# Developer Build Guide

This page records the supported staged build workflow during the current SDK migration.

## Platform Policy

- Linux is the Tier 1 high-performance and release platform.
- Windows is supported for Intel oneAPI based builds when required by applications.
- macOS is development-only and CPU-only. It is intended for local development, examples, and small smoke checks.

## Toolchains

| Platform | Compiler | Math backend | FFT backend | MPI |
| --- | --- | --- | --- | --- |
| Linux | Intel `icx`/`icpx`/`ifort` or `ifx` | oneMKL | MKL FFT | Intel MPI or compatible MPI |
| Windows | Intel `icx`/`ifx` | oneMKL | MKL FFT | Intel MPI |
| macOS | Homebrew `gfortran` with AppleClang C/C++ | OpenBLAS | user-installed FFTW | Homebrew OpenMPI |

Do not use Intel compiler + oneMKL as the macOS route. Do not bundle FFTW into SDK packages. On macOS, FFTW is a developer-installed dependency and the developer is responsible for dynamic-library availability.

## Root Build Prototype

The repository now has a root CMake entrypoint for the migration build graph. It adds `license`, `library`, and selected SDK examples from one configure step.

On macOS development machines:

```bash
cmake --fresh --preset macos-arm64-debug
cmake --build --preset macos-arm64-debug
ctest --preset macos-arm64-debug --output-on-failure
cmake --install out/build/macos-arm64-debug
cmake --build --preset macos-arm64-debug --target package
```

On Linux oneAPI machines:

```bash
cmake --fresh --preset linux-intel-debug
cmake --build --preset linux-intel-debug
ctest --preset linux-intel-debug --output-on-failure
cmake --install out/build/linux-intel-debug
cmake --build --preset linux-intel-debug --target package
```

The root build keeps legacy per-module test targets disabled by default through `MUPRO_ROOT_BUILD_LEGACY_TESTS=OFF`. Use that switch only when working specifically on legacy L0/L1 test cleanup.

Targeted solver compile checks can be enabled without building every L2/L3 solver. For example, on macOS:

```bash
cmake --fresh --preset macos-arm64-debug -B out/build/macos-arm64-debug-tdgl \
  -DMUPRO_BUILD_TDGL=ON
cmake --build out/build/macos-arm64-debug-tdgl --target mupro
```

## Linux Staged Build

Before using the helper scripts, make sure Intel oneAPI is available. Either source oneAPI yourself or set `ONEAPI_ROOT`:

```bash
source /opt/intel/oneapi/setvars.sh
```

The current `library` configure helper builds `license` first, then configures `library`.

```bash
cd library
source scripts/linux/cmake_configure.sh Debug
source scripts/linux/cmake_build.sh Debug
cmake --install ../license/out/build/debug
cmake --install out/build/debug
```

For release:

```bash
cd library
source scripts/linux/cmake_configure.sh Release
source scripts/linux/cmake_build.sh Release
cmake --install ../license/out/build/release
cmake --install out/build/release
```

Developer presets such as `Debug-dev` and `Release-dev` are only defined for `library`; the helper maps the `license` step back to `Debug` or `Release`.

## macOS Development Build

Install dependencies with Homebrew:

```bash
brew install cmake ninja gcc openblas fftw open-mpi
```

Build and install `license`:

```bash
cd license
cmake --fresh --preset macos-arm64-Debug
cmake --build --preset macos-arm64-Debug
cmake --install out/build/macos-arm64-debug
```

Build and install `library`:

```bash
cd ../library
cmake --fresh --preset macos-arm64-Debug
cmake --build --preset macos-arm64-Debug
cmake --install out/build/macos-arm64-debug
```

The macOS preset intentionally sets `MUPRO_BUILD_SOLVERS=OFF` for the current migration stage. It verifies the L0/L1 SDK route and external OpenBLAS/FFTW discovery.

## Example Build

After installing `license` and `library`, `examples/demo1` can be configured as a downstream project from the repository root:

```bash
cd ..
cmake -S examples/demo1 -B examples/demo1/cmake-build-macos-arm64-debug -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_Fortran_COMPILER=/opt/homebrew/bin/gfortran \
  -DCMAKE_PREFIX_PATH="library/out/install/macos-arm64-debug;license/out/install/macos-arm64-debug;/opt/homebrew/opt/openblas;/opt/homebrew/opt/fftw;/opt/homebrew/opt/open-mpi"

cmake --build examples/demo1/cmake-build-macos-arm64-debug
```

The example project enables C, C++, and Fortran because the SDK exports MPI C dependencies and contains C++ object code in the static library.

The C ABI skeleton example can be configured against the root install tree:

```bash
cmake -S examples/c_api_tdgl -B examples/c_api_tdgl/cmake-build-macos-arm64-debug -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_Fortran_COMPILER=/opt/homebrew/bin/gfortran \
  -DCMAKE_PREFIX_PATH="$PWD/out/install/macos-arm64-debug;/opt/homebrew/opt/openblas;/opt/homebrew/opt/fftw;/opt/homebrew/opt/open-mpi"

cmake --build examples/c_api_tdgl/cmake-build-macos-arm64-debug
./examples/c_api_tdgl/cmake-build-macos-arm64-debug/c_api_tdgl
```

The expected PR-014 output is a structured `MUPRO_STATUS_NOT_SETUP` message stating that the TDGL C solve backend is not connected yet.

## Tests

Use CTest from the root build for the current smoke/unit gate:

```bash
ctest --preset macos-arm64-debug --output-on-failure
```

The current root gate includes `root_configure_smoke`, `unit.c_api`, `unit.status`, `unit.l0_base`, `unit.l0_log`, `unit.l1_io`, `unit.l1_transform`, and `unit.l1_utilities`. The legacy `library` macOS Debug preset still configures and builds, but it does not yet register a useful standalone CTest gate.