Windows

Special instructions on compiling OpenSpace on Windows platforms

This page began as the Few-Frills How-To for building on Windows 10, but now we are trying to fill it in with more details. Please help give us feedback on what needs to be improved.

Quick summary:

  1. Development Tools
    1. Git client (one of SourceTree, Git Kraken, SmartGit, or Git for Windows)
    2. CMake
    3. Visual Studio
  2. Build/Install Libraries
    1. Boost
  3. Build OpenSpace
  4. Notes

Development Tools

Git Client

The source code for OpenSpace is distributed via GitHub, and so you will need a Git client to obtain a copy of the source code. OpenSpace uses git submodules, so a client which can handle these gracefully is preferred. These include:

  1. SourceTree
  2. SmartGit
  3. Git GUI (a part of the basic git download or Visual Studio)

Visual Studio 2017

Visual Studio 2017 is the standard Interactive Development Environment (IDE) for Windows. Version 15.7 or higher is required. The "community" version is a free download. When you install it, be sure to select "Custom" configuration and select the C++ compiler -- it is not included by default. You can also select a git client here ("Git GUI"). Installation could take a while (like an hour or so, depending on the machine).

CMake

  • Download and run the CMake installer
  • If you are upgrading from version 3.4 or earlier, uninstall first. We require CMake 3.8 or newer.

Build/Install Libraries

Advice on directory structure

Building OpenSpace will be easier if you follow a few guidelines about where you put the source code and where you build OpenSpace the the libraries it needs.

  • OpenSpace depends on several other software components, which are loaded as git submodules when you do a recursive clone. These are all in the ext/ subdirectory. One of these is a library called Ghoul, and Ghoul has it's own submodules, in ext/Ghoul/ext/.
  • OpenSpace also depends on some libraries that are separate, like Boost. These should be built in a "nearby" directory. So one strategy that could make things easier is to create a common directory (we'll called it develop and then clone the various components in that directory). Then in this example OpenSpace would be in develop/OpenSpace, and Boost would be in develop\Boost.

Build Boost

You can download the newest Boost version here, which will install all necessary Boost components. For later ease of use, it is recommended to add BOOST_PATH to the list of environment variables (see above) and point it to the install directory (likely C:\local\boost_1_64_0)

Build OpenSpace

Get via Git

Checkout OpenSpace recursively using SourceTree, SmartGit, or the command line. The command line git command is:
git clone --recursive https://github.com/OpenSpace/OpenSpace

Build OpenSpace

  1. Open CMake and set "Where is the source code:" to the directory you just cloned from github, for example develop/OpenSpace.
  2. Set "Where to build the binaries:" to the build subdirectory, for example: develop\OpenSpace\build
  3. Press the Configure button in CMake. Expect errors, which you will then correct:
    • The first time you press Configure you are asked to select a "generator" for the project. Select "Visual Studio 15 2017 Win64" (the Win64 is the important part)
    • Configure again, as needed, until you resolve all the errors (except anything that says "this warning is for project developers")
    • You can start over by pulling down "File->Delete Cache".
  4. Press the Generate button. This creates the Visual Studio Solution (.sln) file and supporting Project (.vcxproj) files.
  5. The generated solution file can be opened via Open Project. Otherwise, navigate to the build directory and open the main Solution file, called OpenSpace.sln
  6. Select either the "Launcher" or the "OpenSpace" project as a startup project via right click in the "Solution Explorer" and build them
  7. You can start either application from within Visual Studio or by navigating to OpenSpace/bin/openspace

Notes

CMake

  • Create your build directory to store the configuration files anywhere outside the source files. It's not required to be named build but that's common. You can keep it in the top level of your repository.
  • Unlike the Mac & Linux platforms, the Windows Debug version will run much slower than its Release counterpart due to additional tests by the standard library. The RelWithDebInfo build option will enable optimizations but also makes debugging inside of Visual Studio possible.
  • When in doubt File -> Delete Cache and start again.
  • To execute cmake from visual studio command line, cmake args must be passed with -D:
        cd develop/OpenSpace 
        mkdir build & pushd build
        cmake -DBOOST_ROOT=C:\Users\<user>\Documents\boost_1_63_0 -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 15 2017 Win64" ..
        popd
        cmake --build build --config Release

Git

  • You might find it easier to use SSH instead of HTTPS, especially if you're using Two-Factor Authentication with GitHub.
  • If you use the command line interface for git, remember that OpenSpace has many submodules. You'll want to git clone --recursive and/or use the git submodule commands. The submodule commands will need to be run in both the main repository and ext/ghoul.

Visual Studio

  • When switching between Release and Debug configuration in Visual Studio, there has been cases where some targets aren't getting rebuilt properly. Therefore, highlight tinyxml2static and VRPN in the solution, right click and select Rebuild Selection after changing build configuration.

FAQ

If Windows is complaining that it cannot find the VCOMP120.dll, download https://www.microsoft.com/en-us/download/details.aspx?id=40784 the Visual Studio 2013 Redistributable. On Windows 10, this is not installed by default anymore.