Compiling MinVR and its dependencies

Table of Contents

• Downloading the MinVR source code
• Dependencies
  • Building Dependencies
• Configuring MinVR with CMake
  • Using CMake from the command line (recommended)
  • Using the CMake GUI
  • Build Options
• Compiling MinVR
  • Compiling on Linux
  • Compiling on Mac OS X
  • Compiling on Windows
• Building documentation
• Using MinVR

This is about compiling and installing MinVR and its dependencies. For information on how to use MinVR when writing your own programs, start with the Using MinVR Tutorial.

Downloading the MinVR source code

The MinVR source code is hosted on Github. The easiest way to download the source is to clone the git repository to your local machine. This can be accomplished using command-line git with the following code:

$ cd <your_repo_root>
$ git clone https://github.com/MinVR/MinVR.git

Alternatively, you may download a zip file or tarball of the source from the MinVR webpage or directly from Github.

Dependencies

MinVR's core library has one required dependency and several optional ones depending on which input devices you plan to use. The individual App Kits also have their own dependencies for their specific graphics toolkits.

Core Library Dependencies:

• Boost version >= 1.54 (www.boost.org) - Required
• VRPN version >= 7.30 (www.cs.unc.edu/Research/vrpn/) - Optional Used to connect with a variety of tracking devices.
• TUIO version >= 1.4 (TUIO_CPP-1.4.zip) - Optional Used for multi-touch.
• 3DConnexion SpaceNavigator driver - Optional Used with the SpaceNavigator 3D mouse.
  • Windows: 3DxSoftware (64-bit)
  • Mac OSX: 3DxWare 10 for OSX
  • Linux: libspnav-0.2.2

App Kit Dependencies:

• AppKit_GLFW
  • glfw version >= 3.0.1 (http://github.com/bretjackson/glfw - Required Note: This is not the official glfw repository. In order to support creating an Nvidia Affinity context to choose the rendering GPU on Windows, we have slightly modified the source. The official glfw version will work if you do not use the useGPUAffinity window setting in your vrsetup file. See Creating a setup configuration for more detail on the useGPUAffinity parameter.

Building Dependencies

There are two options for building MinVR with its dependencies. The first option is to download them from the links above and build them yourself. You will then need to set a variety of environment variables for each one so that cmake can find their install locations. The second approach (the recommended one) is that you set the cmake variable BUILD_DEPENDENCIES to ON (the default). In this case, cmake will attempt to find versions of each dependency on your computer. If a dependency is not found, it will download the source automatically and build it.

If you choose to let the cmake build system download and build the dependencies, they are downloaded to the dependencies folder in the root of your source directory. When built, they are copied to the MinVR install location.

Configuring MinVR with CMake

MinVR uses CMake to configure its build system. If you are on a Linux system you should be able to get the CMake package from your package manager. If you are on Windows or Mac OS X you can download an installer directly from the CMake website

Using CMake from the command line (recommended)

Our recommended approach is to generate the build files using CMake from the command line. If you are on a Windows system, we recommend downloading Cygwin. In order to make the build process easier, we have included a Makefile. The Makefile will create a new directory in the root of the source directory called build, where it will generate the build files using CMake.

By default the Makefile will choose a CMake generator depending on your system architecture. If you are Windows, it generates a Visual Studio 2010 64-bit solution and project files. On Mac, it generates an XCode project, and on Linux it generates standard Makefiles. To modify the type of project files that are generated, open the Makefile and change the CMake generator line.

For example to generate a Visual Studio 2012 project file, change the cmake line to:

cmake ../ -G "Visual Studio 11 Win64"

Additional CMake build options can also be added to the Makefile to customize your build. See Build options.

Using the CMake GUI

If you are using the GUI version of CMake, create a build directory in the root of the MinVR source tree. Set the cmake build location to this build directory, and the cmake source location to the root of the MinVR source tree. Click Configure and adjust any options you want. Click Configure again to save your changes, and then click Generate to create the project files.

Build Options

There are several CMake build options that can be set to customize your MinVR build. You should set the input device options and app kit options based on your intended configuration. If you are using the provided Makefile to build, these options are mostly easily set by changing them at the top of the CMakeLists.txt file in the root of the MinVR source directory. If you are using the CMake GUI, these can be set after clicking Configure.

The following options specify which input device libraries to link against:

• USE_VRPN determines whether the VRPN library will be used to connect with trackers and other input devices
• USE_TUIO determines whether the TUIO library will be included to receive multi-touch events
• USE_SPACENAV determines whether the 3DConnexion SpaceNavigator mouse will be supported

The following options specify which App Kits are build. It is fine to build MinVR with multiple App Kits:

• USE_APPKIT_GLFW specifies that the GLFW based App Kit should be built
• USE_APPKIT_GLUT specifies that the Glut App Kit should be built

The following options specify build parameters:

• BUILD_USE_SOLUTION_FOLDERS sets Visual Studio to organize the projects into folders that make the directory structure more organized
• BUILD_EXAMPLES determines whether the example projects for each App Kit are built
• BUILD_DEPENDENCIES determines whether the dependecies are automatically downloaded and built if a version is not already found on the system
• BUILD_DOCUMENTATION determines whether the Doxygen documentation is built.

To change MinVR's install location set the CMAKE_INSTALL_PREFIX variable. This is currently specified in the Makefile as a directory called install in the root of the source tree.

Compiling MinVR

Compiling MinVR is dependent on the system architecture and CMake generator you specified when configuring.

Compiling on Linux

To compile MinVR on linux, we have included helper targets in the root level MakeFile.

To build the debug version:

$ cd <MinVR_root_dir>
$ make debug

To build the release version

$ cd <MinVR_root_dir>
$ make opt

To install:

$ cd <MinVR_root_dir>
$ make install

Compiling on Mac OS X

After configuring, the CMake build system will generate an MinVR XCode project. Open the XCode project found in the build folder.

To build the debug version in XCode, click Product menu -> Build

To build the release version in XCode:

• Click Product menu -> Scheme -> Edit Scheme...
• In the Info tab, change Build Configuration to Release
• Click Product menu -> Scheme -> ALL_BUILD
• Click Product menu -> Build

To install after building, click Product menu -> Scheme -> install

Compiling on Windows

On Windows, the CMake default in the Makefile is to generate a Visual Studio solution file. Open the solution called build/MinVR.sln.

In the navigation menu at the top of the screen click Build -> Build Solution. If you selected MinVR to build dependencies for you, this will take a while. The dependencies will be automatically downloaded and installed in the install location. You will likely get some projects that fail to build the first time because of missing dependencies. Just rerun build after everything finishes the first time and everything should build correctly.

To build release, change the selector at the top of the screen to Release, and rebuild everything.

Right-click the INSTALL project in the Solution Explorer and select Build. This will copy the files to the install location.

Building documentation

You can build the doxygen documentation of MinVR in order to have a local up-to-date api documentation. For this, you need Doxygen (http://www.doxygen.org). Once this is installed, if the CMake option BUILD_DOCUMENTATION is set to ON, CMake will attempt to find the Doxygen executable when configuring. If CMake can not find the executable you can set it manually:

    `DOXYGEN_EXECUTABLE` : path to doxygen.exe (e.g. C:/Program Files (x86)/doxygen/bin/doxygen.exe)

Using MinVR

After compiling, to start using MinVR in your projects, go to the Using MinVR tutorial.