From 85802beaa5ffe32bd61703699980c29693190587 Mon Sep 17 00:00:00 2001 From: Chris White Date: Thu, 8 Jan 2026 17:26:24 -0800 Subject: [PATCH 01/15] first cut at deunifying build instructions --- src/docs/index.rst | 1 + src/docs/sphinx/build_guide/build.rst | 66 ++++++++ src/docs/sphinx/build_guide/build_tpls.rst | 47 ++++++ src/docs/sphinx/build_guide/index.rst | 66 ++++++++ src/docs/sphinx/build_guide/setup_lc.rst | 146 ++++++++++++++++ .../setup_mac.rst} | 50 +----- src/docs/sphinx/build_guide/setup_ubuntu.rst | 159 ++++++++++++++++++ src/docs/sphinx/dev_guide/index.rst | 1 - src/docs/sphinx/quickstart.rst | 58 ------- 9 files changed, 486 insertions(+), 108 deletions(-) create mode 100644 src/docs/sphinx/build_guide/build.rst create mode 100644 src/docs/sphinx/build_guide/build_tpls.rst create mode 100644 src/docs/sphinx/build_guide/index.rst create mode 100644 src/docs/sphinx/build_guide/setup_lc.rst rename src/docs/sphinx/{dev_guide/tpl_build.rst => build_guide/setup_mac.rst} (91%) create mode 100644 src/docs/sphinx/build_guide/setup_ubuntu.rst diff --git a/src/docs/index.rst b/src/docs/index.rst index f1c192a414..89f7d46c2c 100644 --- a/src/docs/index.rst +++ b/src/docs/index.rst @@ -36,5 +36,6 @@ LLNL-CODE-805541 sphinx/quickstart sphinx/user_guide/index + sphinx/build_guide/index sphinx/dev_guide/index sphinx/theory_reference/index diff --git a/src/docs/sphinx/build_guide/build.rst b/src/docs/sphinx/build_guide/build.rst new file mode 100644 index 0000000000..53052b5645 --- /dev/null +++ b/src/docs/sphinx/build_guide/build.rst @@ -0,0 +1,66 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _build-label: + +========================= +Building Smith with CMake +========================= + +Smith uses a CMake build system that wraps its configure step with a script +called ``config-build.py``. This script creates a build directory and +runs the necessary CMake command for you. You just need to point the script +at the generated or a provided host-config. This can be accomplished with +one of the following commands: + +.. code-block:: bash + + # If you built Smith's dependencies yourself either via Spack or by hand + $ python3 ./config-build.py -hc .cmake + + # If you are on an LC machine and want to use our public pre-built dependencies + $ python3 ./config-build.py -hc host-configs/--.cmake + + # If you'd like to configure specific build options, e.g., a debug build + $ python3 ./config-build.py -hc /path/to/host-config.cmake -DCMAKE_BUILD_TYPE=Debug + +If you built the dependencies using Spack/uberenv, the host-config file is output at the +project root. To use the pre-built dependencies on LC, you must be in the appropriate +LC group. Contact `Brandon Talamini `_ for access. + +Some build options frequently used by Smith include: + +* ``CMAKE_BUILD_TYPE``: Specifies the build type, see the `CMake docs `_ +* ``ENABLE_BENCHMARKS``: Enables Google Benchmark performance tests, defaults to ``OFF`` +* ``ENABLE_WARNINGS_AS_ERRORS``: Turns compiler warnings into errors, defaults to ``ON`` +* ``ENABLE_ASAN``: Enables the Address Sanitizer for memory safety inspections, defaults to ``OFF`` +* ``SMITH_ENABLE_TESTS``: Enables Smith unit tests, defaults to ``ON`` +* ``SMITH_ENABLE_CODEVELOP``: Enables local development build of MFEM/Axom, see :ref:`codevelop-label`, defaults to ``OFF`` +* ``SMITH_USE_VDIM_ORDERING``: Sets the vector ordering to be ``byVDIM``, which is significantly faster for algebraic multigrid, defaults to ``ON``. + +Once the build has been configured, Smith can be built with the following commands: + +.. code-block:: bash + + $ cd build- + $ make -j16 + +.. note:: + On LC machines, it is good practice to do the build step in parallel on a compute node. + Here is an example command: ``srun -ppdebug -N1 --exclusive make -j16`` + +We provide the following useful build targets that can be run from the build directory: + +* ``test``: Runs our unit tests +* ``docs``: Builds our documentation to the following locations: + + * Sphinx: ``build-*/src/docs/html/index.html`` + * Doxygen: ``/build-*/src/docs/html/doxygen/html/index.html`` + +* ``style``: Runs styling over source code and replaces files in place +* ``check``: Runs a set of code checks over source code (CppCheck and clang-format) + + + diff --git a/src/docs/sphinx/build_guide/build_tpls.rst b/src/docs/sphinx/build_guide/build_tpls.rst new file mode 100644 index 0000000000..e0898fe22c --- /dev/null +++ b/src/docs/sphinx/build_guide/build_tpls.rst @@ -0,0 +1,47 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _building_tpls-label: + +======================================================== +Building Smith's Third-party Libraries +======================================================== + +It is now time to build Smith's Third-party Libraries (TPLs). Run the command with the compiler +that you want to develop with: + +.. code-block:: bash + + scripts/uberenv/uberenv.py --prefix= --spack-env-file= --spec="%clang_19" + +Some helpful uberenv options include : + +* ``--spec=" build_type=Debug"`` (build core TPLs, such as MFEM and Hypre, with debug symbols) +* ``--spec=+profiling`` (build the Adiak and Caliper libraries) +* ``--spec=+devtools`` (also build the devtools with one command) +* ``--spec=%clang_19`` (build with a specific compiler as defined in the ``spack.yaml`` file) +* ``--spack-env-file=`` (use specific Spack environment configuration file) +* ``--prefix=`` (required, build and install the dependencies in a particular location) - this *must be outside* of your local Smith repository + +The modifiers to the Spack specification ``spec`` can be chained together, e.g. ``--spec='+devtools build_type=Debug %clang_19'``. + + +If successful, you will see two things. The first is what we call a host-config. It is all the CMake +inputs you need to build Smith. This file will be a new CMake file in the current directory with your machine +name, system type, and compiler, for example ``mycomputerlinux-ubuntu24.04-skylake-clang@19.1.1.cmake``. +The second will be output from Spack that ends in this: + +.. code-block:: bash + + ==> smith: Executing phase: 'initconfig' + ==> Updating view at /my/prefix/spack_env/.spack-env/view + +-------------- +Building Smith +-------------- + +Finally, with the TPL's built and the host-config file, you can build Smith +for more detail instructions on how to build Smith, see :ref:`build-label`. + diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst new file mode 100644 index 0000000000..9bd8ca33cc --- /dev/null +++ b/src/docs/sphinx/build_guide/index.rst @@ -0,0 +1,66 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +=========== +Build Guide +=========== + +------------------------------- +Third-party Library (TPL) Build +------------------------------- + +Spack and Uberenv +----------------- + +Smith uses `Spack `_ to build it's 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. + +It also generates a host-config file (``.cmake``) +at the root of Smith repository. This host-config defines all the required information for building +Smith. + +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: + + * Ubuntu 24 LTS :ref:`tpl_ubuntu-label` + * macOS :ref:`tpl_mac-label` + * Livermore Computing (LC) :ref:`tpl_lc-label` + +.. note:: + + Smith uses the LLVM plugin `Enzyme `_ to perform + automatic differentiation. Due to this you have to compile with an LLVM-based compiler. + We recommend ``clang``. + +.. toctree:: + :hidden: + :maxdepth: 2 + + setup_ubuntu + setup_mac + setup_lc + building_tpls + build + + diff --git a/src/docs/sphinx/build_guide/setup_lc.rst b/src/docs/sphinx/build_guide/setup_lc.rst new file mode 100644 index 0000000000..fb0515e144 --- /dev/null +++ b/src/docs/sphinx/build_guide/setup_lc.rst @@ -0,0 +1,146 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _tpl_lc-label: + +======================================================== +Third-party Library (TPL) Livermore Computing (LC) Build +======================================================== + +We provide Spack Environment files for each of LC's systems: + + * TOSS4: ``scripts/spack/configs/toss_4_x86_64_ib/spack.yaml`` + * TOSS4 Cray: ``scripts/spack/configs/toss_4_x86_64_ib_cray/spack.yaml`` + +Unless otherwise specified, Spack will default to a compiler. This is generally not a good idea when +developing large codes. To specify which compiler to use add the compiler specification to the ``--spec`` Uberenv +command line option. We provide recommended Spack specs for LC in ``scripts/spack/specs.json``. + +You can use these directly in the ``uberenv.py`` command in the :ref:`building_tpls-label` +section by substituting the values in these two command line options: ``--spack-env-file=ubuntu24.yaml --spec="%clang_19"``. + +.. note:: + On LC machines, it is good practice to do the build step in parallel on a compute node. + You should add the following to the start of your commands: ``salloc -ppdebug -N1 --exclusive python3 scripts/uberenv/uberenv.py`` + +.. note:: + If you do not have access to the ``smithdev`` linux group. You cannot currently use our prebuilt Dev Tools + referenced in the Spack Environment files listed above. You will be required to turn off the devtool variant + on your Spack spec by adding ``~devtools`` to your uberenv or Spack spec. + +------------------------------- +Generate Spack Environment File +------------------------------- + +Spack uses an environment file, or ``spack.yaml``, to describe where system level packages are to minimize what it builds. +This file describes the compilers and associated flags required for the platform as well as the low-level libraries +on the system to prevent Spack from building the world. Documentation on these environment files is located +in the `Spack docs `_. + +The following command will download the specific Spack version we use and run a minimal set of commands to +generate an environment file for you. This should be a good starting point and should be used in following +Spack builds. + +.. code-block:: bash + + ./scripts/uberenv/uberenv.py --prefix= --setup-and-env-only + +This command will create a Spack environment file, ``spack.yaml``, where you ran the above command. +If you want to use Clang as your compiler, alter the following section in that file by changing +``null`` in the ``f77`` and ``fc`` lines to ``/usr/bin/gfortran``: + +.. code-block:: yaml + + - compiler: + spec: clang@=19.1.1 + paths: + cc: /usr/bin/clang + cxx: /usr/bin/clang++ + f77: null # Change null to /usr/bin/gfortran + fc: null # and this one too + flags: {} + operating_system: ubuntu24.04 + target: x86_64 + modules: [] + environment: {} + extra_rpaths: [] + + +To speed up the build, you can add packages that exist on your system to the same Spack environment file. For example, +we installed lua in the above ``apt`` commands. To do so, add the following lines under the ``packages:`` section of the yaml: + +.. code-block:: yaml + + lua: + externals: + - spec: lua@5.2 + prefix: /usr + buildable: false + +The above spack command will output a concretization that looks like the following: + +.. code-block:: shell + + ==> Concretized 1 spec: + - uu3sgzv smith@develop cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~cuda~devtools+enzyme~ipo+openmp+petsc~profiling+raja~rocm~shared+slepc+strumpack+sundials+tribol+umpire build_system=cmake build_type=Release dev_path=/home/white238/projects/smith/repo generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - x77izrn ^axom@0.10.1.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +cpp14~cuda~devtools~examples~fortran+hdf5~ipo+lua+mfem+mpi~opencascade+openmp~python+raja~rocm~scr~shared~tools+umpire build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - prysqkw ^blt@0.6.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 6vi46wm ^camp@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~ipo~omptarget+openmp~rocm~sycl~tests build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] fbcccfh ^cmake@3.28.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~doc+ncurses+ownlibs~qtgui build_system=generic build_type=Release patches=dbc3892 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - zqg3svf ^conduit@0.9.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~adios+blt_find_mpi~caliper~doc~doxygen+examples~fortran+hdf5+hdf5_compat~ipo+mpi+parmetis~python+shared~silo~test+utilities~zfp build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - lbmoj2n ^enzyme@0.0.180 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] 6bbmbqw ^llvm@19.1.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +clang~cuda~flang+gold+libomptarget~libomptarget_debug~link_llvm_dylib~lld~lldb+llvm_dylib+lua~mlir+offload+polly~python~split_dwarf~z3~zstd build_system=cmake build_type=Release compiler-rt=runtime generator=ninja libcxx=runtime libunwind=runtime openmp=runtime shlib_symbol_version=none targets=all version_suffix=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] wyizjq2 ^glibc@2.39 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] 74zxzg7 ^gmake@4.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~guile build_system=generic patches=599f134 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 32xbf3o ^hdf5@1.8.23 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cxx~fortran+hl~ipo~mpi~shared~szip~threadsafe+tools api=default build_system=cmake build_type=Release generator=make patches=f42732a arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - hlqkvfc ^pkgconf@2.3.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - dlqs5c6 ^zlib-ng@2.2.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +compat~new_strategies+opt+pic+shared build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - iwu2tah ^hypre@2.32.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~caliper~complex~cublas~cuda~debug+fortran~gptune~gpu-aware-mpi~int64~internal-superlu+lapack~magma~mixedint+mpi~openmp~rocblas~rocm~shared~superlu-dist~sycl~umpire~unified-memory build_system=autotools precision=double arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - g6pkuqj ^openblas@0.3.29 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~bignuma~consistent_fpcsr+dynamic_dispatch+fortran~ilp64+locking+pic+shared build_system=makefile patches=9968625 symbol_suffix=none threads=openmp arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] naati2q ^lua@5.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +shared build_system=makefile fetcher=curl arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 5u3dj5i ^metis@5.1.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~gdb~int64~ipo~no_warning~real64~shared build_system=cmake build_type=Release generator=make patches=4991da9,93a7903 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ae2mqqr ^mfem@4.8.0.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~amgx~asan~conduit~cuda~debug~examples~exceptions~fms~ginkgo~gnutls~gslib~hiop+lapack~libceed~libunwind+metis~miniapps~mpfr+mpi~mumps+netcdf~occa+openmp+petsc~pumi~raja~rocm~shared+slepc+static+strumpack~suite-sparse+sundials+superlu-dist~threadsafe~umpire+zlib build_system=generic cxxstd=auto precision=double timer=auto arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ohbx2dl ^netcdf-c@4.7.4 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~blosc~byterange~dap~fsync~hdf4~jna~logging~mpi~nczarr_zip+optimize~parallel-netcdf+pic~shared~szip~zstd build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] yr5mrlv ^openmpi@4.1.6 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +atomics~cuda+cxx~cxx_exceptions~debug~gpfs~internal-hwloc~internal-libevent~internal-pmix+java~legacylaunchers~lustre~memchecker~openshmem~orterunprefix+pmi+romio+rsh~singularity~static~two_level_namespace+vt~wrapper-rpath build_system=autotools fabrics=ofi,psm,psm2,ucx romio-filesystem=none schedulers=slurm arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 2zrmzi6 ^parmetis@4.0.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~gdb~int64~ipo~shared build_system=cmake build_type=Release generator=make patches=4f89253,50ed208,704b84f arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - sxzqrlk ^petsc@3.22.4 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~X~batch~cgns~complex~cuda~debug+double~exodusii~fftw+fortran~giflib~hdf5~hpddm~hwloc+hypre~int64~jpeg~knl~kokkos~libpng~libyaml~memkind+metis~mkl-pardiso~mmg~moab~mpfr+mpi~mumps+openmp~p4est~parmmg~ptscotch~random123~rocm~saws~scalapack~shared+strumpack~suite-sparse+superlu-dist~sycl~tetgen~trilinos~valgrind~zoltan build_system=generic clanguage=C memalign=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] baweecy ^diffutils@3.10 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - evwepln ^netlib-scalapack@2.2.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo~pic+shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] timms67 ^python@3.12.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +bz2+crypt+ctypes+dbm~debug+libxml2+lzma~optimizations+pic+pyexpat~pythoncmd+readline+shared+sqlite3+ssl~tkinter+uuid+zlib build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - cc22mbv ^raja@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~desul~examples~exercises~ipo~lowopttest~omptarget~omptask+openmp~plugins~rocm~run-all-tests~shared~sycl~tests+vectorization build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - zmiasfe ^slepc@3.22.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +arpack~blopex~cuda~hpddm~rocm build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - fvqm3cm ^arpack-ng@3.9.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~icb~ipo+mpi+shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 3ka3cml ^strumpack@8.0.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~butterflypack+c_interface~count_flops~cuda~ipo~magma+mpi+openmp+parmetis~rocm~scotch~shared~slate~task_timers~zfp build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - mkzronq ^sundials@6.7.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +ARKODE+CVODE+CVODES+IDA+IDAS+KINSOL~asan~cuda~examples~examples-install~f2003~fcmix+generic-math~ginkgo+hypre~int64~ipo~klu~kokkos~kokkos-kernels~lapack~magma~monitoring+mpi~openmp~petsc~profiling~pthread~raja~rocm~shared+static~superlu-dist~superlu-mt~sycl~trilinos build_system=cmake build_type=Release cstd=99 cxxstd=14 generator=make logging-level=2 logging-mpi=OFF precision=double arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - vqgxdhb ^superlu-dist@8.1.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~int64~ipo~openmp+parmetis~rocm~shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ldxkes6 ^tribol@0.1.0.18 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~cuda~devtools~examples~fortran~ipo+openmp+raja+redecomp~rocm~tests+umpire build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 3ftpxxz ^umpire@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~backtrace+c~cuda~dev_benchmarks~device_alloc~deviceconst~examples+fmt_header_only~fortran~ipc_shmem~ipo~mpi~numa~omptarget+openmp~rocm~sanitizer_tests~shared~sqlite_experimental~tools+werror build_system=cmake build_type=Release generator=make tests=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - xts3eqq ^fmt@11.0.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo+pic~shared build_system=cmake build_type=Release cxxstd=11 generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + + +Lines starting with ``[e]`` are external packages that Spack recognizes are on the system and will not rebuild them. +By adding Lua to the Spack environment file, Spack will no longer build Lua and any of its dependencies that are +needed by anything else. In this case, ``lua``, ``readline``, and ``unzip`` will not be built. ``unzip`` may be needed +by another package, so you can also add it with this yaml section: + +.. code-block:: yaml + + unzip: + externals: + - spec: unzip@6.0 + prefix: /usr + buildable: false + +.. important:: + + Uberenv will override existing ``spack.yaml`` files in the current working directory. Now that we have made modifications, + you should rename/move the file so the changes are not lost and adjust the `uberenv.py` commands to reflect the new file name. + +-------------------------------------- +Building Smith's Third-party Libraries +-------------------------------------- + +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. + diff --git a/src/docs/sphinx/dev_guide/tpl_build.rst b/src/docs/sphinx/build_guide/setup_mac.rst similarity index 91% rename from src/docs/sphinx/dev_guide/tpl_build.rst rename to src/docs/sphinx/build_guide/setup_mac.rst index 935804906f..220382ec58 100644 --- a/src/docs/sphinx/dev_guide/tpl_build.rst +++ b/src/docs/sphinx/build_guide/setup_mac.rst @@ -325,57 +325,9 @@ by another package, so you can also add it with this yaml section: Uberenv will override existing ``spack.yaml`` files in the current working directory. Now that we have made modifications, you should rename/move the file so the changes are not lost and adjust the `uberenv.py` commands to reflect the new file name. - -.. _building_tpls-label: - -------------------------------------- Building Smith's Third-party Libraries -------------------------------------- -It is now time to build Smith's Third-party Libraries (TPLs). Run the command with the compiler -that you want to develop with: - -.. code-block:: bash - - scripts/uberenv/uberenv.py --prefix= --spack-env-file= --spec="%clang_19" - -Some helpful uberenv options include : - -* ``--spec=" build_type=Debug"`` (build core TPLs, such as MFEM and Hypre, with debug symbols) -* ``--spec=+profiling`` (build the Adiak and Caliper libraries) -* ``--spec=+devtools`` (also build the devtools with one command) -* ``--spec=%clang_19`` (build with a specific compiler as defined in the ``spack.yaml`` file) -* ``--spack-env-file=`` (use specific Spack environment configuration file) -* ``--prefix=`` (required, build and install the dependencies in a particular location) - this *must be outside* of your local Smith repository - -The modifiers to the Spack specification ``spec`` can be chained together, e.g. ``--spec='+devtools build_type=Debug %clang_19'``. - - -If successful, you will see two things. The first is what we call a host-config. It is all the CMake -inputs you need to build Smith. This file will be a new CMake file in the current directory with your machine -name, system type, and compiler, for example ``mycomputerlinux-ubuntu24.04-skylake-clang@19.1.1.cmake``. -The second will be output from Spack that ends in this: - -.. code-block:: bash - - ==> smith: Executing phase: 'initconfig' - ==> Updating view at /my/prefix/spack_env/.spack-env/view - --------------- -Building Smith --------------- - -Finally, with the TPL's built and the host-config file, you can build Smith with the following -command: - -.. code-block:: bash - - ./config-build.py -hc - cd - make -j - make -j8 test - -For more detail instructions on how to build Smith, see :ref:`build-label`. - - +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. diff --git a/src/docs/sphinx/build_guide/setup_ubuntu.rst b/src/docs/sphinx/build_guide/setup_ubuntu.rst new file mode 100644 index 0000000000..28e9e2eb3d --- /dev/null +++ b/src/docs/sphinx/build_guide/setup_ubuntu.rst @@ -0,0 +1,159 @@ +.. ## Copyright (c) Lawrence Livermore National Security, LLC and +.. ## other Smith Project Developers. See the top-level COPYRIGHT file for details. +.. ## +.. ## SPDX-License-Identifier: (BSD-3-Clause) + +.. _tpl_builds-label: + +========================================= +Third-party Library (TPL) Ubuntu 24 Build +========================================= + +Install clang version 19 and make it the default compiler: + +.. code-block:: bash + + sudo apt install -y --no-install-recommends clang-19 libclang-19-dev clang-format-19 llvm-19 llvm-19-dev libzstd-dev libomp-19-dev gfortran-13 + # Set clang-19 as the default clang + sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-19 101 \ + && sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-19 101 \ + && sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-19 101 + +Install required build packages to minimize what Spack will build: + +.. code-block:: bash + + sudo apt install -y --no-install-recommends build-essential bzip2 cmake libopenblas-dev \ + lua5.2 liblua5.2-dev openmpi-bin libopenmpi-dev unzip + +Optionally you can install packages to generate documentation: + +.. code-block:: bash + + sudo apt install -y --no-install-recommends graphviz python3-sphinx texlive-full doxygen + +.. note:: + + The documentation packages require a lot of disk space. + +.. note:: + + We provide a basic Ubuntu 24 Spack environment file in ``scripts/spack/configs/linux_ubuntu_24`` that + may work for most people. If you want to try using that, skip to :ref:`building_tpls-label` + below and use this command line option instead ``--spack-env-file=scripts/spack/configs/linux_ubuntu_24/spack.yaml`` + + +------------------------------- +Generate Spack Environment File +------------------------------- + +Spack uses an environment file, or ``spack.yaml``, to describe where system level packages are to minimize what it builds. +This file describes the compilers and associated flags required for the platform as well as the low-level libraries +on the system to prevent Spack from building the world. Documentation on these environment files is located +in the `Spack docs `_. + +The following command will download the specific Spack version we use and run a minimal set of commands to +generate an environment file for you. This should be a good starting point and should be used in following +Spack builds. + +.. code-block:: bash + + ./scripts/uberenv/uberenv.py --prefix= --setup-and-env-only + +This command will create a Spack environment file, ``spack.yaml``, where you ran the above command. +If you want to use Clang as your compiler, alter the following section in that file by changing +``null`` in the ``f77`` and ``fc`` lines to ``/usr/bin/gfortran``: + +.. code-block:: yaml + + - compiler: + spec: clang@=19.1.1 + paths: + cc: /usr/bin/clang + cxx: /usr/bin/clang++ + f77: null # Change null to /usr/bin/gfortran + fc: null # and this one too + flags: {} + operating_system: ubuntu24.04 + target: x86_64 + modules: [] + environment: {} + extra_rpaths: [] + + +To speed up the build, you can add packages that exist on your system to the same Spack environment file. For example, +we installed lua in the above ``apt`` commands. To do so, add the following lines under the ``packages:`` section of the yaml: + +.. code-block:: yaml + + lua: + externals: + - spec: lua@5.2 + prefix: /usr + buildable: false + +The above spack command will output a concretization that looks like the following: + +.. code-block:: shell + + ==> Concretized 1 spec: + - uu3sgzv smith@develop cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~cuda~devtools+enzyme~ipo+openmp+petsc~profiling+raja~rocm~shared+slepc+strumpack+sundials+tribol+umpire build_system=cmake build_type=Release dev_path=/home/white238/projects/smith/repo generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - x77izrn ^axom@0.10.1.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +cpp14~cuda~devtools~examples~fortran+hdf5~ipo+lua+mfem+mpi~opencascade+openmp~python+raja~rocm~scr~shared~tools+umpire build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - prysqkw ^blt@0.6.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 6vi46wm ^camp@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~ipo~omptarget+openmp~rocm~sycl~tests build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] fbcccfh ^cmake@3.28.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~doc+ncurses+ownlibs~qtgui build_system=generic build_type=Release patches=dbc3892 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - zqg3svf ^conduit@0.9.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~adios+blt_find_mpi~caliper~doc~doxygen+examples~fortran+hdf5+hdf5_compat~ipo+mpi+parmetis~python+shared~silo~test+utilities~zfp build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - lbmoj2n ^enzyme@0.0.180 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] 6bbmbqw ^llvm@19.1.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +clang~cuda~flang+gold+libomptarget~libomptarget_debug~link_llvm_dylib~lld~lldb+llvm_dylib+lua~mlir+offload+polly~python~split_dwarf~z3~zstd build_system=cmake build_type=Release compiler-rt=runtime generator=ninja libcxx=runtime libunwind=runtime openmp=runtime shlib_symbol_version=none targets=all version_suffix=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] wyizjq2 ^glibc@2.39 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] 74zxzg7 ^gmake@4.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~guile build_system=generic patches=599f134 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 32xbf3o ^hdf5@1.8.23 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cxx~fortran+hl~ipo~mpi~shared~szip~threadsafe+tools api=default build_system=cmake build_type=Release generator=make patches=f42732a arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - hlqkvfc ^pkgconf@2.3.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - dlqs5c6 ^zlib-ng@2.2.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +compat~new_strategies+opt+pic+shared build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - iwu2tah ^hypre@2.32.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~caliper~complex~cublas~cuda~debug+fortran~gptune~gpu-aware-mpi~int64~internal-superlu+lapack~magma~mixedint+mpi~openmp~rocblas~rocm~shared~superlu-dist~sycl~umpire~unified-memory build_system=autotools precision=double arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - g6pkuqj ^openblas@0.3.29 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~bignuma~consistent_fpcsr+dynamic_dispatch+fortran~ilp64+locking+pic+shared build_system=makefile patches=9968625 symbol_suffix=none threads=openmp arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] naati2q ^lua@5.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +shared build_system=makefile fetcher=curl arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 5u3dj5i ^metis@5.1.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~gdb~int64~ipo~no_warning~real64~shared build_system=cmake build_type=Release generator=make patches=4991da9,93a7903 arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ae2mqqr ^mfem@4.8.0.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~amgx~asan~conduit~cuda~debug~examples~exceptions~fms~ginkgo~gnutls~gslib~hiop+lapack~libceed~libunwind+metis~miniapps~mpfr+mpi~mumps+netcdf~occa+openmp+petsc~pumi~raja~rocm~shared+slepc+static+strumpack~suite-sparse+sundials+superlu-dist~threadsafe~umpire+zlib build_system=generic cxxstd=auto precision=double timer=auto arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ohbx2dl ^netcdf-c@4.7.4 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~blosc~byterange~dap~fsync~hdf4~jna~logging~mpi~nczarr_zip+optimize~parallel-netcdf+pic~shared~szip~zstd build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] yr5mrlv ^openmpi@4.1.6 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +atomics~cuda+cxx~cxx_exceptions~debug~gpfs~internal-hwloc~internal-libevent~internal-pmix+java~legacylaunchers~lustre~memchecker~openshmem~orterunprefix+pmi+romio+rsh~singularity~static~two_level_namespace+vt~wrapper-rpath build_system=autotools fabrics=ofi,psm,psm2,ucx romio-filesystem=none schedulers=slurm arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 2zrmzi6 ^parmetis@4.0.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~gdb~int64~ipo~shared build_system=cmake build_type=Release generator=make patches=4f89253,50ed208,704b84f arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - sxzqrlk ^petsc@3.22.4 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~X~batch~cgns~complex~cuda~debug+double~exodusii~fftw+fortran~giflib~hdf5~hpddm~hwloc+hypre~int64~jpeg~knl~kokkos~libpng~libyaml~memkind+metis~mkl-pardiso~mmg~moab~mpfr+mpi~mumps+openmp~p4est~parmmg~ptscotch~random123~rocm~saws~scalapack~shared+strumpack~suite-sparse+superlu-dist~sycl~tetgen~trilinos~valgrind~zoltan build_system=generic clanguage=C memalign=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] baweecy ^diffutils@3.10 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC build_system=autotools arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - evwepln ^netlib-scalapack@2.2.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo~pic+shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + [e] timms67 ^python@3.12.3 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +bz2+crypt+ctypes+dbm~debug+libxml2+lzma~optimizations+pic+pyexpat~pythoncmd+readline+shared+sqlite3+ssl~tkinter+uuid+zlib build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - cc22mbv ^raja@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~desul~examples~exercises~ipo~lowopttest~omptarget~omptask+openmp~plugins~rocm~run-all-tests~shared~sycl~tests+vectorization build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - zmiasfe ^slepc@3.22.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +arpack~blopex~cuda~hpddm~rocm build_system=generic arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - fvqm3cm ^arpack-ng@3.9.1 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~icb~ipo+mpi+shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 3ka3cml ^strumpack@8.0.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~butterflypack+c_interface~count_flops~cuda~ipo~magma+mpi+openmp+parmetis~rocm~scotch~shared~slate~task_timers~zfp build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - mkzronq ^sundials@6.7.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC +ARKODE+CVODE+CVODES+IDA+IDAS+KINSOL~asan~cuda~examples~examples-install~f2003~fcmix+generic-math~ginkgo+hypre~int64~ipo~klu~kokkos~kokkos-kernels~lapack~magma~monitoring+mpi~openmp~petsc~profiling~pthread~raja~rocm~shared+static~superlu-dist~superlu-mt~sycl~trilinos build_system=cmake build_type=Release cstd=99 cxxstd=14 generator=make logging-level=2 logging-mpi=OFF precision=double arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - vqgxdhb ^superlu-dist@8.1.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~cuda~int64~ipo~openmp+parmetis~rocm~shared build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - ldxkes6 ^tribol@0.1.0.18 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~cuda~devtools~examples~fortran~ipo+openmp+raja+redecomp~rocm~tests+umpire build_system=cmake build_type=Release generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - 3ftpxxz ^umpire@2024.07.0 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~asan~backtrace+c~cuda~dev_benchmarks~device_alloc~deviceconst~examples+fmt_header_only~fortran~ipc_shmem~ipo~mpi~numa~omptarget+openmp~rocm~sanitizer_tests~shared~sqlite_experimental~tools+werror build_system=cmake build_type=Release generator=make tests=none arch=linux-ubuntu24.04-skylake %clang@19.1.1 + - xts3eqq ^fmt@11.0.2 cflags=-fPIC cxxflags=-fPIC fflags=-fPIC ~ipo+pic~shared build_system=cmake build_type=Release cxxstd=11 generator=make arch=linux-ubuntu24.04-skylake %clang@19.1.1 + + +Lines starting with ``[e]`` are external packages that Spack recognizes are on the system and will not rebuild them. +By adding Lua to the Spack environment file, Spack will no longer build Lua and any of its dependencies that are +needed by anything else. In this case, ``lua``, ``readline``, and ``unzip`` will not be built. ``unzip`` may be needed +by another package, so you can also add it with this yaml section: + +.. code-block:: yaml + + unzip: + externals: + - spec: unzip@6.0 + prefix: /usr + buildable: false + +.. important:: + + Uberenv will override existing ``spack.yaml`` files in the current working directory. Now that we have made modifications, + you should rename/move the file so the changes are not lost and adjust the `uberenv.py` commands to reflect the new file name. + + +-------------------------------------- +Building Smith's Third-party Libraries +-------------------------------------- + +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. diff --git a/src/docs/sphinx/dev_guide/index.rst b/src/docs/sphinx/dev_guide/index.rst index 2f044291a1..37f4abf53b 100644 --- a/src/docs/sphinx/dev_guide/index.rst +++ b/src/docs/sphinx/dev_guide/index.rst @@ -11,7 +11,6 @@ Developer Guide :hidden: :maxdepth: 2 - tpl_build.rst style_guide docker_env modern_cpp diff --git a/src/docs/sphinx/quickstart.rst b/src/docs/sphinx/quickstart.rst index 9d4bc17c59..d3d010290b 100644 --- a/src/docs/sphinx/quickstart.rst +++ b/src/docs/sphinx/quickstart.rst @@ -91,61 +91,3 @@ Using a Docker Image with Preinstalled Dependencies As an alternative, you can build Smith using preinstalled dependencies inside a Docker container. Instructions for this process are located :ref:`here `. - -.. _build-label: - -Building Smith --------------- - -Smith uses a CMake build system that wraps its configure step with a script -called ``config-build.py``. This script creates a build directory and -runs the necessary CMake command for you. You just need to point the script -at the generated or a provided host-config. This can be accomplished with -one of the following commands: - -.. code-block:: bash - - # If you built Smith's dependencies yourself either via Spack or by hand - $ python3 ./config-build.py -hc .cmake - - # If you are on an LC machine and want to use our public pre-built dependencies - $ python3 ./config-build.py -hc host-configs/--.cmake - - # If you'd like to configure specific build options, e.g., a debug build - $ python3 ./config-build.py -hc /path/to/host-config.cmake -DCMAKE_BUILD_TYPE=Debug - -If you built the dependencies using Spack/uberenv, the host-config file is output at the -project root. To use the pre-built dependencies on LC, you must be in the appropriate -LC group. Contact `Brandon Talamini `_ for access. - -Some build options frequently used by Smith include: - -* ``CMAKE_BUILD_TYPE``: Specifies the build type, see the `CMake docs `_ -* ``ENABLE_BENCHMARKS``: Enables Google Benchmark performance tests, defaults to ``OFF`` -* ``ENABLE_WARNINGS_AS_ERRORS``: Turns compiler warnings into errors, defaults to ``ON`` -* ``ENABLE_ASAN``: Enables the Address Sanitizer for memory safety inspections, defaults to ``OFF`` -* ``SMITH_ENABLE_TESTS``: Enables Smith unit tests, defaults to ``ON`` -* ``SMITH_ENABLE_CODEVELOP``: Enables local development build of MFEM/Axom, see :ref:`codevelop-label`, defaults to ``OFF`` -* ``SMITH_USE_VDIM_ORDERING``: Sets the vector ordering to be ``byVDIM``, which is significantly faster for algebraic multigrid, defaults to ``ON``. - -Once the build has been configured, Smith can be built with the following commands: - -.. code-block:: bash - - $ cd build- - $ make -j16 - -.. note:: - On LC machines, it is good practice to do the build step in parallel on a compute node. - Here is an example command: ``srun -ppdebug -N1 --exclusive make -j16`` - -We provide the following useful build targets that can be run from the build directory: - -* ``test``: Runs our unit tests -* ``docs``: Builds our documentation to the following locations: - - * Sphinx: ``build-*/src/docs/html/index.html`` - * Doxygen: ``/build-*/src/docs/html/doxygen/html/index.html`` - -* ``style``: Runs styling over source code and replaces files in place -* ``check``: Runs a set of code checks over source code (CppCheck and clang-format) From c94fdde5aa7aa7ec6a30fac527be6d6dc8539627 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 12:41:54 -0800 Subject: [PATCH 02/15] fix links and cleanup start of macos page --- src/docs/sphinx/build_guide/index.rst | 6 +- .../{setup_lc.rst => setup_tpl_lc.rst} | 2 +- .../{setup_mac.rst => setup_tpl_mac.rst} | 94 +------------------ ...{setup_ubuntu.rst => setup_tpl_ubuntu.rst} | 2 +- 4 files changed, 9 insertions(+), 95 deletions(-) rename src/docs/sphinx/build_guide/{setup_lc.rst => setup_tpl_lc.rst} (99%) rename src/docs/sphinx/build_guide/{setup_mac.rst => setup_tpl_mac.rst} (85%) rename src/docs/sphinx/build_guide/{setup_ubuntu.rst => setup_tpl_ubuntu.rst} (99%) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index 9bd8ca33cc..bb7f73c02b 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -43,9 +43,9 @@ amount of packages that Spack will build. The following pages provide basic guidance on the following platforms: - * Ubuntu 24 LTS :ref:`tpl_ubuntu-label` - * macOS :ref:`tpl_mac-label` - * Livermore Computing (LC) :ref:`tpl_lc-label` + * Livermore Computing (LC) :ref:`setup_tpl_lc-label` + * macOS :ref:`setup_tpl_mac-label` + * Ubuntu 24 LTS :ref:`setup_tpl_ubuntu-label` .. note:: diff --git a/src/docs/sphinx/build_guide/setup_lc.rst b/src/docs/sphinx/build_guide/setup_tpl_lc.rst similarity index 99% rename from src/docs/sphinx/build_guide/setup_lc.rst rename to src/docs/sphinx/build_guide/setup_tpl_lc.rst index fb0515e144..c96c57af80 100644 --- a/src/docs/sphinx/build_guide/setup_lc.rst +++ b/src/docs/sphinx/build_guide/setup_tpl_lc.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _tpl_lc-label: +.. _setup_tpl_lc-label: ======================================================== Third-party Library (TPL) Livermore Computing (LC) Build diff --git a/src/docs/sphinx/build_guide/setup_mac.rst b/src/docs/sphinx/build_guide/setup_tpl_mac.rst similarity index 85% rename from src/docs/sphinx/build_guide/setup_mac.rst rename to src/docs/sphinx/build_guide/setup_tpl_mac.rst index 220382ec58..3e66d356c7 100644 --- a/src/docs/sphinx/build_guide/setup_mac.rst +++ b/src/docs/sphinx/build_guide/setup_tpl_mac.rst @@ -3,97 +3,11 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _tpl_builds-label: +.. _setup_tpl_mac-label: -=============================== -Third-party Library (TPL) Build -=============================== - ------------------ -Spack and Uberenv ------------------ - -Smith uses `Spack `_ to build it's TPLs. -This has been encapsulated using `Uberenv `_. -Uberenv helps by doing the following: - -* Pulls a blessed version of Spack locally -* If you are on a known operating system (like TOSS4), we have defined Spack configuration files - to keep Spack from building the world -* Installs our Spack packages into the local Spack Environment -* 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. - -It also generates a host-config file (``.cmake``) -at the root of Smith repository. This host-config defines all the required information for building -Smith. - ------------------- -Basic System Setup ------------------- - -We recommend installing some basic system-level development packages to minimize the -amount of packages that Spack will build. - -The following page provides basic guidance on the following platforms: - - * Ubuntu 24 LTS - * macOS - * Livermore Computing (LC) - -.. note:: - - Smith uses the LLVM plugin `Enzyme `_ to perform - automatic differentiation. Due to this you have to compile with an LLVM-based compiler. - We recommend ``clang``. - -Ubuntu 24 LTS -^^^^^^^^^^^^^ - -Install clang version 19 and make it the default compiler: - -.. code-block:: bash - - sudo apt install -y --no-install-recommends clang-19 libclang-19-dev clang-format-19 llvm-19 llvm-19-dev libzstd-dev libomp-19-dev gfortran-13 - # Set clang-19 as the default clang - sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-19 101 \ - && sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-19 101 \ - && sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-19 101 - -Install required build packages to minimize what Spack will build: - -.. code-block:: bash - - sudo apt install -y --no-install-recommends build-essential bzip2 cmake libopenblas-dev \ - lua5.2 liblua5.2-dev openmpi-bin libopenmpi-dev unzip - -Optionally you can install packages to generate documentation: - -.. code-block:: bash - - sudo apt install -y --no-install-recommends graphviz python3-sphinx texlive-full doxygen - -.. note:: - - The documentation packages require a lot of disk space. - -.. note:: - - We provide a basic Ubuntu 24 Spack environment file in ``scripts/spack/configs/linux_ubuntu_24`` that - may work for most people. If you want to try using that, skip to :ref:`building_tpls-label` - below and use this command line option instead ``--spack-env-file=scripts/spack/configs/linux_ubuntu_24/spack.yaml`` - -macOS -^^^^^ - -.. warning:: - These instructions are in development, but have been tested for M2 MacBooks. +=========================================== +Setup Third-party Library (TPL) macOS Build +=========================================== .. note:: View an example host-config for MacOS in ``host-configs/other/firion-macos_sonoma_aarch64-.cmake``. diff --git a/src/docs/sphinx/build_guide/setup_ubuntu.rst b/src/docs/sphinx/build_guide/setup_tpl_ubuntu.rst similarity index 99% rename from src/docs/sphinx/build_guide/setup_ubuntu.rst rename to src/docs/sphinx/build_guide/setup_tpl_ubuntu.rst index 28e9e2eb3d..158774dd18 100644 --- a/src/docs/sphinx/build_guide/setup_ubuntu.rst +++ b/src/docs/sphinx/build_guide/setup_tpl_ubuntu.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _tpl_builds-label: +.. _setup_tpl_ubuntu-label: ========================================= Third-party Library (TPL) Ubuntu 24 Build From 2f27fc07410fbfd7bfddebb92d58368186de0b38 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 12:56:15 -0800 Subject: [PATCH 03/15] fix toc --- src/docs/sphinx/build_guide/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index bb7f73c02b..a406562c07 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -50,16 +50,16 @@ The following pages provide basic guidance on the following platforms: .. note:: Smith uses the LLVM plugin `Enzyme `_ to perform - automatic differentiation. Due to this you have to compile with an LLVM-based compiler. - We recommend ``clang``. + automatic differentiation. To enable this functionality, you have to compile with an + LLVM-based compiler. We recommend ``clang``. .. toctree:: :hidden: :maxdepth: 2 - setup_ubuntu - setup_mac - setup_lc + setup_tpl_lc + setup_tpl_mac + setup_tpl_ubuntu building_tpls build From 9c21bb246c202d353da342fddbedbd266d8075d6 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 13:03:00 -0800 Subject: [PATCH 04/15] fix list --- src/docs/sphinx/build_guide/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index a406562c07..2fbc96c920 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -43,9 +43,9 @@ amount of packages that Spack will build. The following pages provide basic guidance on the following platforms: - * Livermore Computing (LC) :ref:`setup_tpl_lc-label` - * macOS :ref:`setup_tpl_mac-label` - * Ubuntu 24 LTS :ref:`setup_tpl_ubuntu-label` +* :ref:`Livermore Computing (LC) ` +* :ref:`macOS ` +* :ref:`Ubuntu 24 LTS ` .. note:: From f6db00a37590710dab30c8ef36e65033bc533c9c Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 13:03:29 -0800 Subject: [PATCH 05/15] slight tweak --- src/docs/sphinx/build_guide/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index 2fbc96c920..bff97cb99d 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -45,7 +45,7 @@ The following pages provide basic guidance on the following platforms: * :ref:`Livermore Computing (LC) ` * :ref:`macOS ` -* :ref:`Ubuntu 24 LTS ` +* :ref:`Ubuntu 24 ` .. note:: From 20b6f82fc92181991eb254ef4ca57a7ddcf57d63 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 13:13:45 -0800 Subject: [PATCH 06/15] fix toc? --- .../build_guide/{build.rst => build_smith.rst} | 2 +- src/docs/sphinx/build_guide/build_tpls.rst | 4 ++-- src/docs/sphinx/build_guide/index.rst | 16 ++++++++-------- .../{setup_tpl_lc.rst => setup_tpls_lc.rst} | 0 .../{setup_tpl_mac.rst => setup_tpls_macos.rst} | 0 ...tup_tpl_ubuntu.rst => setup_tpls_unbuntu.rst} | 0 6 files changed, 11 insertions(+), 11 deletions(-) rename src/docs/sphinx/build_guide/{build.rst => build_smith.rst} (99%) rename src/docs/sphinx/build_guide/{setup_tpl_lc.rst => setup_tpls_lc.rst} (100%) rename src/docs/sphinx/build_guide/{setup_tpl_mac.rst => setup_tpls_macos.rst} (100%) rename src/docs/sphinx/build_guide/{setup_tpl_ubuntu.rst => setup_tpls_unbuntu.rst} (100%) diff --git a/src/docs/sphinx/build_guide/build.rst b/src/docs/sphinx/build_guide/build_smith.rst similarity index 99% rename from src/docs/sphinx/build_guide/build.rst rename to src/docs/sphinx/build_guide/build_smith.rst index 53052b5645..82301ced86 100644 --- a/src/docs/sphinx/build_guide/build.rst +++ b/src/docs/sphinx/build_guide/build_smith.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _build-label: +.. _build_smith-label: ========================= Building Smith with CMake diff --git a/src/docs/sphinx/build_guide/build_tpls.rst b/src/docs/sphinx/build_guide/build_tpls.rst index e0898fe22c..c7c8726e0c 100644 --- a/src/docs/sphinx/build_guide/build_tpls.rst +++ b/src/docs/sphinx/build_guide/build_tpls.rst @@ -5,9 +5,9 @@ .. _building_tpls-label: -======================================================== +====================================== Building Smith's Third-party Libraries -======================================================== +====================================== It is now time to build Smith's Third-party Libraries (TPLs). Run the command with the compiler that you want to develop with: diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index bff97cb99d..bba32035ec 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -43,9 +43,9 @@ amount of packages that Spack will build. The following pages provide basic guidance on the following platforms: -* :ref:`Livermore Computing (LC) ` -* :ref:`macOS ` -* :ref:`Ubuntu 24 ` +* :ref:`Livermore Computing (LC) ` +* :ref:`macOS ` +* :ref:`Ubuntu 24 ` .. note:: @@ -57,10 +57,10 @@ The following pages provide basic guidance on the following platforms: :hidden: :maxdepth: 2 - setup_tpl_lc - setup_tpl_mac - setup_tpl_ubuntu - building_tpls - build + setup_tpls_lc + setup_tpls_macos + setup_tpls_ubuntu + build_tpls + build_smith diff --git a/src/docs/sphinx/build_guide/setup_tpl_lc.rst b/src/docs/sphinx/build_guide/setup_tpls_lc.rst similarity index 100% rename from src/docs/sphinx/build_guide/setup_tpl_lc.rst rename to src/docs/sphinx/build_guide/setup_tpls_lc.rst diff --git a/src/docs/sphinx/build_guide/setup_tpl_mac.rst b/src/docs/sphinx/build_guide/setup_tpls_macos.rst similarity index 100% rename from src/docs/sphinx/build_guide/setup_tpl_mac.rst rename to src/docs/sphinx/build_guide/setup_tpls_macos.rst diff --git a/src/docs/sphinx/build_guide/setup_tpl_ubuntu.rst b/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst similarity index 100% rename from src/docs/sphinx/build_guide/setup_tpl_ubuntu.rst rename to src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst From 6d6884b75a6787b0b7de9e280f5085b8f7b21317 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 14:08:07 -0800 Subject: [PATCH 07/15] fix tags --- src/docs/sphinx/build_guide/setup_tpls_lc.rst | 2 +- src/docs/sphinx/build_guide/setup_tpls_macos.rst | 2 +- src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/docs/sphinx/build_guide/setup_tpls_lc.rst b/src/docs/sphinx/build_guide/setup_tpls_lc.rst index c96c57af80..f908278697 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_lc.rst +++ b/src/docs/sphinx/build_guide/setup_tpls_lc.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpl_lc-label: +.. _setup_tpls_lc-label: ======================================================== Third-party Library (TPL) Livermore Computing (LC) Build diff --git a/src/docs/sphinx/build_guide/setup_tpls_macos.rst b/src/docs/sphinx/build_guide/setup_tpls_macos.rst index 3e66d356c7..9603a26e39 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_macos.rst +++ b/src/docs/sphinx/build_guide/setup_tpls_macos.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpl_mac-label: +.. _setup_tpls_mac-label: =========================================== Setup Third-party Library (TPL) macOS Build diff --git a/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst b/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst index 158774dd18..4eb06304b0 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst +++ b/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpl_ubuntu-label: +.. _setup_tpls_ubuntu-label: ========================================= Third-party Library (TPL) Ubuntu 24 Build From 8cf275fbc8bf9bb2cac165550e877b858ec843f7 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 14:08:42 -0800 Subject: [PATCH 08/15] unhide toc --- src/docs/sphinx/build_guide/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index bba32035ec..e17337945c 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -54,7 +54,6 @@ The following pages provide basic guidance on the following platforms: LLVM-based compiler. We recommend ``clang``. .. toctree:: - :hidden: :maxdepth: 2 setup_tpls_lc From 4be7198acb41fa15fbfa94aa7f8e896631b37fbc Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 14:12:58 -0800 Subject: [PATCH 09/15] dont ask --- src/docs/sphinx/build_guide/setup_tpls_macos.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/sphinx/build_guide/setup_tpls_macos.rst b/src/docs/sphinx/build_guide/setup_tpls_macos.rst index 9603a26e39..446e668b12 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_macos.rst +++ b/src/docs/sphinx/build_guide/setup_tpls_macos.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpls_mac-label: +.. _setup_tpls_macos-label: =========================================== Setup Third-party Library (TPL) macOS Build From c4813411dbb4d40ef10e9b1b12115a82b29b92d2 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 17:58:30 -0800 Subject: [PATCH 10/15] clean up build guide index --- src/docs/sphinx/build_guide/index.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index e17337945c..0b78f05d28 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -7,10 +7,14 @@ Build Guide =========== -------------------------------- -Third-party Library (TPL) Build -------------------------------- +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: +#. Setup the machine by installing the required system-level packages and generating a Spack environment file +#. Build third-party libraries using Spack and Uberenv to provide a consistent dependency stack +#. Build Smith itself using CMake once all dependencies are in place + +----------------- Spack and Uberenv ----------------- @@ -35,18 +39,24 @@ It also generates a host-config file (``.cmake``) at the root of Smith repository. This host-config defines all the required information for building Smith. +------------------ 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: +The following pages provide basic guidance on the following platforms and is where you should +start: * :ref:`Livermore Computing (LC) ` * :ref:`macOS ` * :ref:`Ubuntu 24 ` +At the end of each Setup guide, it has a link to the page that shows you how to build +the minimal set of Third-party Libraries for Smith; followed by a page on how to build +Smith from the generated host-config file via CMake. + .. note:: Smith uses the LLVM plugin `Enzyme `_ to perform @@ -54,7 +64,7 @@ The following pages provide basic guidance on the following platforms: LLVM-based compiler. We recommend ``clang``. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 setup_tpls_lc setup_tpls_macos From b54cc10dd3223170ceb6f957de054baa89104214 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 18:09:51 -0800 Subject: [PATCH 11/15] small tweak --- src/docs/sphinx/build_guide/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index 0b78f05d28..c0c75bef5a 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -18,7 +18,7 @@ how to build Smith from source. The process consists of the following high-level Spack and Uberenv ----------------- -Smith uses `Spack `_ to build it's TPLs. +Smith uses `Spack `_ to build it's Third-party Libraries (TPLs). This has been encapsulated using `Uberenv `_. Uberenv helps by doing the following: @@ -54,7 +54,7 @@ start: * :ref:`Ubuntu 24 ` At the end of each Setup guide, it has a link to the page that shows you how to build -the minimal set of Third-party Libraries for Smith; followed by a page on 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. .. note:: From 5f2c28d668af92d55f1f40d1a0eedac2580ca161 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 18:31:05 -0800 Subject: [PATCH 12/15] more consistent naming and labels --- src/docs/sphinx/build_guide/build_tpls.rst | 2 +- src/docs/sphinx/build_guide/index.rst | 12 ++++++------ .../{setup_tpls_lc.rst => setup_lc_tpl_build.rst} | 10 +++++----- ...etup_tpls_macos.rst => setup_macos_tpl_build.rst} | 10 +++++----- ...p_tpls_unbuntu.rst => setup_ubuntu_tpl_build.rst} | 11 ++++++----- 5 files changed, 23 insertions(+), 22 deletions(-) rename src/docs/sphinx/build_guide/{setup_tpls_lc.rst => setup_lc_tpl_build.rst} (98%) rename src/docs/sphinx/build_guide/{setup_tpls_macos.rst => setup_macos_tpl_build.rst} (98%) rename src/docs/sphinx/build_guide/{setup_tpls_unbuntu.rst => setup_ubuntu_tpl_build.rst} (98%) diff --git a/src/docs/sphinx/build_guide/build_tpls.rst b/src/docs/sphinx/build_guide/build_tpls.rst index c7c8726e0c..7ec82b4a60 100644 --- a/src/docs/sphinx/build_guide/build_tpls.rst +++ b/src/docs/sphinx/build_guide/build_tpls.rst @@ -3,7 +3,7 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _building_tpls-label: +.. _build_tpls-label: ====================================== Building Smith's Third-party Libraries diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index c0c75bef5a..6032ac85c5 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -49,9 +49,9 @@ amount of packages that Spack will build. The following pages provide basic guidance on the following platforms and is where you should start: -* :ref:`Livermore Computing (LC) ` -* :ref:`macOS ` -* :ref:`Ubuntu 24 ` +* :ref:`Livermore Computing (LC) ` +* :ref:`macOS ` +* :ref:`Ubuntu 24 ` 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 @@ -66,9 +66,9 @@ Smith from the generated host-config file via CMake. .. toctree:: :maxdepth: 1 - setup_tpls_lc - setup_tpls_macos - setup_tpls_ubuntu + setup_lc_tpl_build + setup_macos_tpl_build + setup_ubuntu_tpl_build build_tpls build_smith diff --git a/src/docs/sphinx/build_guide/setup_tpls_lc.rst b/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst similarity index 98% rename from src/docs/sphinx/build_guide/setup_tpls_lc.rst rename to src/docs/sphinx/build_guide/setup_lc_tpl_build.rst index f908278697..af362762ae 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_lc.rst +++ b/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst @@ -3,11 +3,11 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpls_lc-label: +.. _setup_lc_tpl_build-label: -======================================================== -Third-party Library (TPL) Livermore Computing (LC) Build -======================================================== +======================================== +Setup Livermore Computing (LC) TPL Build +======================================== We provide Spack Environment files for each of LC's systems: @@ -142,5 +142,5 @@ by another package, so you can also add it with this yaml section: Building Smith's Third-party Libraries -------------------------------------- -It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`build_tpls-label`. diff --git a/src/docs/sphinx/build_guide/setup_tpls_macos.rst b/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst similarity index 98% rename from src/docs/sphinx/build_guide/setup_tpls_macos.rst rename to src/docs/sphinx/build_guide/setup_macos_tpl_build.rst index 446e668b12..96399a9d76 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_macos.rst +++ b/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst @@ -3,11 +3,11 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpls_macos-label: +.. _setup_macos_tpl_build-label: -=========================================== -Setup Third-party Library (TPL) macOS Build -=========================================== +===================== +Setup macOS TPL Build +===================== .. note:: View an example host-config for MacOS in ``host-configs/other/firion-macos_sonoma_aarch64-.cmake``. @@ -243,5 +243,5 @@ by another package, so you can also add it with this yaml section: Building Smith's Third-party Libraries -------------------------------------- -It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`build_tpls-label`. diff --git a/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst b/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst similarity index 98% rename from src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst rename to src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst index 4eb06304b0..8214444a98 100644 --- a/src/docs/sphinx/build_guide/setup_tpls_unbuntu.rst +++ b/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst @@ -3,11 +3,12 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) -.. _setup_tpls_ubuntu-label: +.. _setup_ubuntu_tpl_build-label: + +========================= +Setup Ubuntu 24 TPL Build +========================= -========================================= -Third-party Library (TPL) Ubuntu 24 Build -========================================= Install clang version 19 and make it the default compiler: @@ -156,4 +157,4 @@ by another package, so you can also add it with this yaml section: Building Smith's Third-party Libraries -------------------------------------- -It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`building_tpls-label`. +It is now time to build Smith's Third-party Libraries (TPLs). For detailed instructions see :ref:`build_tpls-label`. From 4161c943a89a3522f7769ef42ed66f7836a5a279 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 18:34:49 -0800 Subject: [PATCH 13/15] more labels --- src/docs/sphinx/build_guide/build_tpls.rst | 2 +- src/docs/sphinx/build_guide/setup_lc_tpl_build.rst | 2 +- src/docs/sphinx/build_guide/setup_macos_tpl_build.rst | 4 ++-- src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/docs/sphinx/build_guide/build_tpls.rst b/src/docs/sphinx/build_guide/build_tpls.rst index 7ec82b4a60..1360f2895b 100644 --- a/src/docs/sphinx/build_guide/build_tpls.rst +++ b/src/docs/sphinx/build_guide/build_tpls.rst @@ -43,5 +43,5 @@ Building Smith -------------- Finally, with the TPL's built and the host-config file, you can build Smith -for more detail instructions on how to build Smith, see :ref:`build-label`. +for more detail instructions on how to build Smith, see :ref:`build_smith-label`. diff --git a/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst b/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst index af362762ae..542586da31 100644 --- a/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst +++ b/src/docs/sphinx/build_guide/setup_lc_tpl_build.rst @@ -18,7 +18,7 @@ Unless otherwise specified, Spack will default to a compiler. This is generally developing large codes. To specify which compiler to use add the compiler specification to the ``--spec`` Uberenv command line option. We provide recommended Spack specs for LC in ``scripts/spack/specs.json``. -You can use these directly in the ``uberenv.py`` command in the :ref:`building_tpls-label` +You can use these directly in the ``uberenv.py`` command in the :ref:`build_tpls-label` section by substituting the values in these two command line options: ``--spack-env-file=ubuntu24.yaml --spec="%clang_19"``. .. note:: diff --git a/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst b/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst index 96399a9d76..fb087253b0 100644 --- a/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst +++ b/src/docs/sphinx/build_guide/setup_macos_tpl_build.rst @@ -44,7 +44,7 @@ This is also useful for a few additional packages: .. note:: We provide a basic MacOS Spack environment file that - may work for most people. If you want to try using that, skip to :ref:`building_tpls-label` + may work for most people. If you want to try using that, skip to :ref:`build_tpls-label` below and use this command line option instead ``--spack-env-file=scripts/spack/configs/darwin/spack.yaml``. You will likely need to update the versions of packages to match the versions installed by Homebrew. The versions for all installed packages can be listed via the command ``brew list --versions``. @@ -119,7 +119,7 @@ Unless otherwise specified, Spack will default to a compiler. This is generally developing large codes. To specify which compiler to use add the compiler specification to the ``--spec`` Uberenv command line option. We provide recommended Spack specs for LC in ``scripts/spack/specs.json``. -You can use these directly in the ``uberenv.py`` command in the :ref:`building_tpls-label` +You can use these directly in the ``uberenv.py`` command in the :ref:`build_tpls-label` section by substituting the values in these two command line options: ``--spack-env-file=ubuntu24.yaml --spec="%clang_19"``. .. note:: diff --git a/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst b/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst index 8214444a98..5027c1d68e 100644 --- a/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst +++ b/src/docs/sphinx/build_guide/setup_ubuntu_tpl_build.rst @@ -40,7 +40,7 @@ Optionally you can install packages to generate documentation: .. note:: We provide a basic Ubuntu 24 Spack environment file in ``scripts/spack/configs/linux_ubuntu_24`` that - may work for most people. If you want to try using that, skip to :ref:`building_tpls-label` + may work for most people. If you want to try using that, skip to :ref:`build_tpls-label` below and use this command line option instead ``--spack-env-file=scripts/spack/configs/linux_ubuntu_24/spack.yaml`` From d67bcf612c5f124f0e07f228a539fcd74e43bceb Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 18:39:40 -0800 Subject: [PATCH 14/15] move for labels --- src/docs/sphinx/build_guide/index.rst | 2 ++ src/docs/sphinx/dev_guide/docker_env.rst | 2 +- src/docs/sphinx/dev_guide/testing.rst | 2 +- src/docs/sphinx/quickstart.rst | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index 6032ac85c5..c3d26dc11b 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -3,6 +3,8 @@ .. ## .. ## SPDX-License-Identifier: (BSD-3-Clause) +.. _build_guide-label: + =========== Build Guide =========== diff --git a/src/docs/sphinx/dev_guide/docker_env.rst b/src/docs/sphinx/dev_guide/docker_env.rst index b3da247d0b..5ac8be6a21 100644 --- a/src/docs/sphinx/dev_guide/docker_env.rst +++ b/src/docs/sphinx/dev_guide/docker_env.rst @@ -34,7 +34,7 @@ If you haven't used Docker before, it is recommended that you check out the The ``-v`` option to ``docker run`` mounts a `Docker volume `_ into the container. This means that part of your filesystem (in this case, your copy of the Smith repo) will be accessible from the container. -6. Follow the build instructions detailed in the :ref:`quickstart guide `, using the host-config in ``host-configs/docker`` that +6. Follow the build instructions detailed in :ref:`build_smith-label`, using the host-config in ``host-configs/docker`` that corresponds to the compiler you've selected. These commands should be run using the terminal you opened in the previous step. Due to issues with the docker bind-mount permissions, it is suggested that you set the build and install directories to be outside of the repository. diff --git a/src/docs/sphinx/dev_guide/testing.rst b/src/docs/sphinx/dev_guide/testing.rst index 99a80ee265..6b1ff4a709 100644 --- a/src/docs/sphinx/dev_guide/testing.rst +++ b/src/docs/sphinx/dev_guide/testing.rst @@ -45,7 +45,7 @@ Requirements: used as reference. #. **Build the code.** - Build code with the normal steps. More info in the :ref:`quickstart-label`. + Build code with the normal steps. More info in the :ref:`build_smith-label`. This generates a script in the build directory called ``ats.sh``. #. **Run integration tests.** diff --git a/src/docs/sphinx/quickstart.rst b/src/docs/sphinx/quickstart.rst index d3d010290b..ea6ac60165 100644 --- a/src/docs/sphinx/quickstart.rst +++ b/src/docs/sphinx/quickstart.rst @@ -79,7 +79,7 @@ build with that compiler. Building Smith's Dependencies via Spack/uberenv ----------------------------------------------- -For detailed instructions see :ref:`tpl_builds-label`. +For detailed instructions see :ref:`build_guide-label`. .. note:: This is optional if you are on an LC machine and are in the ``smithdev`` group as we have From d9653272b209c5241709a57477c84d1b6ff9ece5 Mon Sep 17 00:00:00 2001 From: Chris White Date: Tue, 13 Jan 2026 18:48:53 -0800 Subject: [PATCH 15/15] add more basic structure --- src/docs/index.rst | 3 ++- src/docs/sphinx/build_guide/index.rst | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/src/docs/index.rst b/src/docs/index.rst index 89f7d46c2c..e1bb1504d0 100644 --- a/src/docs/index.rst +++ b/src/docs/index.rst @@ -15,7 +15,8 @@ computing architectures. It heavily leverages the `MFEM finite element library < This project is under heavy development and is currently a pre-alpha release. Functionality and interfaces may change rapidly as development progresses. -* :ref:`Quickstart/Build Instructions ` +* :ref:`Quickstart ` +* :ref:`build_guide-label` * `Source Documentation `_ diff --git a/src/docs/sphinx/build_guide/index.rst b/src/docs/sphinx/build_guide/index.rst index c3d26dc11b..b19e1ff885 100644 --- a/src/docs/sphinx/build_guide/index.rst +++ b/src/docs/sphinx/build_guide/index.rst @@ -13,14 +13,14 @@ This guide provides instructions on how to build or install all dependencies of how to build Smith from source. The process consists of the following high-level phases: #. Setup the machine by installing the required system-level packages and generating a Spack environment file -#. Build third-party libraries using Spack and Uberenv to provide a consistent dependency stack +#. Build Third-party Libraries (TPLs) using Spack and Uberenv to provide a consistent dependency stack #. Build Smith itself using CMake once all dependencies are in place ----------------- Spack and Uberenv ----------------- -Smith uses `Spack `_ to build it's Third-party Libraries (TPLs). +Smith uses `Spack `_ to build it's TPLs. This has been encapsulated using `Uberenv `_. Uberenv helps by doing the following: @@ -65,7 +65,21 @@ Smith from the generated host-config file via CMake. automatic differentiation. To enable this functionality, you have to compile with an LLVM-based compiler. We recommend ``clang``. +--------------------------- +Build Third-party Libraries +--------------------------- + +For more information see :ref:`build_tpls-label`. + +---------------------- +Build Smith with CMake +---------------------- + +For more information see :ref:`build_smith-label`. + + .. toctree:: + :hidden: :maxdepth: 1 setup_lc_tpl_build