# Installation

Advanced instructions for compiling MoCSI locally, including everything you need to develop new features.

:::{tip}
Don't want to compile anything? Run the prebuilt **Docker image** instead — it ships both `mocsi` and `mocsi_mpi` with VTK + CSPICE included. See [Running MoCSI with Docker](docker.md).
:::

MoCSI builds on **Linux, macOS, and Windows**. Pick your platform to jump straight to the steps:

<div class="box-container">
  <a class="box-card" href="#minimum-installation-instructions">
    <span class="box-icon">🐧</span>
    <b>Linux</b>
    <span class="box-sub">apt + gcc + CMake + make</span>
  </a>
  <a class="box-card" href="#minimum-installation-instructions">
    <span class="box-icon">🍎</span>
    <b>macOS</b>
    <span class="box-sub">Homebrew + CMake + make</span>
  </a>
  <a class="box-card" href="#minimum-installation-instructions">
    <span class="box-icon">🪟</span>
    <b>Windows</b>
    <span class="box-sub">Visual Studio + CMake GUI</span>
  </a>
</div>

## 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. |

The config generator runs on a plain Python install with no extra packages. For its optional **`<Tab>` path-completion**, **Windows** additionally needs the [`pyreadline3`](https://pypi.org/project/pyreadline3/) package (`readline` is built in on Linux/macOS). Install the script's Python dependencies with:

```bash
pip install -r configs/python_scripts/requirements.txt
```

This is a no-op on Linux/macOS and pulls in `pyreadline3` only on Windows. Without it, Tab simply inserts a tab character.

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.