<!-- TITLE: Windows --> <!-- SUBTITLE: 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](#tools) 1. Git client (one of SourceTree, Git Kraken, SmartGit, or Git for Windows) 1. [CMake](#cmake) 1. [Visual Studio](#visual-studio-2017) 1. [Build/Install Libraries](#buildinstall-libraries) 1. [Boost](#boost) 1. [Build OpenSpace](#build-openspace) 1. [Notes](#notes) ## Development Tools ### Git Client The source code for OpenSpace is distributed via [GitHub](https://github.com/OpenSpace/OpenSpace), 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 1. SmartGit 1. Git GUI (a part of the basic git [download](http://git-scm.com/download) or Visual Studio) ### Visual Studio 2017 [Visual Studio 2017](http://www.visualstudio.com) 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](https://cmake.org/download/) - 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](https://sourceforge.net/projects/boost/files/boost-binaries/1.64.0/boost_1_64_0-msvc-14.1-64.exe/download), 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`. 1. Set "Where to build the binaries:" to the build subdirectory, for example: `develop\OpenSpace\build` 1. 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". 1. Press the `Generate` button. This creates the Visual Studio Solution (`.sln`) file and supporting Project (`.vcxproj`) files. 1. 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` 1. Select either the "Launcher" or the "OpenSpace" project as a startup project via right click in the "Solution Explorer" and build them 1. 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<cmake flag>: ``` 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](https://help.github.com/articles/generating-an-ssh-key/) 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.