WIP: Build docs reorg

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 <quickstart-label>`
+*  :ref:`Quickstart <quickstart-label>`
+*  :ref:`build_guide-label`
 *  `Source Documentation <doxygen/html/index.html>`_
 
 
@@ -36,5 +37,6 @@ LLNL-CODE-805541
 
    sphinx/quickstart
    sphinx/user_guide/index
+   sphinx/build_guide/index
    sphinx/dev_guide/index
    sphinx/theory_reference/index

src/docs/sphinx/build_guide/build_smith.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_smith-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 <config_dependent_name>.cmake
+
+   # If you are on an LC machine and want to use our public pre-built dependencies
+   $ python3 ./config-build.py -hc host-configs/<machine name>-<SYS_TYPE>-<compiler>.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 <more CMake build options...>
+
+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 <[email protected]>`_ for access.
+
+Some build options frequently used by Smith include:
+
+* ``CMAKE_BUILD_TYPE``: Specifies the build type, see the `CMake docs <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`_
+* ``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-<system-and-toolchain>
+   $ 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)
+
+
+

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)
+
+.. _build_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=<path/outside/repository> --spack-env-file=<path/to/spack.yaml> --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=<Path to Spack environment file>`` (use specific Spack environment configuration file)
+* ``--prefix=<Path>`` (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 ``[email protected]``.
+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_smith-label`.
+

src/docs/sphinx/build_guide/index.rst

@@ -0,0 +1,91 @@
+.. ## 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-label:
+
+===========
+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:
+
+#. Setup the machine by installing the required system-level packages and generating a Spack environment file
+#. 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 <https://github.com/spack/spack>`_ to build it's TPLs.
+This has been encapsulated using `Uberenv <https://github.com/LLNL/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 (``<config_dependent_name>.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 and is where you should
+start:
+
+* :ref:`Livermore Computing (LC) <setup_lc_tpl_build-label>`
+* :ref:`macOS <setup_macos_tpl_build-label>`
+* :ref:`Ubuntu 24 <setup_ubuntu_tpl_build-label>`
+
+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.
+
+.. note::
+
+   Smith uses the LLVM plugin `Enzyme <https://github.com/EnzymeAD/Enzyme>`_ to perform
+   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
+   setup_macos_tpl_build
+   setup_ubuntu_tpl_build
+   build_tpls
+   build_smith
+
+