Chapter 1: Installation

Prerequisites

Download the latest OpenTK release or checkout the latest source code directly.

OpenTK is a C# library that targets .Net 2.0. To use it, you will need either the Mono or the .Net runtime, plus device drivers for OpenGL (graphics), OpenAL (audio) and OpenCL (compute), depending on which parts of OpenTK you are interested in:

Most operating systems come with one of the above preinstalled. Note that OpenTK does not currently support .Net 1.1 or .Net CF.

Installation

OpenTK 1.0 is distributed in two flavors: a Windows installer and a plain zip archive.

On Windows, simply execute the installer and follow the on-screen instructions. The installer does not require administrator rights, unless you opt to install OpenAL drivers or the GLSL plugin for Visual Studio Professional. Once installation is complete, you will be able to select OpenTK in your project references (double click "References" in the solution pane, select the ".Net" tab, locate OpenTK and click add).

On Linux and Mac OS X, extract the zip archive to a folder of your choice and add OpenTK.dll to your project references. You can find this file under Binaries/OpenTK/Release. Additionally, you should add OpenTK.dll.config to your project and instruct your IDE to copy this file to the output directory. This is necessary for your project to function under Linux and Mac OS X.

Build

You can either build OpenTK through the commandline or through an IDE:

OpenTK can be built in four different configurations: "Release" (shown above), "Debug", "Nsis" and "Documentation". To build a different configuration, use your IDE's configuration manager or modify the commandline invocation like this:

msbuild OpenTK.sln /p:Configuration=Documentation

Important note: MonoDevelop versions prior to 2.6 fail to bootstrap and build OpenTK directly from source control. The workaround is simple: open OpenTK.sln, right click the "Build.UpdateVersion" project and select "Run". You can now build OpenTK as normal.

Dependencies

OpenTK 1.0 requires a C# 2.0 compiler and the following .Net 2.0 libraries:

Additionally, the binding generator requires a C# 3.0 compiler and the following .Net 3.5 library: System.Core.

These dependencies will be reduced in future OpenTK versions.

The "Documentation" build configuration requires doxygen and latex to be present in your path. If you are using Linux, you can install these through your package manager (search for "doxygen", "texlive-core" and "texlive-extras").

The "Nsis" build configuration requires doxygen, latex (refer to "Documentation" configuration, above) and the Nsis installer system. Linux users will also be able to install this through the package manager (search for "nsis").

Linux

Installing Mono

If you are using a recent Linux distribution, all prerequisites for OpenTK projects should be readily available: the Mono runtime and the Mono compilers. Execute "mono --version" and "gmcs --version" and check if the output looks like this:

$ mono --version
Mono JIT compiler version 1.2.6 (tarball)
Copyright (C) 2002-2007 Novell, Inc and Contributors. www.mono-project.com
        TLS:           __thread
        GC:            Included Boehm (with typed GC)
        SIGSEGV:       altstack
        Notifications: epoll
        Architecture:  amd64
        Disabled:      none
 
$ gmcs --version
Mono C# compiler version 1.2.6.0

If one or both of these commands fail, you'll have to install Mono. Mono packages should be readily available through your package manager:

# Ubuntu and other .deb-based distributions
sudo apt-get install mono mono-gmcs
# or
su -c "apt-get install mono mono-gmcs"
 
# Fedora Core and .rpm-based distributions
su -c "yum install mono mono-gmcs"

If no Mono packages are available, or they are outdated (mono --version returns something less than 1.2.6), you should build Mono from source. There is a message in the support forum describing the process of building mono from source here.

Alternatively, you can find use one of the Mono binary packages on the Mono download page.

Using a binary release

Download the latest opentk-x.y.z.zip release from Sourceforge and unzip it.

A new opentk-x.y.z will be created with four subfolders: "Binaries", "Documentation", "Source" and "Installers". Try running the examples binary to make sure everything works alright:

unzip opentk-1.0-2010-10-06.zip
cd opentk-1.0-2010-10-06/Binaries/OpenTK/Release
mono Examples.exe

A new window will hopefully show up, listing all available examples. If not, check the troubleshooting section below.

The "Binaries/OpenTK/Release" folder contains the main OpenTK assembly (OpenTK.dll) and the OpenTK.dll.config file - these are all you need to run OpenTK projects. If you are using MonoDevelop, check the "QuickStart.sln" solution for a ready-to-use project. Last, don't forget to take a look at the release notes contained in the "Documentation" folder.

Troubleshooting

The following error has been reported on Fedora Core 8, when running Examples.exe:

Unhandled Exception: System.TypeInitializationException: An exception was thrown by the type initializer for System.Windows.Forms.Form ---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation. ---> System.TypeInitializationException: An exception was thrown by the type initializer for System.Drawing.GDIPlus ---> System.DllNotFoundException: gdiplus.dll
  at (wrapper managed-to-native) System.Drawing.GDIPlus:GdiplusStartup (ulong&,System.Drawing.GdiplusStartupInput&,System.Drawing.GdiplusStartupOutput&)
  at System.Drawing.GDIPlus..cctor () [0x00000] --- End of inner exception stack trace ---

