# Installation Advanced instructions for compiling MoCSI locally, including everything you need to develop new features. MoCSI builds on **Linux, macOS, and Windows**. Pick your platform to jump straight to the steps:
🐧 Linux apt + gcc + CMake + make 🍎 macOS Homebrew + CMake + make 🪟 Windows Visual Studio + CMake GUI
## Requirements MoCSI builds with [CMake](https://cmake.org/), a C++ compiler (GCC / Clang / MSVC), [git](https://git-scm.com/), and [Python](https://www.python.org/) for the config generator. Versions known to work: | Tool | Minimum | Notes | |------|---------|-------| | **CMake** | 3.10 | Set by `cmake_minimum_required` in `CMakeLists.txt`. | | **C++ compiler** | Must support **C++20** | GCC ≥ 10, Clang ≥ 11, MSVC ≥ 19.29 (Visual Studio 2019 16.10+, or VS 2022). | | **Python** | 3.8 | For the config generator. CI exercises Python 3.13. | | **git** | any recent | For cloning the repository. | Optional features (VTK, CSPICE, MPI) are **disabled by default** and must be enabled explicitly via CMake flags — see [*Installing additional libraries*](#installing-additional-libraries-optional) below. ## Requirements ### Mandatory - [CMake](https://cmake.org/) **≥ 3.10** - A C++20 compatible compiler - Linux: GCC or Clang - macOS: Apple Clang or GCC - Windows: MSVC (Visual Studio) - [git](https://git-scm.com/) - [Python](https://www.python.org/) (≥ 3) ### Optional - [CSPICE](https://naif.jpl.nasa.gov/naif/toolkit.html) — accurate orbital data - [VTK](https://vtk.org/) — shape models and visualization - MPI implementation (e.g. OpenMPI, MPICH) --- ## CMake configuration options All optional features are **OFF by default**. | Option | Default | Description | |------|--------|------------| | `INCLUDE_CSPICE` | OFF | Enable CSPICE support | | `INCLUDE_VTK` | OFF | Enable VTK support | | `INCLUDE_MPI` | OFF | Build MPI executable (`mocsi_mpi`) | | `CSPICE_DIR` | — | Path to CSPICE installation (required if CSPICE is enabled) | Example: ```bash cmake .. -DINCLUDE_CSPICE=ON -DINCLUDE_VTK=ON ``` --- ## Minimum installation (no optional libraries) Each tab below walks through the minimum steps to clone, configure, and build MoCSI without SPICE or VTK. ::::{tab-set} :::{tab-item} Linux 1. Install CMake, a C++ compiler (we recommend gcc), git and Python: ```bash sudo apt-get update && sudo apt-get install -y build-essential cmake git python3 python3-pip ``` 2. Navigate to a preferred folder, clone the repository, and enter it: ```bash git clone https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi.git cd mocsi ``` 3. Create the build directory and run CMake + make: ```bash mkdir build cd build cmake .. make ``` The final executable is called `mocsi` and lives in `build/`. See the [Quickstart](../quick_start/quick_start.md) for how to run it. ::: :::{tab-item} macOS 1. Install CMake, a C++ compiler (we recommend gcc), git and Python: ```bash brew install cmake gcc git python ``` 2. Navigate to a preferred folder, clone the repository, and enter it: ```bash git clone https://gitlab.git.nrw/uni-ms/ag-gundlach/public/mocsi.git cd mocsi ``` 3. Create the build directory and run CMake + make: ```bash mkdir build cd build cmake .. make ``` The final executable is called `mocsi` and lives in `build/`. See the [Quickstart](../quick_start/quick_start.md) for how to run it. ::: :::{tab-item} Windows (MSVC + CMake GUI) 1. Install [git](https://git-scm.com/downloads/win), [CMake](https://github.com/Kitware/CMake/releases/download/v4.1.1/cmake-4.1.1-windows-x86_64.msi), [Python](https://www.python.org/downloads/), and [Visual Studio](https://visualstudio.microsoft.com/de/downloads/). When opening Visual Studio for the first time, select **Desktop Development with C++** to install the MSVC compiler. 2. Navigate to a preferred folder and clone the repository. 3. Open the **CMake GUI**. Click **Browse Source** and select the MoCSI root folder. Create a new folder for your build files and select it via **Browse Build**. 4. Click **Configure**. You'll be prompted to pick a generator — choose *Visual Studio 17 2022* (or your version) and hit **Finish**. After a few warnings you should see "Configuration done". 5. Click **Generate**. CMake finishes with "Generate done". 6. Click **Open Project** to open the generated solution in Visual Studio. 7. In the top bar, pick your compilation configuration: **Release** for the highest optimization level, or **Debug** for testing. 8. In the **Solution Explorer**, right-click **ALL_BUILD** and choose **Build**. It should finish with "Build completed". 9. Your executable `mocsi.exe` lives in `build/Debug/` or `build/Release/` depending on the configuration you picked. See the [Quickstart](../quick_start/quick_start.md) for how to run it. ::: :::: ## Installing additional libraries (optional) Three build-time features extend what MoCSI can do. All are **OFF by default** — enable what you need with the CMake flags below. | Feature | Version | Default | How to enable | What it unlocks | |---------|---------|---------|---------------|-----------------| | [VTK](https://vtk.org/) | 9.x | Off | Install system VTK (see below) and pass `-DINCLUDE_VTK=ON` to CMake | Reading shape-model mesh files | | [SPICE](https://naif.jpl.nasa.gov/naif/toolkit.html) | latest NAIF release | Off | Pass `-DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice` to CMake | Accurate orbital geometry from ephemerides | | MPI | any (Open MPI / MPICH / MS-MPI) | Off | Pass `-DINCLUDE_MPI=ON` to CMake (MPI library must be installed) | Parallel execution across processes | ### SPICE (for accurate orbital data) ::::{tab-set} :::{tab-item} Linux Download the correct [CSPICE toolkit](https://naif.jpl.nasa.gov/naif/toolkit_C_PC_Linux_GCC_64bit.html) into your preferred folder. With gcc: ```bash curl -O https://naif.jpl.nasa.gov/pub/naif/toolkit/C/PC_Linux_GCC_64bit/packages/cspice.tar.Z uncompress cspice.tar.Z tar -xf cspice.tar ``` Then re-run the CMake command from step 3, with the SPICE flags: ```bash cmake .. -DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice/ ``` All other steps remain the same. ::: :::{tab-item} macOS Download the correct [CSPICE toolkit](https://naif.jpl.nasa.gov/naif/toolkit_C_MacIntel_OSX_AppleC_64bit.html) into your preferred folder: ```bash curl -O https://naif.jpl.nasa.gov/pub/naif/toolkit/C/MacIntel_OSX_AppleC_64bit/packages/cspice.tar.Z uncompress cspice.tar.Z tar -xf cspice.tar ``` Then re-run the CMake command from step 3, with the SPICE flags: ```bash cmake .. -DINCLUDE_CSPICE=ON -DCSPICE_DIR=/path/to/cspice/ ``` All other steps remain the same. ::: :::{tab-item} Windows Download the correct [CSPICE toolkit](https://naif.jpl.nasa.gov/naif/toolkit_C_PC_Windows_VisualC_64bit.html) and extract the files to a directory of your choosing. Open the CMake GUI and click **+ Add Entry** twice. First, enable CSPICE: ``` Name: INCLUDE_CSPICE Type: BOOL Value: ON ``` Then, if your SPICE toolkit is at `D:/cspice`, set: ``` Name: CSPICE_DIR Type: Path Value: D:/cspice ``` Click **OK**, then continue from step 4 of the Windows minimum-install instructions. (If you already picked a compiler, clicking **Configure** skips the prompt and jumps straight to the configuration step.) ::: :::: ### VTK (for shape-model support) ::::{tab-set} :::{tab-item} Linux Install VTK: ```bash sudo apt-get install -y --no-install-recommends libvtk9-dev ``` Re-run the CMake command from step 3 with the VTK flag: ```bash cmake .. -DINCLUDE_VTK=ON ``` ::: :::{tab-item} macOS Install VTK via Homebrew: ```bash brew install vtk ``` Re-run the CMake command from step 3 with the VTK flag: ```bash cmake .. -DINCLUDE_VTK=ON ``` ::: :::{tab-item} Windows Download the latest [VTK release](https://vtk.org/download/) and extract it to a folder of your choosing. Follow the same MSVC + CMake GUI flow, but select the VTK folder as *Source* and a new folder as *Build*. The Visual Studio build takes a while — make sure you pick the same configuration (**Release**/**Debug**) you plan to use for MoCSI. After VTK builds successfully, add its library folders to your `Path` system variable: 1. Open Windows system variables, select **Path**, click **Edit**. 2. Add the `../bin/` and `../lib/Release` (or `../lib/Debug/`) folders from your VTK install. 3. Confirm and exit. Then re-open the CMake GUI for MoCSI and click **+ Add Entry** to enable VTK: ``` Name: INCLUDE_VTK Type: BOOL Value: ON ``` Click **OK** and continue from step 4 of the Windows minimum-install instructions. ::: :::: ### MPI (for parallel execution) When MPI is enabled, the executable is named **`mocsi_mpi`** (the serial `mocsi` is still built alongside). ::::{tab-set} :::{tab-item} Linux Install an MPI implementation, e.g. Open MPI: ```bash sudo apt-get install -y openmpi-bin libopenmpi-dev ``` Re-run the CMake command from step 3 with the MPI flag and `mpicxx`: ```bash cmake .. -DINCLUDE_MPI=ON -DCMAKE_CXX_COMPILER=mpicxx ``` ::: :::{tab-item} macOS Install Open MPI via Homebrew: ```bash brew install open-mpi ``` Re-run the CMake command from step 3 with the MPI flag and `mpicxx`: ```bash cmake .. -DINCLUDE_MPI=ON -DCMAKE_CXX_COMPILER=mpicxx ``` ::: :::{tab-item} Windows Install [Microsoft MPI](https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi) (both the SDK and the runtime). In the CMake GUI, click **+ Add Entry** to enable MPI: ``` Name: INCLUDE_MPI Type: BOOL Value: ON ``` Click **OK** and continue from step 4 of the Windows minimum-install instructions. ::: :::: ## Tests Tests are built automatically alongside the main executable. CSPICE-dependent tests are skipped when `INCLUDE_CSPICE=OFF`. Runtime test data is copied into `build/tests/` at configure time.