Build and install FORGE¶

This page shows how to configure, build and install FORGE for each backend. Install the libraries in Install the dependencies first. Every option and target is listed in the CMake reference.

Get the source¶

git clone https://github.com/mechneurolab/forge.git
cd forge

Configure and build¶

Pick the block for your machine.

On a Mac with Apple Silicon, the Metal backend is on by default:

cmake -B build -DMPISupport=OFF
cmake --build build -j$(sysctl -n hw.logicalcpu)

On Linux without a GPU:

cmake -B build -DMPISupport=OFF
cmake --build build -j$(nproc)

On Linux with an NVIDIA GPU, add the CUDA backend:

cmake -B build -DCUDA_COMPUTE=ON -DMPISupport=OFF
cmake --build build -j$(nproc)

MPISupport is on by default, and then CMake requires Boost.MPI. Turn it off as above unless you want the MPI programs; Run a reconstruction with MPI covers that case.

The first configure downloads a few libraries (spdlog, indicators, FTXUI and nlohmann/json), so it needs network access.

Install¶

Install into a prefix of your choice:

cmake --install build --prefix $HOME/forge

Each backend gets its own directory, so a Metal or CUDA build installs two copies of every program:

$HOME/forge/
  bin/cpu/forgeSense, forgePcSense, ...    # CPU backend
  bin/metal/forgeSense, ...                # or bin/cuda/
  bin/forgeview
  bin/GenSyntheticISMRMRD
  lib/libForgeCommon_cpu.*, ...

Put the backend you want on your PATH, followed by bin/ so the programs can find forgeview:

export PATH="$HOME/forge/bin/metal:$HOME/forge/bin:$PATH"   # or bin/cuda, bin/cpu

Add the line to your shell profile to keep it.

Build a single program¶

The reconstruction programs have the same file name in every backend, and all of them are written to the top of the build directory. If you build more than one backend and want to run from the build tree, build only the target you need:

cmake --build build --target forgeSense_metal

Check the build¶

Print the version:

forgeSense --version

It prints a line such as FORGE v0.14.0 (forgeSense) built 2026-11-04. A build that isn't exactly a release tag adds Git metadata to the version, such as v0.14.0+git.3.g1a2b3c4, and .dirty if the source had uncommitted changes.

To run the test suites, see Run the tests. To try a reconstruction, follow Your first reconstruction.

Build redistributable binaries¶

-DSTATIC_DEPS=ON links the third-party libraries statically so the programs run on machines without them. It forces MPISupport=OFF. It also needs static Armadillo and ISMRMRD: scripts/build-deps.sh builds both, then set ARMA_HOME in the environment and pass -DISMRMRD_LIBRARIES=<path to libismrmrd.a>. The macOS distribution job in .github/workflows/ci.yml shows the full sequence.