Build Guide

This guide provides instructions on how to build or install all dependencies of Smith, followed by how to build Smith from source. The process consists of the following high-level phases:

  1. Setup the machine by installing the required system-level packages and generating a Spack environment file

  2. Build Third-party Libraries (TPLs) using Spack and Uberenv to provide a consistent dependency stack

  3. Build Smith itself using CMake once all dependencies are in place

Note

On LC machines, it is good practice to run intensive build commands in parallel on a compute node. Here is an example SLURM command, srun -ppdebug -N1 --exclusive make -j16 and an example Flux command, flux run -qpdebug -N1 --exclusive make -j16.

Tip

If you are on a LC machine and are in the smithdev LC linux group, we have a variety of pre-installed TPLs and configurations. If these are sufficient for you, you can skip to Building Smith with CMake. You can see these machines and configurations in the host-configs repository directory.

Tip

Alternatively, you can build Smith using preinstalled dependencies inside our existing Docker containers. This may have runtime speed considerations. Instructions for this process are located here.

Note

Smith uses the LLVM plugin Enzyme to perform automatic differentiation. To enable this functionality, you have to compile with an LLVM-based compiler. We recommend clang.

Spack and Uberenv

Smith uses Spack to build its TPLs. This has been encapsulated using Uberenv. Uberenv helps by doing the following:

  • Pulls a blessed version of Spack and Spack Packages locally

  • If you are on a known operating system (like TOSS4), Uberenv will automatically use our blessed Spack Environment files to keep Spack from building the world

  • Installs our Spack packages into the local Spack installation location

  • Simplifies whole dependency build into one command

Uberenv will create a directory containing a Spack instance with the required Smith TPLs installed.

Note

This directory must not be within the Smith repo - the example below controls this with the --prefix command line argument which is required.

Host-configs

Our Spack package recipe generates a file we call a host-config (<config_dependent_name>.cmake) at the root of Smith repository. CMake refers to this file as an initial cache. This host-config defines all the required information for building Smith including paths to compilers, TPLs, Developer Tools, and machine specific options.

Cloning Smith

Smith is hosted on GitHub. Smith uses git submodules, so the project must be cloned recursively. Use either of the following commands to pull Smith's repository:

# Using SSH keys setup with GitHub
$ git clone --recursive git@github.com:LLNL/smith.git

# Using HTTPS which works for everyone but is slightly slower and will require username/password
# for some commands
$ git clone --recursive https://github.com/LLNL/smith.git

Phase 1: Basic System Setup

We recommend installing some basic system-level development packages to minimize the amount of packages that Spack will build.

The following pages provide basic guidance on the following platforms and is where you should start:

At the end of each Setup guide, it has a link to the page that shows you how to build the minimal set of TPLs for Smith; followed by a page on how to build Smith from the generated host-config file via CMake.

Phase 2: Build Third-party Libraries

For more information see Building Smith's Third-party Libraries.

Phase 3: Build Smith with CMake

For more information see Building Smith with CMake.