Special instructions on compiling OpenSpace on macOS
This page describes the details of how to compile OpenSpace on macOS.
For a more general overview for all platforms, see Getting Started Guide: Compiling OpenSpace
- Install the Development Tools
- Install or build the Libraries
- Build OpenSpace
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:
Homebrew is billed as "the missing package manager" for macOS. Homewbrew installs the stuff you need that Apple didn't. It's easy to install and uninstall packages with Homebrew. See http://brew.sh for instructions and to download and install Homebrew.
Once you have installed homebrew you can use it to install other useful utilities and libraries. Specifically, to build OpenSpace you will need to do the following:
brew install glew brew install boost brew install freeimage brew tap osgeo/osgeo4mac && brew install gdal2
Please make use that the correct GDAL version is installed, as OpenSpace uses some recent features. We recommend a version that is newer than
port install glew boost freeimage gdal +curl
See below for more information about freeimage3.
Xcode is the Interactive Development Environment (IDE) tool for Mac. It's how you compile code on a Mac. It's a free install from the Mac App Store.
Get the source with Git
Checkout OpenSpace/OpenSpace recursively using git.1 You probably want the
master branch . If you are using
git via the command line the command is:
git clone --recursive https://github.com/OpenSpace/OpenSpace
If you forget to clone with
--recursive you can recover with a set of git commands (once only) to initialize and update (clone, the first time) the appropriate submodules. The command (starting from the top level directory) is:
git submodule update --init --recursive
You only need to
--init once, but you should do the recursive update anytime you checkout a different branch from the repository. (You also should do the
git submodule --init if/when the submodules on which OpenSpace relies change (eg. a new one is added).)
Configure with CMake
- Change to the OpenSpace directory just created by cloning the git repo, and create a
builddirectory. (Your Xcode project file will live there.)
- Run the CMake utility, which will eventually generate the Xcode project file. There are actually two ways you can do this:
Run the GUI version of CMake (the CMake App that you installed from http://www.cmake.org). Set the Build directory to the subdirectory you just created, and set the Source directory to the directory just above it. Press the "Configure" button, and deal with any problems.
Run the command line version of CMake which uses the curses library5(#curses), called
ccmake(note the extra letter 'c'). In the Terminal app, change to the OpenSpace/build subdirectory and give the command
ccmake, passing it the path to the source directory (which is just the directory above, aka the ".." directory). You also want to tell it you will use Xcode as the generator (otherwise the default is to create Unix Makefiles). Thus:
ccmake -G Xcode ..
- If you built Boost from source then you need to tell CMake where it is.
- Do the "configure" step in CMake. For the GUI version simply press the "Configure" button. For the curses CLI version press "c".
- Fix any other configuration errors. You may have to tweak and adjust and re-run the configure step several times.
Generate with CMake
- Do the "generate" step in CMake. This will create the Xcode project file, in the build subdirectory. Using the GUI version simply press the "Generate" button. For the curses CLI version press "g".
Open the Xcode OpenSpace project
build/OpenSpace.xcodeproj. Since you are already doing so much with the CLI you can do this with
Select the target/scheme
ALL_BUILD(if it isn't already) and build it (pull down Product -> Build)
Verify build type (
Debug) by browsing to Product -> Scheme -> Edit Scheme -> Info tab -> Build Configuration.
Your source code and bin directory will be in the top-level OpenSpace directory (just above the build subdirectory)
open -n OpenSpace.app <args>from
- 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 --recursiveand/or use the
git submodulecommands. The
submodulecommands will need to be run in both the main repository and
- Feel free to use a git client app instead, like Xcode or SourceTree. Make sure you get your submodules though.
- Did I mention to make sure you get your submodules?
ccmakeis the curses interface to CMake.
- Create a build directory to store the configuration files anywhere outside the source files. This is where the Xcode project file will be generated by CMake. It's not required to be named
buildbut that's common. You can keep it in the top level of your repository.
- It's easiest to run
ccmakein the build directory, like so:
cd <build dir>; ccmake -G Xcode <repo dir>
cto configure your CMake files. Some configurations will require you to run the configure multiple times before you can generate.
- Scroll up and down using the arrow keys, press Enter/Return to toggle or edit a value, again to confirm it.
- When you make changes, confgure with
cagain: you won't be able to generate the build files until you do.
twill toggle advanced mode.
gwill generate the files.
eto exit the errors/warning/help screen and take you back to the configuration so you can update it as necessary.
qwill quit without generating changes.
- When in doubt,
rmin your CMake build directory and start again.
Curses is the Unix "cursor functions" library, which can be used to create a sort of Graphical User Interface (GUI) in a terminal environment. Thus the
ccmake version of CMake acts like the full GUI App, but runs in a terminal window.