From 08443bce75c19f58cb86ae9a575827fcb7970a96 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Thu, 23 Jun 2022 14:44:59 -0700 Subject: [PATCH 01/10] First pass a reworking, expanding documentation of build options. --- .../sphinx/quickstart_guide/config_build.rst | 236 ++++++++++++------ 1 file changed, 163 insertions(+), 73 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index 502c9e23f1..f784645fba 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -25,7 +25,7 @@ Requirements, Dependencies, and Supported Compilers Basic requirements: ~~~~~~~~~~~~~~~~~~~ - * C++ Compiler with C++11 support + * C++ Compiler with C++11 support at a minimum. Depending on which Axom features are enables, a C++14 compliant compiler may be required. * CMake * Fortran Compiler (optional) @@ -47,11 +47,25 @@ Axom's dependencies come in two flavors: * Library: contain code that axom must link against * Tool: executables that we use as part of our development process, e.g. to generate documentation and format our code. -Unless otherwise marked, the dependencies are optional. +Unless otherwise noted otherwise in the following discussion, Axom +dependencies are optional. + +.. note:: A typical Axom user need only understand how to enable Axom features + and provide a valid installation path for each required library + dependency for each enabled feature. Library Dependencies """""""""""""""""""" +The following table lists: + + * External library dependencies for Axom, with links to documentation for + each library + * Which Axom components may require a dependency for access to all component + capabilities + * The CMake variable that must be set to the path of the library dependency + installation enable it capabilities in the Axom component + ================== ==================================== ====================== Library Dependent Components Build system variable ================== ==================================== ====================== @@ -75,16 +89,24 @@ Library Dependencies .. _Umpire: https://umpire.readthedocs.io/en/latest/ Each library dependency has a corresponding build system variable -(with the suffix ``_DIR``) to supply the path to the library's installation directory. -For example, ``hdf5`` has a corresponding variable ``HDF5_DIR``. +(with the suffix ``_DIR``) to supply the path to the library's installation +directory. For example, ``hdf5`` has a corresponding variable ``HDF5_DIR``. -.. note:: - Optional `c2c` library is currently only available for configurations on LLNL clusters. +.. note:: Optional `c2c` library is currently only available for configurations + on LLNL clusters. Tool Dependencies """"""""""""""""" +The following table lists: + + * External tool dependencies for Axom, with links to documentation for + each tool + * The purpose of each tool; i.e., how it is used in Axom development + * The CMake variable that must be set to the path of the tool + installation to enable it in Axom + ================== ==================================== ====================== Tool Purpose Build System Variable ================== ==================================== ====================== @@ -103,14 +125,13 @@ Tool Dependencies .. _Shroud: https://shroud.readthedocs.io/en/develop/ .. _Sphinx: http://www.sphinx-doc.org/en/master/ -Each tool has a corresponding build system variable (with the suffix ``_EXECUTABLE``) -to supply the tool's executable path. For example, ``sphinx`` has a corresponding build -system variable ``SPHINX_EXECUTABLE``. +Each tool has a corresponding build system variable (with the suffix +``_EXECUTABLE``) to supply a path to the tool executable. For example, +``sphinx`` has a corresponding build system variable ``SPHINX_EXECUTABLE``. -.. note:: - To get a full list of all dependencies of Axom's dependencies in an ``uberenv`` - build of our TPLs, please go to the TPL root directory and - run the following spack command ``./spack/bin/spack spec axom``. +.. note:: To get a full list of all Axom dependencies in an ``uberenv`` + build of our TPLs, please go to the TPL root directory and + run the following Spack command ``./spack/bin/spack spec axom``. .. _tplbuild-label: @@ -120,34 +141,35 @@ Building and Installing Third-party Libraries --------------------------------------------- We use the `Spack Package Manager `_ -to manage and build TPL dependencies for Axom. The Spack process works on Linux and macOS -systems. Axom does not currently have a tool to automatically build dependencies for -Windows systems. +to manage and build TPL dependencies for Axom. The Spack process works on +Linux and macOS systems. Axom does not currently have a tool to automatically +build dependencies for Windows systems. -To make the TPL process easier (you don't really need to learn much about Spack) and -automatic, we drive it with a python script called ``uberenv.py``, which is located in the -``scripts/uberenv`` directory. Running this script does several things: +To make the TPL management process easier (you don't really need to learn much +about Spack) and automatic, we drive it with a python script called +``uberenv.py``, which is located in the ``scripts/uberenv`` directory. +Running this script does several things: * Clones the Spack repo from GitHub and checks out a specific version that we have tested. - * Configures Spack compiler sets, adds custom package build rules and sets any options - specific to Axom. - * Invokes Spack to build a complete set of TPLs for each configuration and generates a - *host-config* file that captures all details of the configuration and build - dependencies. + * Configures Spack compiler sets, adds custom package build rules and sets + any options specific to Axom. + * Invokes Spack to build a complete set of TPLs for each configuration and + generates a *host-config* (i.e., CMake cache file) file that includes all + details of the configuration and build dependencies. The figure illustrates what the script does. .. figure:: Uberenv.jpg -The uberenv script is run from Axom's top-level directory like this:: +The uberenv script is run from the Axom top-level directory like this:: $ python ./scripts/uberenv/uberenv.py --prefix {install path} \ --spec spec \ [ --mirror {mirror path} ] -For more details about ``uberenv.py`` and the options it supports, +For more details about ``uberenv.py`` and the options it supports, please see the `uberenv docs `_ You can also see examples of how Spack spec names are passed to ``uberenv.py`` @@ -162,7 +184,7 @@ LC platforms at LLNL. These scripts are located in the directory Building and Installing Axom ---------------------------- -This section provides essential instructions for building the code. +This section provides essential instructions for building the Axom code. Axom uses `BLT `_, a CMake-based system, to configure and build the code. There are two ways to configure Axom: @@ -170,8 +192,8 @@ configure and build the code. There are two ways to configure Axom: * Using a helper script ``config-build.py`` * Directly invoke CMake from the command line. -Either way, we typically pass in many of the configuration options and variables -using platform-specific *host-config* files. +Either way, we typically pass in many of the configuration options and +variables using platform-specific *host-config* files. .. _hostconfig-label: @@ -179,19 +201,20 @@ using platform-specific *host-config* files. Host-config files ~~~~~~~~~~~~~~~~~ -Host-config files help make Axom's configuration process more automatic and +Host-config files help make the Axom configuration process more automatic and reproducible. A host-config file captures all build configuration -information used for the build such as compiler version and options, -paths to all TPLs, etc. When passed to CMake, a host-config file initializes -the CMake cache with the configuration specified in the file. +information used for the build, such as compiler version and options, +paths to all TPLs, etc. When passed to CMake +(via the ``-C path/to/hostconfig/file/foo.cmake``, the host-config file +initializes the CMake cache with the configuration specified in the file. We noted in the previous section that the uberenv script generates a host-config file for each item in the Spack spec list given to it. -These files are generated by spack in the directory where the +These files are generated by Spack in the directory where the TPLs were installed. The name of each file contains information about the platform and spec. -For more information, see `BLT's host-config documentation `_. +For more information, see `BLT host-config documentation `_. Python helper script @@ -201,10 +224,9 @@ The easiest way to configure the code for compilation is to use the ``config-build.py`` python script located in Axom's base directory; e.g.,:: - $ ./config-build.py -hc {host-config path} + $ ./config-build.py -hc path/to/host-config/file/ -This script requires that you pass it a *host-config* file. The script runs -CMake and passes it the host-config. +The script runs CMake and passes it the host-config. See :ref:`hostconfig-label` for more information. Running the script, as in the example above, will create two directories to @@ -219,10 +241,12 @@ in the install directory, go into the build directory and run ``make``; e.g.,:: $ make install .. caution :: When building on LC systems, please don't compile on login nodes. + You will incur the wrath of others and you really don't want that, + do you? .. tip :: Most make targets can be run in parallel by supplying the '-j' flag - along with the number of threads to use. - E.g. ``$ make -j8`` runs make using 8 threads. + along with the number of threads to use. + E.g. ``$ make -j8`` runs make using 8 threads. The python helper script accepts other arguments that allow you to specify explicitly the build and install paths and build type. Following CMake @@ -232,13 +256,13 @@ i.e.,:: $ ./config-build.py -You can also pass extra CMake configuration variables through the script; e.g.,:: +You can also pass extra CMake configuration variables to the script; e.g.,:: - $ ./config-build.py -hc {host-config file name} \ + $ ./config-build.py -hc path/to/host-config/file/ \ -DBUILD_SHARED_LIBS=ON \ -DENABLE_FORTRAN=OFF -This will configure cmake to build shared libraries and disable fortran +This will configure CMake to build shared libraries and disable fortran for the generated configuration. @@ -276,68 +300,134 @@ directly to CMake; for example:: CMake Configuration Options -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- + +The tables in this section summarize the main build system options in Axom. -Here are the key build system options in Axom: +Axom Components, Tests, Examples, etc. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------+---------+----------------------------------------+ | OPTION | Default | Description | +==============================+=========+========================================+ -| AXOM_DEBUG_DEFINE | DEFAULT | Controls whether the `AXOM_DEBUG` | -| | | compiler define is enabled | -| | | | -| | | By DEFAULT, it is enabled for | -| | | `Debug` and `RelWithDebInfo` configs | -| | | but this can be overridden by setting | -| | | `AXOM_DEBUG_DEFINE` to `ON` or `OFF` | -+------------------------------+---------+----------------------------------------+ | AXOM_ENABLE_ALL_COMPONENTS | ON | Enable all components by default | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_ | ON | Enables the axom component named 'foo' | +| AXOM_ENABLE_ | ON | Enables the axom component named 'Foo' | | | | | | | | (e.g. AXOM_ENABLE_SIDRE) | -| | | for the sidre component | +| | | for the Sidre component | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_DOCS | ON | Builds documentation | +| AXOM_ENABLE_EXAMPLES | ON | Build Axom examples | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_EXAMPLES | ON | Builds examples | +| AXOM_ENABLE_TESTS | ON | Build Axom unit tests | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_TESTS | ON | Builds unit tests | +| ENABLE_BENCHMARKS | OFF | Enable Google benchmark | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_TOOLS | ON | Builds tools | +| AXOM_ENABLE_DOCS | ON | Enable Axom documentation to be built | +| | | as a make target | +------------------------------+---------+----------------------------------------+ -| BUILD_SHARED_LIBS | OFF | Build shared libraries. | -| | | Default is Static libraries | + +If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable the desired +components (other than 'core', which is always enabled). + +See `Axom software documentation <../../../index.html>`_ +for a list of Axom's components and their dependencies. + +See :ref:`dependencies-label` for configuration variables to specify paths +to Axom's dependencies. + +.. note:: ``AXOM_ENABLE_EXAMPLES``, ``AXOM_ENABLE_TESTS``, and ``AXOM_ENABLE_DOCS`` + are *CMake-dependent options*. Thus, if a non-Axom prefix variable form + is ON, such as ``ENABLE_TESTS``, tests can be enabled in other packages in + integrated build and turned off in Axom by setting the Axom prefix form, + ``AXOM_ENABLE_TESTS`` to OFF. + + +Axom Build Option, Compiler Support, and Parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++------------------------------+---------+----------------------------------------+ +| OPTION | Default | Description | ++==============================+=========+========================================+ +| AXOM_DEBUG_DEFINE | DEFAULT | Controls whether the `AXOM_DEBUG` | +| | | compiler define is enabled | +| | | | +| | | By DEFAULT, it is enabled for | +| | | `Debug` and `RelWithDebInfo` configs | +| | | but this can be overridden by setting | +| | | `AXOM_DEBUG_DEFINE` to `ON` or `OFF` | +------------------------------+---------+----------------------------------------+ | ENABLE_ALL_WARNINGS | ON | Enable extra compiler warnings | | | | in all build targets | +------------------------------+---------+----------------------------------------+ -| ENABLE_BENCHMARKS | OFF | Enable google benchmark | +| ENABLE_WARNINGS_AS_ERRORS | OFF | Compiler warnings treated as errors | +------------------------------+---------+----------------------------------------+ -| ENABLE_CODECOV | ON | Enable code coverage via gcov | +| BUILD_SHARED_LIBS | OFF | Build shared libraries. | +| | | Default is Static libraries | +------------------------------+---------+----------------------------------------+ -| ENABLE_FORTRAN | ON | Enable Fortran compiler support | +| ENABLE_FORTRAN | OFF | Enable Fortran compiler support | +------------------------------+---------+----------------------------------------+ | ENABLE_MPI | OFF | Enable MPI | +------------------------------+---------+----------------------------------------+ | ENABLE_OPENMP | OFF | Enable OpenMP | +------------------------------+---------+----------------------------------------+ -| ENABLE_WARNINGS_AS_ERRORS | OFF | Compiler warnings treated as errors | -| | | errors. | +| ENABLE_CUDA | OFF | Enable CUDA | ++------------------------------+---------+----------------------------------------+ +| ENABLE_HIP | OFF | Enable HIP | +------------------------------+---------+----------------------------------------+ -If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable the desired -components (other than 'core', which is always enabled). - -See `Axom software documentation <../../../index.html>`_ -for a list of Axom's components and their dependencies. +Note that, in most Axom components, node-level parallelism features, enabled with +OpenMP, CUDA (NVIDIA GPUs), and HIP (AMD GPUs), are implemented using RAJA. These +features are described in :ref:`dependencies-label`. In addition, enabling such +features may require additional build options to be provided, which are summarized +in the following table. + ++------------------------------+------------------------------------------+ +| OPTION | Description | ++==============================+==========================================+ +| RAJA_DIR | RAJA installation directory as described | +| | in :ref:`dependencies-label`. +| | | +| | RAJA must be built with support enabled | +| | for OpenMP, CUDA, or HIP to use features | +| | enabled by those parallel programming | +| | models in Axom. | ++------------------------------+------------------------------------------+ +| CUDA_TOOLKIT_ROOT_DIR | Path to CUDA software stack installation | ++------------------------------+------------------------------------------+ +| CMAKE_CUDA_COMPILER | Path to CUDA compiler (e.g., nvcc) | ++------------------------------+------------------------------------------+ +| CMAKE_CUDA_ARCHITECTURES | Target architecture(s) for CUDA | ++------------------------------+------------------------------------------+ +| HIP_ROOT_DIR | Path to HIP software stack installation | ++------------------------------+------------------------------------------+ +| CMAKE_HIP_ARCHITECTURES | Target architecture(s) for HIP | ++------------------------------+------------------------------------------+ + +.. important:: Depending on the version of RAJA you are using, you may need to + set the C++ standard to C++14. .. note :: To configure the version of the C++ standard, you can supply one of the following values for **BLT_CXX_STD**: 'c++11' or 'c++14'. Axom requires at least 'c++11', the default value. -See :ref:`dependencies-label` for configuration variables to specify paths -to Axom's dependencies. + +Tools and Features Primarily for Developers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++------------------------------------------+---------+----------------------------------------+ +| OPTION | Default | Description | ++==========================================+=========+========================================+ +| AXOM_ENABLE_TOOLS | ON | Enable Axom development tools | ++------------------------------------------+---------+----------------------------------------+ +| ENABLE_CODECOV | ON | Enable code coverage via gcov | ++------------------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_ANNOTATIONS | OFF | Enable source code annotations to | +| | | facilitate performance evaluation | ++------------------------------------------+---------+----------------------------------------+ +| AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS | OFF | Enable building an expanded set of | +| | | tests for the Axom Quest component | ++------------------------------------------+---------+----------------------------------------+ Make targets From a8f781f92b6ec6f9b957c0b96db01e5c23779d3d Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Fri, 24 Jun 2022 10:42:07 -0700 Subject: [PATCH 02/10] Proofread pass, fix formatting issues --- .../sphinx/quickstart_guide/config_build.rst | 152 +++++++++--------- 1 file changed, 80 insertions(+), 72 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index f784645fba..cfe5e43103 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -25,17 +25,19 @@ Requirements, Dependencies, and Supported Compilers Basic requirements: ~~~~~~~~~~~~~~~~~~~ - * C++ Compiler with C++11 support at a minimum. Depending on which Axom features are enables, a C++14 compliant compiler may be required. - * CMake + * C++ Compiler with C++11 support at a minimum. Depending on which Axom + features you enable, a C++14 compliant compiler may be required. + * CMake. Minimum version required is 3.8.2. If using CUDA, 3.9 is the minimum + required version. * Fortran Compiler (optional) Supported Compilers ~~~~~~~~~~~~~~~~~~~ -Axom supports a wide variety of compilers. -Please see the ``/scripts/spack/configs//compilers.yaml`` -for an up to date list of the currently supported and tested compilers for -each platform. +Axom supports a wide variety of compilers. Please see the file +``axom/scripts/spack/configs//compilers.yaml`` +for the current list of supported and tested compilers for the platforms we +test on. .. _dependencies-label: @@ -44,11 +46,12 @@ External Dependencies Axom's dependencies come in two flavors: -* Library: contain code that axom must link against -* Tool: executables that we use as part of our development process, e.g. to generate documentation and format our code. +* Libraries. These contain code that axom must link against. +* Tools. These are executables that we use during code development; e.g., +generate documentation, format code, etc. -Unless otherwise noted otherwise in the following discussion, Axom -dependencies are optional. +Unless noted otherwise in the following discussion, Axom dependencies are +optional. .. note:: A typical Axom user need only understand how to enable Axom features and provide a valid installation path for each required library @@ -59,12 +62,13 @@ Library Dependencies The following table lists: - * External library dependencies for Axom, with links to documentation for + * Axom external library dependencies and links to documentation for each library - * Which Axom components may require a dependency for access to all component - capabilities - * The CMake variable that must be set to the path of the library dependency - installation enable it capabilities in the Axom component + * Which libraries are required or optional dependencies for Axom. While + most Axom libraries are not required, they are required to access all + capabilities of componements listed. + * The CMake variable that must be set to the path of each library + installation when configuring a build with the library ================== ==================================== ====================== Library Dependent Components Build system variable @@ -88,7 +92,7 @@ The following table lists: .. _SCR: https://computation.llnl.gov/projects/scalable-checkpoint-restart-for-mpi .. _Umpire: https://umpire.readthedocs.io/en/latest/ -Each library dependency has a corresponding build system variable +Note that each library dependency has a corresponding build system variable (with the suffix ``_DIR``) to supply the path to the library's installation directory. For example, ``hdf5`` has a corresponding variable ``HDF5_DIR``. @@ -101,11 +105,11 @@ Tool Dependencies The following table lists: - * External tool dependencies for Axom, with links to documentation for + * Axom external tool dependencies, with links to documentation for each tool * The purpose of each tool; i.e., how it is used in Axom development * The CMake variable that must be set to the path of the tool - installation to enable it in Axom + installation to enable its use in Axom ================== ==================================== ====================== Tool Purpose Build System Variable @@ -142,27 +146,28 @@ Building and Installing Third-party Libraries We use the `Spack Package Manager `_ to manage and build TPL dependencies for Axom. The Spack process works on -Linux and macOS systems. Axom does not currently have a tool to automatically -build dependencies for Windows systems. +Linux and macOS systems. Although we test Axom on Windows and some Axom users +build their applications for Windows, Axom does not currently have a tool to +automatically build dependencies for Windows systems. -To make the TPL management process easier (you don't really need to learn much -about Spack) and automatic, we drive it with a python script called +To make the TPL management process easier and automatic (you don't really need +to learn much about Spack), we drive it with a Python script called ``uberenv.py``, which is located in the ``scripts/uberenv`` directory. Running this script does several things: - * Clones the Spack repo from GitHub and checks out a specific version + * It clones the Spack repo from GitHub and checks out a specific version that we have tested. - * Configures Spack compiler sets, adds custom package build rules and sets - any options specific to Axom. - * Invokes Spack to build a complete set of TPLs for each configuration and - generates a *host-config* (i.e., CMake cache file) file that includes all + * It configures Spack compiler sets, adds custom package build rules, and + sets any options specific to Axom. + * It invokes Spack to build a complete set of TPLs for each configuration and + generates a *host-config* file (i.e., CMake cache file) that includes all details of the configuration and build dependencies. The figure illustrates what the script does. .. figure:: Uberenv.jpg -The uberenv script is run from the Axom top-level directory like this:: +The uberenv script is run from the top-level Axom directory like this:: $ python ./scripts/uberenv/uberenv.py --prefix {install path} \ --spec spec \ @@ -173,7 +178,7 @@ For more details about ``uberenv.py`` and the options it supports, please see the `uberenv docs `_ You can also see examples of how Spack spec names are passed to ``uberenv.py`` -in the python scripts we use to build TPLs for the Axom development team on +in the Python scripts we use to build TPLs for Axom development on LC platforms at LLNL. These scripts are located in the directory ``scripts/llnl_scripts``. @@ -189,8 +194,8 @@ This section provides essential instructions for building the Axom code. Axom uses `BLT `_, a CMake-based system, to configure and build the code. There are two ways to configure Axom: - * Using a helper script ``config-build.py`` - * Directly invoke CMake from the command line. + * Using the helper Python script ``config-build.py`` + * Directly invoke CMake from the command line Either way, we typically pass in many of the configuration options and variables using platform-specific *host-config* files. @@ -203,16 +208,15 @@ Host-config files Host-config files help make the Axom configuration process more automatic and reproducible. A host-config file captures all build configuration -information used for the build, such as compiler version and options, +information used for a build, such as compiler version and options, paths to all TPLs, etc. When passed to CMake -(via the ``-C path/to/hostconfig/file/foo.cmake``, the host-config file -initializes the CMake cache with the configuration specified in the file. +(via the ``-C path/to/hostconfig/file/foo.cmake`` option), the host-config file +initializes the CMake cache with the configuration contained in the file. -We noted in the previous section that the uberenv script generates a -host-config file for each item in the Spack spec list given to it. -These files are generated by Spack in the directory where the -TPLs were installed. The name of each file contains information about the -platform and spec. +We noted earlier that the uberenv script generates a host-config file for each +item in the Spack spec list given to it. These files are generated by Spack in +the directory where the TPLs were installed. The name of each file contains +information about the platform and spec. For more information, see `BLT host-config documentation `_. @@ -220,21 +224,21 @@ For more information, see `BLT host-config documentation -The script runs CMake and passes it the host-config. +The script runs CMake and passes it the given host-config file. See :ref:`hostconfig-label` for more information. -Running the script, as in the example above, will create two directories to -hold the build and install contents for the platform and compiler specified -in the name of the host-config file. +Running the script, as above, will create two directories to hold the build +and install contents for the platform and compiler with names that match +the name of the host-config file. To build the code and install the header files, libraries, and documentation -in the install directory, go into the build directory and run ``make``; e.g.,:: +in the install directory, go into the build directory and run ``make`` and +``make install``:: $ cd {build directory} $ make @@ -245,18 +249,21 @@ in the install directory, go into the build directory and run ``make``; e.g.,:: do you? .. tip :: Most make targets can be run in parallel by supplying the '-j' flag - along with the number of threads to use. - E.g. ``$ make -j8`` runs make using 8 threads. + along with the number of threads to use. For example:: -The python helper script accepts other arguments that allow you to specify + $ make -j 8 + + runs make using 8 threads. + +The Python helper script accepts other arguments that allow you to specify explicitly the build and install paths and build type. Following CMake -conventions, we support three build types: 'Release', 'RelWithDebInfo', and -'Debug'. To see the script options, run the script without any arguments; -i.e.,:: +conventions, we support three build types: ``Release``, ``RelWithDebInfo``, and +``Debug``. To see the script options, run the script without any arguments:: $ ./config-build.py -You can also pass extra CMake configuration variables to the script; e.g.,:: +You can also pass extra CMake configuration variables to the script. For +example:: $ ./config-build.py -hc path/to/host-config/file/ \ -DBUILD_SHARED_LIBS=ON \ @@ -269,7 +276,7 @@ for the generated configuration. Run CMake directly ~~~~~~~~~~~~~~~~~~ -You can also configure the code by running CMake directly and passing it the +You can also configure Axom by running CMake directly and passing it the appropriate arguments. For example, to configure, build and install a release build with the gcc compiler, you could pass a host-config file to CMake:: @@ -304,7 +311,7 @@ CMake Configuration Options The tables in this section summarize the main build system options in Axom. -Axom Components, Tests, Examples, etc. +Axom components, tests, examples, etc. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------+---------+----------------------------------------+ @@ -312,7 +319,7 @@ Axom Components, Tests, Examples, etc. +==============================+=========+========================================+ | AXOM_ENABLE_ALL_COMPONENTS | ON | Enable all components by default | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_ | ON | Enables the axom component named 'Foo' | +| AXOM_ENABLE_ | ON | Enable the axom component named 'Foo' | | | | | | | | (e.g. AXOM_ENABLE_SIDRE) | | | | for the Sidre component | @@ -334,17 +341,17 @@ See `Axom software documentation <../../../index.html>`_ for a list of Axom's components and their dependencies. See :ref:`dependencies-label` for configuration variables to specify paths -to Axom's dependencies. +to Axom external dependencies. .. note:: ``AXOM_ENABLE_EXAMPLES``, ``AXOM_ENABLE_TESTS``, and ``AXOM_ENABLE_DOCS`` are *CMake-dependent options*. Thus, if a non-Axom prefix variable form is ON, such as ``ENABLE_TESTS``, tests can be enabled in other packages in - integrated build and turned off in Axom by setting the Axom prefix form, + a project build and turned off in Axom by setting the Axom prefix form ``AXOM_ENABLE_TESTS`` to OFF. -Axom Build Option, Compiler Support, and Parallelism -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Axom build options, compiler support, and parallelism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------+---------+----------------------------------------+ | OPTION | Default | Description | @@ -377,16 +384,16 @@ Axom Build Option, Compiler Support, and Parallelism +------------------------------+---------+----------------------------------------+ Note that, in most Axom components, node-level parallelism features, enabled with -OpenMP, CUDA (NVIDIA GPUs), and HIP (AMD GPUs), are implemented using RAJA. These -features are described in :ref:`dependencies-label`. In addition, enabling such -features may require additional build options to be provided, which are summarized -in the following table. +OpenMP, CUDA (NVIDIA GPUs), and HIP (AMD GPUs), are implemented using RAJA. See +:ref:`dependencies-label` for instructions to set the directory location of a +RAJA installation. In addition, enabling such features may require additional build +options to be provided, which are summarized in the following table. +------------------------------+------------------------------------------+ | OPTION | Description | +==============================+==========================================+ | RAJA_DIR | RAJA installation directory as described | -| | in :ref:`dependencies-label`. +| | in :ref:`dependencies-label`. | | | | | | RAJA must be built with support enabled | | | for OpenMP, CUDA, or HIP to use features | @@ -405,15 +412,16 @@ in the following table. +------------------------------+------------------------------------------+ .. important:: Depending on the version of RAJA you are using, you may need to - set the C++ standard to C++14. + set the C++ standard to C++14. RAJA requires C++14 as of release + v2022.03.0. .. note :: To configure the version of the C++ standard, you can supply one of the following values for **BLT_CXX_STD**: 'c++11' or 'c++14'. Axom requires at least 'c++11', the default value. -Tools and Features Primarily for Developers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Tools and features primarily intended for developers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------+---------+----------------------------------------+ | OPTION | Default | Description | @@ -425,8 +433,8 @@ Tools and Features Primarily for Developers | AXOM_ENABLE_ANNOTATIONS | OFF | Enable source code annotations to | | | | facilitate performance evaluation | +------------------------------------------+---------+----------------------------------------+ -| AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS | OFF | Enable building an expanded set of | -| | | tests for the Axom Quest component | +| AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS | OFF | Enable an expanded set of tests for | +| | | the Axom Quest component | +------------------------------------------+---------+----------------------------------------+ @@ -435,7 +443,7 @@ Make targets Our system provides a variety of make targets to build individual Axom components, documentation, run tests, examples, etc. After running CMake -(using either the python helper script or directly), you can see a listing of +(using either the Python helper script or directly), you can see a listing of all available targets by passing 'help' to make; i.e.,:: $ make help From 2b19b8fee1535c459fab6651e7df93a676bb8d45 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Fri, 24 Jun 2022 13:09:07 -0700 Subject: [PATCH 03/10] Linked library/component enablement to conditional compilation in coding guide --- .../sphinx/coding_guide/sec10_dev_macros.rst | 18 ++++++++++++++---- .../sphinx/quickstart_guide/config_build.rst | 16 ++++++++++++---- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst index 0f64e7c26a..31f9f8ce10 100644 --- a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst +++ b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst @@ -56,6 +56,8 @@ Please see the `AXOMMacros.hpp` header file for other available macros and usage examples. +.. _codemacros-conditional-label: + ------------------------------------ Conditionally compiled code ------------------------------------ @@ -76,10 +78,18 @@ for a debug build **must** be guarded using the `AXOM_DEBUG` macro:: // rest of method implementation } -The Axom build system provides various other macros for controlling -conditionally-compiled code. The macro constants will be defined based -on CMake options given when the code is configured. Please see the -`config.hpp` header file in the source include directory for a complete list. +Axom provides various other macro constants for conditionally-compiled code +based on which built-in and third-party libraries are being used and which Axom +components are enabled. The macro constants are defined in the ``config.hpp.in`` +file in the top-level Axom source directory. Each of these macro constants has +the form ``AXOM_USE_``, where ``FOO`` is the name of an Axom library +dependency or the name of an Axom component. + +When CMake is run to configure an Axom build, the macro constants are set +based on CMake options and Axom dependencies and this file is converted to +the ``config.hpp`` header file in the Axom build space. The ``config.hpp`` +header file is included in all Axom source and header files for consistent +application of the macro constants throughout the code. ------------------------------------ diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index cfe5e43103..dba1f528e0 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -44,7 +44,7 @@ test on. External Dependencies ~~~~~~~~~~~~~~~~~~~~~~ -Axom's dependencies come in two flavors: +Axom has two types of dependencies: * Libraries. These contain code that axom must link against. * Tools. These are executables that we use during code development; e.g., @@ -66,7 +66,7 @@ The following table lists: each library * Which libraries are required or optional dependencies for Axom. While most Axom libraries are not required, they are required to access all - capabilities of componements listed. + capabilities of components listed. * The CMake variable that must be set to the path of each library installation when configuring a build with the library @@ -269,7 +269,7 @@ example:: -DBUILD_SHARED_LIBS=ON \ -DENABLE_FORTRAN=OFF -This will configure CMake to build shared libraries and disable fortran +This will configure CMake to build shared libraries and disable Fortran for the generated configuration. @@ -338,7 +338,7 @@ If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable the desired components (other than 'core', which is always enabled). See `Axom software documentation <../../../index.html>`_ -for a list of Axom's components and their dependencies. +for a list of Axom components and their dependencies. See :ref:`dependencies-label` for configuration variables to specify paths to Axom external dependencies. @@ -437,6 +437,14 @@ Tools and features primarily intended for developers | | | the Axom Quest component | +------------------------------------------+---------+----------------------------------------+ +Axom source code macro constants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Axom developers, please note that Axom provides macro constants to control +conditionally-compiled code based on which built-in and third-party libraries +are being used and which Axom components are enabled. Please see +:ref:`codemacros-conditional-label` for more information. + Make targets ------------ From 6a2e251954d34425149c75bd5ba4f6c351d7c4a8 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 09:58:50 -0700 Subject: [PATCH 04/10] Changes to address reviewer comments. --- .../sphinx/coding_guide/sec10_dev_macros.rst | 10 ++-- .../sphinx/quickstart_guide/config_build.rst | 51 ++++++++++--------- 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst index 31f9f8ce10..ade49566f8 100644 --- a/src/docs/sphinx/coding_guide/sec10_dev_macros.rst +++ b/src/docs/sphinx/coding_guide/sec10_dev_macros.rst @@ -79,11 +79,11 @@ for a debug build **must** be guarded using the `AXOM_DEBUG` macro:: } Axom provides various other macro constants for conditionally-compiled code -based on which built-in and third-party libraries are being used and which Axom -components are enabled. The macro constants are defined in the ``config.hpp.in`` -file in the top-level Axom source directory. Each of these macro constants has -the form ``AXOM_USE_``, where ``FOO`` is the name of an Axom library -dependency or the name of an Axom component. +which reflect which built-in and third-party libraries are being used and +which Axom components are enabled. The macro constants are defined in the +``config.hpp.in`` file in the top-level Axom source directory. Each of these +macro constants has the form ``AXOM_USE_``, where ``FOO`` is the name of +an Axom library dependency or the name of an Axom component. When CMake is run to configure an Axom build, the macro constants are set based on CMake options and Axom dependencies and this file is converted to diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index dba1f528e0..fab4788b69 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -25,10 +25,9 @@ Requirements, Dependencies, and Supported Compilers Basic requirements: ~~~~~~~~~~~~~~~~~~~ - * C++ Compiler with C++11 support at a minimum. Depending on which Axom - features you enable, a C++14 compliant compiler may be required. - * CMake. Minimum version required is 3.8.2. If using CUDA, 3.9 is the minimum - required version. + * C++ compiler with C++14 support at a minimum + * CMake with a minimum required version of 3.14 for CPU-only and CUDA builds, + and a minimum version of 3.21 when building with HIP support. * Fortran Compiler (optional) Supported Compilers @@ -46,9 +45,9 @@ External Dependencies Axom has two types of dependencies: -* Libraries. These contain code that axom must link against. -* Tools. These are executables that we use during code development; e.g., -generate documentation, format code, etc. +* **Libraries.** These contain code that axom must link against. +* **Tools.** These are executables that we use during code development; e.g., + generate documentation, format code, etc. Unless noted otherwise in the following discussion, Axom dependencies are optional. @@ -74,10 +73,10 @@ The following table lists: Library Dependent Components Build system variable ================== ==================================== ====================== `Conduit`_ Required: Sidre CONDUIT_DIR - `c2c`_ Optional C2C_DIR + `c2c`_ Optional: Quest C2C_DIR `HDF5`_ Optional: Sidre HDF5_DIR `Lua`_ Optional: Inlet LUA_DIR - `MFEM`_ Optional: Quest MFEM_DIR + `MFEM`_ Optional: Quest, Sidre MFEM_DIR `RAJA`_ Optional: Mint, Spin, Quest RAJA_DIR `SCR`_ Optional: Sidre SCR_DIR `Umpire`_ Optional: Core, Spin, Quest UMPIRE_DIR @@ -133,10 +132,6 @@ Each tool has a corresponding build system variable (with the suffix ``_EXECUTABLE``) to supply a path to the tool executable. For example, ``sphinx`` has a corresponding build system variable ``SPHINX_EXECUTABLE``. -.. note:: To get a full list of all Axom dependencies in an ``uberenv`` - build of our TPLs, please go to the TPL root directory and - run the following Spack command ``./spack/bin/spack spec axom``. - .. _tplbuild-label: @@ -145,15 +140,14 @@ Building and Installing Third-party Libraries --------------------------------------------- We use the `Spack Package Manager `_ -to manage and build TPL dependencies for Axom. The Spack process works on -Linux and macOS systems. Although we test Axom on Windows and some Axom users -build their applications for Windows, Axom does not currently have a tool to -automatically build dependencies for Windows systems. +to manage and build TPL dependencies for Axom on Linux and MacOS systems. +Similarly, support for managing and building TPLs on Windows is provided +through `Vcpkg `_. To make the TPL management process easier and automatic (you don't really need -to learn much about Spack), we drive it with a Python script called +to learn much about Spack or Vcpkg), we drive it with a Python script called ``uberenv.py``, which is located in the ``scripts/uberenv`` directory. -Running this script does several things: +Running this script on Linux or MacOS does several things: * It clones the Spack repo from GitHub and checks out a specific version that we have tested. @@ -182,6 +176,12 @@ in the Python scripts we use to build TPLs for Axom development on LC platforms at LLNL. These scripts are located in the directory ``scripts/llnl_scripts``. +.. note:: To get a full list of all Axom dependencies in an ``uberenv`` + ``spack`` build of our TPLs, please go to the TPL root directory + and run the following Spack command: ``./spack/bin/spack spec axom``. + The analogous command for an ``uberenv`` ``vcpkg`` build is: + ``.\vcpkg depend-info axom``. + .. _building-axom-label: @@ -333,15 +333,18 @@ Axom components, tests, examples, etc. | AXOM_ENABLE_DOCS | ON | Enable Axom documentation to be built | | | | as a make target | +------------------------------+---------+----------------------------------------+ +| AXOM_ENABLE_TOOLS | ON | Enable Axom development tools | ++------------------------------+---------+----------------------------------------+ If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable the desired components (other than 'core', which is always enabled). See `Axom software documentation <../../../index.html>`_ -for a list of Axom components and their dependencies. - -See :ref:`dependencies-label` for configuration variables to specify paths -to Axom external dependencies. +for a list of Axom components and their dependencies. Note that when enabling +an external dependency for an Axom component, the CMake variable ``BAR_DIR`` +must be set to a valid path to the dependency installation. See +:ref:`dependencies-label` for a complete listing of configuration variables +to specify paths to Axom external dependencies. .. note:: ``AXOM_ENABLE_EXAMPLES``, ``AXOM_ENABLE_TESTS``, and ``AXOM_ENABLE_DOCS`` are *CMake-dependent options*. Thus, if a non-Axom prefix variable form @@ -426,8 +429,6 @@ Tools and features primarily intended for developers +------------------------------------------+---------+----------------------------------------+ | OPTION | Default | Description | +==========================================+=========+========================================+ -| AXOM_ENABLE_TOOLS | ON | Enable Axom development tools | -+------------------------------------------+---------+----------------------------------------+ | ENABLE_CODECOV | ON | Enable code coverage via gcov | +------------------------------------------+---------+----------------------------------------+ | AXOM_ENABLE_ANNOTATIONS | OFF | Enable source code annotations to | From 531b310d30ca5ec69f5635e49cad89f4c6cbc5c4 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 10:00:07 -0700 Subject: [PATCH 05/10] Update min cmake versions --- src/CMakeLists.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 8ac08f9fd2..47205e0f62 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -6,10 +6,10 @@ # Axom project #------------------------------------------------------------------------------ -if (ENABLE_CUDA) - cmake_minimum_required(VERSION 3.9) +if (ENABLE_HIP) + cmake_minimum_required(VERSION 3.21) else() - cmake_minimum_required(VERSION 3.8.2) + cmake_minimum_required(VERSION 3.14) endif() project(axom LANGUAGES C CXX) From 2c06a00d003492311a0c08fc8b733024caf20fde Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 10:02:57 -0700 Subject: [PATCH 06/10] Remove extraneous commas --- src/docs/sphinx/quickstart_guide/config_build.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index fab4788b69..02633a97af 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -46,7 +46,7 @@ External Dependencies Axom has two types of dependencies: * **Libraries.** These contain code that axom must link against. -* **Tools.** These are executables that we use during code development; e.g., +* **Tools.** These are executables that we use during code development; e.g. generate documentation, format code, etc. Unless noted otherwise in the following discussion, Axom dependencies are @@ -405,7 +405,7 @@ options to be provided, which are summarized in the following table. +------------------------------+------------------------------------------+ | CUDA_TOOLKIT_ROOT_DIR | Path to CUDA software stack installation | +------------------------------+------------------------------------------+ -| CMAKE_CUDA_COMPILER | Path to CUDA compiler (e.g., nvcc) | +| CMAKE_CUDA_COMPILER | Path to CUDA compiler (e.g. nvcc) | +------------------------------+------------------------------------------+ | CMAKE_CUDA_ARCHITECTURES | Target architecture(s) for CUDA | +------------------------------+------------------------------------------+ From bb9b5a81ac31a11a1d7f5de5fd7620d9c3f91d39 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 12:23:00 -0700 Subject: [PATCH 07/10] Address more review comments. --- .../sphinx/quickstart_guide/config_build.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index 02633a97af..1c5a496fa7 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -27,7 +27,7 @@ Basic requirements: * C++ compiler with C++14 support at a minimum * CMake with a minimum required version of 3.14 for CPU-only and CUDA builds, - and a minimum version of 3.21 when building with HIP support. + and a minimum version of 3.21 when building with HIP support * Fortran Compiler (optional) Supported Compilers @@ -346,11 +346,12 @@ must be set to a valid path to the dependency installation. See :ref:`dependencies-label` for a complete listing of configuration variables to specify paths to Axom external dependencies. -.. note:: ``AXOM_ENABLE_EXAMPLES``, ``AXOM_ENABLE_TESTS``, and ``AXOM_ENABLE_DOCS`` - are *CMake-dependent options*. Thus, if a non-Axom prefix variable form - is ON, such as ``ENABLE_TESTS``, tests can be enabled in other packages in - a project build and turned off in Axom by setting the Axom prefix form - ``AXOM_ENABLE_TESTS`` to OFF. +.. note:: ``AXOM_ENABLE_EXAMPLES``, ``AXOM_ENABLE_TESTS``, and + ``AXOM_ENABLE_DOCS`` are *CMake-dependent options*. Thus, if a + variable without the ``AXOM_`` prefix is ON, such as ``ENABLE_TESTS``, + tests can be enabled in other packages in a project build and turned + off in Axom by setting the Axom prefix form ``AXOM_ENABLE_TESTS`` to + OFF. Axom build options, compiler support, and parallelism @@ -414,13 +415,9 @@ options to be provided, which are summarized in the following table. | CMAKE_HIP_ARCHITECTURES | Target architecture(s) for HIP | +------------------------------+------------------------------------------+ -.. important:: Depending on the version of RAJA you are using, you may need to - set the C++ standard to C++14. RAJA requires C++14 as of release - v2022.03.0. - .. note :: To configure the version of the C++ standard, you can supply one of the following values for **BLT_CXX_STD**: 'c++11' or 'c++14'. - Axom requires at least 'c++11', the default value. + Axom requires at least 'c++14', the default value. Tools and features primarily intended for developers From 4cbca5753a7da13a21cfe45056cbf0c87083190b Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 13:44:01 -0700 Subject: [PATCH 08/10] replace with more robust git command in cmake message --- src/CMakeLists.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 47205e0f62..2b6034778b 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -33,9 +33,8 @@ else() if (NOT EXISTS ${BLT_SOURCE_DIR}/SetupBLT.cmake) message(FATAL_ERROR "Cannot locate BLT. " - "Either run the following two commands in your git repository: \n" - " git submodule init\n" - " git submodule update\n" + "Either run the following command in your git repository: \n" + " git submodule update --init --recursive\n" "Or add -DBLT_SOURCE_DIR=/path/to/blt to your CMake command." ) endif() endif() From ea6981f3436a2e9a7b7cde628bb1bf29b3bc1e50 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Mon, 27 Jun 2022 15:18:36 -0700 Subject: [PATCH 09/10] clarified variable usage to enable/disable Axom components. --- src/docs/sphinx/quickstart_guide/config_build.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index 1c5a496fa7..56ad4a26ef 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -322,7 +322,10 @@ Axom components, tests, examples, etc. | AXOM_ENABLE_ | ON | Enable the axom component named 'Foo' | | | | | | | | (e.g. AXOM_ENABLE_SIDRE) | -| | | for the Sidre component | +| | | for the Sidre component. | +| | | | +| | | Overrides AXOM_ENABLE_ALL_COMPONENTS | +| | | for the specified component. | +------------------------------+---------+----------------------------------------+ | AXOM_ENABLE_EXAMPLES | ON | Build Axom examples | +------------------------------+---------+----------------------------------------+ @@ -336,8 +339,10 @@ Axom components, tests, examples, etc. | AXOM_ENABLE_TOOLS | ON | Enable Axom development tools | +------------------------------+---------+----------------------------------------+ -If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable the desired -components (other than 'core', which is always enabled). +If ``AXOM_ENABLE_ALL_COMPONENTS`` is OFF, you must explicitly enable a desired +component (other than 'core', which is always enabled). Similarly, if +``AXOM_ENABLE_ALL_COMPONENTS`` is ON, you can disable individual components by +setting ``AXOM_ENABLE_`` to OFF for the component you want turned off. See `Axom software documentation <../../../index.html>`_ for a list of Axom components and their dependencies. Note that when enabling From 9d6126dc4f5adca3d90729c0a3d92918b33c2ad9 Mon Sep 17 00:00:00 2001 From: Rich Hornung Date: Tue, 28 Jun 2022 08:59:30 -0700 Subject: [PATCH 10/10] More changes based on reviewer feedback --- src/docs/sphinx/quickstart_guide/config_build.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/docs/sphinx/quickstart_guide/config_build.rst b/src/docs/sphinx/quickstart_guide/config_build.rst index 56ad4a26ef..2a236a0a34 100644 --- a/src/docs/sphinx/quickstart_guide/config_build.rst +++ b/src/docs/sphinx/quickstart_guide/config_build.rst @@ -45,7 +45,7 @@ External Dependencies Axom has two types of dependencies: -* **Libraries.** These contain code that axom must link against. +* **Libraries.** These contain code that Axom must link against. * **Tools.** These are executables that we use during code development; e.g. generate documentation, format code, etc. @@ -72,7 +72,7 @@ The following table lists: ================== ==================================== ====================== Library Dependent Components Build system variable ================== ==================================== ====================== - `Conduit`_ Required: Sidre CONDUIT_DIR + `Conduit`_ Required: Inlet, Sidre CONDUIT_DIR `c2c`_ Optional: Quest C2C_DIR `HDF5`_ Optional: Sidre HDF5_DIR `Lua`_ Optional: Inlet LUA_DIR @@ -265,7 +265,7 @@ conventions, we support three build types: ``Release``, ``RelWithDebInfo``, and You can also pass extra CMake configuration variables to the script. For example:: - $ ./config-build.py -hc path/to/host-config/file/ \ + $ ./config-build.py -hc path/to/host-config/ \ -DBUILD_SHARED_LIBS=ON \ -DENABLE_FORTRAN=OFF @@ -319,7 +319,7 @@ Axom components, tests, examples, etc. +==============================+=========+========================================+ | AXOM_ENABLE_ALL_COMPONENTS | ON | Enable all components by default | +------------------------------+---------+----------------------------------------+ -| AXOM_ENABLE_ | ON | Enable the axom component named 'Foo' | +| AXOM_ENABLE_ | ON | Enable the Axom component named 'Foo' | | | | | | | | (e.g. AXOM_ENABLE_SIDRE) | | | | for the Sidre component. | @@ -331,7 +331,7 @@ Axom components, tests, examples, etc. +------------------------------+---------+----------------------------------------+ | AXOM_ENABLE_TESTS | ON | Build Axom unit tests | +------------------------------+---------+----------------------------------------+ -| ENABLE_BENCHMARKS | OFF | Enable Google benchmark | +| ENABLE_BENCHMARKS | OFF | Build Axom benchmarks | +------------------------------+---------+----------------------------------------+ | AXOM_ENABLE_DOCS | ON | Enable Axom documentation to be built | | | | as a make target |