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

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

Optional features (VTK, SPICE, MPI) have their own setup — see [*Installing additional libraries*](#installing-additional-libraries-optional) below.

## Minimum installation instructions

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. Enable what you need — each has its own setup below.

| Feature | Default | How to enable | What it unlocks |
|---------|---------|---------------|-----------------|
| [VTK](https://vtk.org/) | Auto-detect | Install system VTK (see below) | Reading shape-model mesh files |
| [SPICE](https://naif.jpl.nasa.gov/naif/toolkit.html) | Off | Pass `-DCSPICE_DIR=/path/to/cspice` to CMake | Accurate orbital geometry from ephemerides |
| 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, pointing to SPICE:

```bash
cmake .. -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, pointing to SPICE:

```bash
cmake .. -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**. 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
```

When running CMake at step 3, it automatically discovers the installed VTK and wires it into the build.
:::

:::{tab-item} macOS

Install VTK via Homebrew:

```bash
brew install vtk
```

When running CMake at step 3, it automatically discovers the installed VTK and wires it into the build.
:::

:::{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.

CMake will now find VTK automatically at configuration time. From there, continue from step 4 of the Windows minimum-install instructions.
:::

::::