This is caused by a missing entry in "/etc/mono/config". To correct this issue, open the aforementioned file (you must be root!), and add this line: <dllmap dll="gdiplus.dll" target="/usr/lib/libgdiplus.so.0" />. Now, Examples.exe should work.

Building OpenTK from source

OpenTK's build system relies on xbuild, so you'll need to install that:

# Ubuntu
sudo apt-get install xbuild
 
# Debian
su -c "apt-get install xbuild"
 
# Fedora
su -c "yum install xbuild"

Note that xbuild versions earlier than 2.6.7 are quite buggy and may fail to build OpenTK.

Once xbuild is installed, unzip the source release and cd to the Build folder:

unzip opentk-1.0-2010-10-06.zip
cd opentk-1.0-2010-10-06/
xbuild OpenTK.sln /p:Configuration=Release

Wait a few seconds for the compilation to end, and check the "Binaries" folder that just appeared in the base OpenTK directory.

Windows

OpenTK does not come with any installer or setup. Instead, you download the OpenTK binaries and add a reference to "OpenTK.dll" in your Visual Studio/SharpDevelop/MonoDevelop project. (Unzip the binaries first!)

OpenTK demo
To run all of the OpenTK builtin examples, the following software is required:

  1. .NET2.0 or Mono 1.2.6
  2. OpenAL 2.0.3

This is also the software required for an end-user running an OpenTK application. Note that OpenAL is not strictly required if the application does not use any sound.

OpenTK development
If you want to start developing applications using OpenTK, first make sure the items under "OpenTK demo" are installed, then download a compiler/IDE for .NET/mono. Here are some popular choices:

  1. SharpDevelop
  2. MonoDevelop (bundled in the mono installer)
  3. Visual Studio Express

Setting up an OpenTK application in Visual Studio Express
It is a good idea to add "OpenTK.dll.config" to your project, and make sure the "Copy To Output Folder" (not "compile"!) is set to "Copy Always". The application will run without this on Windows, but not on Linux or Mac OS X.

Last, but not least, make sure the "Copy Local" property is set to true for the OpenTK reference, to simplify the distribution of your application.

Setting up an OpenTK application in SharpDevelop
Include the "OpenTK.dll.config" in your project, if you want it to run under Linux Mac OS X.
Visual explanation:

Troubleshooting

Most problems with running OpenTK-based Applications are related to the target platform missing the proper drivers.

OpenTK requires these components installed:

  • Either Mono or .Net (not both).
  • An OpenGL driver for your graphics card.
  • The OpenAL driver for your Operating System.

Below are links for your convenience. Note: Many of those sites require Javascript enabled to function.

Mono

Novell (Linux, Mac & Windows) http://www.go-mono.com/mono-downloads/download.html

.Net

Microsoft (Windows) http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=...

OpenAL

Note: It doesn't matter what brand your soundcard is, just chose the proper Operating System.

Creative Labs (Mac & Windows) http://www.openal.org/downloads.html
Direct link to download page for Windows: http://connect.creativelabs.com/developer/Wiki/OpenAL%20Installer%20for%...
Strangesoft (Linux) http://kcat.strangesoft.net/openal.html

OpenGL

ATi (Linux, Mac & Windows) http://ati.amd.com/support/driver.html
NVIDIA (Linux & Windows) http://www.nvidia.com/Download/index.aspx?lang=en-us
Intel (Windows) http://downloadcenter.intel.com/
Intel (Linux) http://intellinuxgraphics.org/download.html
Mesa 3D (software rendering) http://sourceforge.net/project/showfiles.php?group_id=3

If you have a laptop with an Nvidia card, you can obtain updated drivers through: http://www.laptopvideo2go.com

Last edit of the links: March 2008

Tags for searches:
help problem error outdated trouble crash fail failure exception abort opengl openal driver ati intel nvidia

Distributing OpenTK applications

The most important dependency by far is the Mono/.Net framework. If you need to support users that might not have that installed, the best solution is to embed the Mono runtime into a small launcher (example code).

Additionally, on Windows, you will typically need to install OpenAL drivers:

  • either distribute the official oalinst.exe from Creative (requires admin rights to install)
  • or distribute OpenAL Soft (plain dll, no admin rights required).

There is no such redistributable for OpenGL drivers - the user will have to install those on his own.

On Linux, users will typically have OpenAL and OpenGL pre-installed. If you generate distro-specific packages, then list AL/GL as dependencies and the package manager will take care of the rest. If you provide distro-agnostic packages, then you can either expect the user to have AL/GL preinstalled (which is quite reasonable) or you can bundle your own version of OpenAL (use the OpenAL Soft link, above). Most commercial games follow the distro-agnostic package approach. Many include libopenal.so, too.

Apart from those, OpenTK uses either core OS components which are always available (e.g. user32.dll or libX) or optional components with transparent fallbacks (e.g. libXi).

In any case, do try to fail smoothly if AudioContext or GraphicsContext construction fails. It is also a good idea to check the OpenGL version and bail out early if too low.