Getting Started Guide: Compiling

General information about compiling OpenSpace from scratch

This page outlines the steps and resources required to compile OpenSpace on all platforms. You don't need to follow these instructions just to download and use an OpenSpace binary (when packages become available) but you currently need to be able to compile from source to get the latest version of OpenSpace.

There are also separate pages with more particular information for each platform:

0. Hardware requirements

  • OpenGL 3.3: Most new graphics cards have this capability, but sometimes you need to update your drivers. Many older machines also have this capability, so this is not a hard requirement to fulfill
  • A mouse makes navigation easier than using a trackpad, since you need both left and right mouse buttons
  • Enough disk space (all numbers approximate):
    • 1 GB of disk space to clone the GitHub repository
    • 650 MB of additional disk space to build OpenSpace
    • 10+ GB of disk space to hold the current OpenSpace dataset (about half for Scenes and half for SPICE kernels). Expect that to grow as time goes on.

1. Developer Tools

To compile OpenSpace on any platform you will need a Git client, CMake, and a C++ compiler.

Git Client

see Git for information about a Git client

CMake

CMake is a multi-platform project-generation tool. OpenSpace uses CMake so that we can more easily configure and compile OpenSpace on various platforms. We require CMake version 3.8 or above as C++17 support was only introduced in that release. If you favor the command line you can use the cmake command, but you might also like to know that you can use ccmake, which is CMake with an interactive curses interface.

Compiler / IDE

  • Visual Studio 2017 is the standard Interactive Development Environment (IDE) for Windows
  • XCode is the standard IDE on macOS
  • On Linux you can install either g++ or clang compilers, using either yum or apt-get, and use either emacs or vim, or any other editor of your choice.

OpenSpace is written in C++17 and thus requires modern compiler versions that support a large portion of the new standard. Thus we require the following versions of the compiler:

  • Windows: MSVC Visual Studio 15.7 (Visual Studio 2017)
  • macOS: clang (clang-802.0.42) (shipped with Xcode on Sierra)
  • Linux gcc (7.1) (installed via apt-get link

2. Required libraries

  • SGCT is the Simple Graphics Cluster Toolkit, which was developed at C-Research, Linköping University. SGCT is included as a submodule in OpenSpace, so it will automatically be updated and built.
  • GDAL is the Geospatial Data Abstraction Library. For Windows, this library is contained in the repository, otherwise you it is available via apt-get or homebrew or MacPorts. Suggested version: 2.1.2 or above

3. Compiling

Roughly speaking, here are the steps required to compile OpenSpace:

  1. Clone the Git repository including all submodules. If you use the commandline for this, a standard command would be: git clone --recursive https://github.com/OpenSpace/OpenSpace
  2. Check-out the master branch (read Branching Model for more information about git branches).
  3. Start CMake and "Configure" using the CMakeLists.txt file in the OpenSpace directory
  4. Once you have the configuration set with no errors, use CMake to "generate" a project file
  5. Compile

Platform-specific Instructions

More complete details specific to a given platform are given here:

4. After compiling

  • See the Getting Started Guide: Using OpenSpace page for how to get started with running and using OpenSpace. The first time you run OpenSpace you should run the Launcher and sync at least one Scene to be able to view something.
  • The Coding Style describe the general coding guidelines that are applicable to the Ghoul and OpenSpace repository
  • See the OpenSpace Layout page for more information about the structure of OpenSpace directories
  • See the Deploy to a Windows Machine page for additional information about what goes where on Windows (and how to copy from one machine to another).
  • The source code is written in C++17 with the feature set supported by Visual Studio 2017.7. The available features are detailed here
  • Developers, before committing to the repository, read the post about Structuring commit messages. In general you can push to the feature branch you have been working on, but do not push directly to the master branche. Instead, send a Pull Requests.
  • Some useful information about C++ can be found in the form of C++ Core Guidelines and Exception Handling

5. FAQ

Q:

CMake Error at ext/ghoul/CMakeLists.txt:74 (include):
 include could not find load file:

   src/CMakeLists.txt


You have called ADD_LIBRARY for library Ghoul without any source files. This typically indicates a problem with your CMakeLists.txt file
CMake Error at ext/ghoul/CMakeLists.txt:304 (find_package):
 By not providing \"FindGLM.cmake\" in CMAKE_MODULE_PATH this project has
 asked CMake to find a package configuration file provided by \"GLM\", but
 CMake did not find one.

 Could not find a package configuration file provided by \"GLM\" with any of
 the following names:

   GLMConfig.cmake
   glm-config.cmake

 Add the installation prefix of \"GLM\" to CMAKE_PREFIX_PATH or set \"GLM_DIR\"
 to a directory containing one of the above files.  If \"GLM\" provides a
 separate development package or SDK, be sure it has been installed.

A: The Git clone was not done recursively and thus the Ghoul CMakeLists.txt file is missing. Please reclone the repository using the --recursive flag