Merge pull request #661 from LLNL/task/white238/fix_rtd

Fix RTD

.readthedocs.yml

@@ -5,7 +5,21 @@
 # Required
 version: 2
 
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+    - ghostscript
+    - graphviz
+    - texlive-full
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
   install:
     - requirements: docs/requirements.txt
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py

docs/api/target.rst

@@ -531,7 +531,7 @@ Internal variable names are prefixed with ``_`` to avoid collision with input pa
 .. _blt_export_tpl_targets:
 
 blt_export_tpl_targets
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: cmake
 
@@ -563,7 +563,7 @@ targets, without the downstream project itself requiring the use of BLT.
 .. blt_install_tpl_setups:
 
 blt_install_tpl_setups
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: cmake
 

docs/api/utility.rst

@@ -9,7 +9,7 @@ Utility Macros
 .. _blt_assert_exists:
 
 blt_assert_exists
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 
 .. code-block:: cmake
 
@@ -218,7 +218,7 @@ command but doesn't throw an error if the list is empty or not defined.
 .. _blt_convert_to_system_includes:
 
 blt_convert_to_system_includes
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: cmake
 

docs/conf.py

@@ -31,7 +31,8 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.imgmath']
+              'sphinx.ext.imgmath',
+              'sphinxcontrib.jquery']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -47,7 +48,7 @@
 
 # General information about the project.
 project = u'BLT: Build, Link, and Test'
-copyright = u'2017-2022, BLT Development Team'
+copyright = u'2017-2023, BLT Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -128,8 +129,13 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static/blt_style.css']
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'blt_style.css',
+]
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'

docs/requirements.txt

@@ -1 +1,3 @@
-docutils<0.18
+docutils
+sphinx==6.2.1
+sphinx-rtd-theme==1.2.2

docs/tutorial/common_hpc_dependencies.rst

@@ -40,7 +40,7 @@ which uses MPI to parallelize the calculation over the integration intervals.
 To enable MPI, we set ``ENABLE_MPI``, ``MPI_C_COMPILER``, and ``MPI_CXX_COMPILER``
 in our host config file. Here is a snippet with these settings for LLNL's Lassen Cluster:
 
-.. literalinclude:: ../../host-configs/llnl/toss_3_x86_64_ib/gcc@8.3.1.cmake
+.. literalinclude:: ../../host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1.cmake
    :start-after: _blt_tutorial_mpi_config_start
    :end-before:  _blt_tutorial_mpi_config_end
    :language: cmake
@@ -103,7 +103,7 @@ for you and enable the CUDA language.
 
 Here is a snippet with these settings for LLNL's Lassen Cluster:
 
-.. literalinclude:: ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@upstream_nvcc_c++17.cmake
+.. literalinclude:: ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@10.0.1_nvcc_c++17.cmake
    :start-after: _blt_tutorial_cuda_config_start
    :end-before:  _blt_tutorial_cuda_config_end
    :language: cmake
@@ -124,7 +124,7 @@ compile each source file with ``nvcc``.
 
 Some other useful CUDA flags are:
 
-.. literalinclude:: ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@upstream_nvcc_xlf.cmake
+.. literalinclude:: ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@10.0.1_nvcc_c++14_xlf.cmake
    :start-after: _blt_tutorial_useful_cuda_flags_start
    :end-before:  _blt_tutorial_useful_cuda_flags_end
    :language: cmake
@@ -144,17 +144,6 @@ Here is an example of how to add an OpenMP enabled executable:
    :end-before:  _blt_tutorial_openmp_executable_end
    :language: cmake
 
-.. note::
-  While we have tried to ensure that BLT chooses the correct compile and link flags for
-  OpenMP, there are several niche cases where the default options are insufficient.
-  For example, linking with NVCC requires to link in the OpenMP libraries directly instead
-  of relying on the compile and link flags returned by CMake's FindOpenMP package.  An
-  example of this is in ``host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@upstream_link_with_nvcc.cmake``. 
-  We provide two variables to override BLT's OpenMP flag logic: 
-
-  * ``BLT_OPENMP_COMPILE_FLAGS``
-  * ``BLT_OPENMP_LINK_FLAGS``
-
 Here is an example of how to add an OpenMP enabled test that sets the amount of threads used:
 
 .. literalinclude:: ../../tests/smoke/CMakeLists.txt

docs/tutorial/host_configs.rst

@@ -31,11 +31,11 @@ These files use standard CMake commands. CMake ``set()`` commands need to specif
     set(CMAKE_VARIABLE_NAME {VALUE} CACHE PATH "")
 
 Here is a snippet from a host-config file that specifies compiler details for
-using specific gcc (version 4.9.3 in this case) on the LLNL Pascal cluster. 
+using specific gcc (version 10.3.1 in this case) on the LLNL Pascal cluster: 
 
-.. literalinclude:: ../../host-configs/llnl/toss_3_x86_64_ib/gcc@4.9.3_nvcc.cmake
-   :start-after: _blt_tutorial_compiler_config_start
-   :end-before:  _blt_tutorial_compiler_config_end
+.. literalinclude:: ../../host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1_nvcc.cmake
+   :start-after: _blt_pascal_compiler_config_start
+   :end-before:  _blt_pascal_compiler_config_end
    :language: cmake
 
 
@@ -52,7 +52,7 @@ MPI and CUDA enabled on Pascal:
     mkdir build
     cd build
     # configure using host-config
-    cmake -C ../../host-configs/llnl/toss_3_x86_64_ib/gcc@4.9.3_nvcc.cmake  ..
+    cmake -C ../../host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1_nvcc.cmake  ..
 
 After building (``make``), you can run ``make test`` on a batch node (where the GPUs reside) 
 to run the unit tests that are using MPI and CUDA:
@@ -90,16 +90,16 @@ to run the unit tests that are using MPI and CUDA:
 Building and Testing on Ray
 ---------------------------
 
-Here is how you can use the host-config file to configure a build of the ``calc_pi``  project with MPI and CUDA 
-enabled on the LLNL BlueOS Ray cluster:
+Here is how you can use the host-config file to configure a build of the
+``calc_pi``  project with MPI and CUDA enabled on the LLNL BlueOS Lassen cluster:
 
 .. code-block:: bash
     
     # create build dir
     mkdir build
     cd build
     # configure using host-config
-    cmake -C ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@upstream_nvcc_xlf.cmake  ..
+    cmake -C ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@10.0.1_nvcc_c++17.cmake  ..
 
 And here is how to build and test the code on Ray:
 
@@ -134,8 +134,8 @@ And here is how to build and test the code on Ray:
 Building and Testing on Summit
 -------------------------------
 
-Here is how you can use the host-config file to configure a build of the ``calc_pi``  project with MPI and CUDA 
-enabled on the OLCF Summit cluster:
+Here is how you can use the host-config file to configure a build of the
+``calc_pi``  project with MPI and CUDA enabled on the OLCF Summit cluster:
 
 .. code-block:: bash
     
@@ -198,20 +198,20 @@ Basic TOSS3 (for example: Quartz) host-config that has C, C++, and Fortran Compi
 
         ``gcc@8.3.1 host-config``
 
-    .. literalinclude::  ../../host-configs/llnl/toss_3_x86_64_ib/gcc@8.3.1.cmake
+    .. literalinclude::  ../../host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1.cmake
         :language: cmake
         :linenos:
 
-Here are the full example host-config files for LLNL's Pascal, Ray, and Quartz Clusters that uses
-the default compilers on the system:
+Here are the full example host-config files for LLNL's Pascal, Lassen, 
+and Quartz Clusters that uses the default compilers on the system:
 
 .. container:: toggle
 
     .. container:: label
 
-        ``gcc@4.9.3 host-config``
+        ``gcc@10.3.1 host-config``
 
-    .. literalinclude::  ../../host-configs/llnl/toss_3_x86_64_ib/gcc@4.9.3_nvcc.cmake
+    .. literalinclude::  ../../host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1_nvcc.cmake
         :language: cmake
         :linenos:
 
@@ -223,7 +223,7 @@ More complicated BlueOS host-config that has C, C++, MPI, and CUDA support:
 
         ``clang@upstream C++17 host-config``
 
-    .. literalinclude::  ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@upstream_nvcc_c++17_no_separable.cmake
+    .. literalinclude::  ../../host-configs/llnl/blueos_3_ppc64le_ib_p9/clang@10.0.1_nvcc_c++17_no_separable.cmake
         :language: cmake
         :linenos:
 

host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1.cmake

@@ -16,24 +16,23 @@
 # gcc@10.3.1 compilers
 #------------------------------------------------------------------------------
 
+# _blt_tutorial_compiler_config_start
 set(GCC_VERSION "gcc-10.3.1")
 set(GCC_HOME "/usr/tce/packages/gcc/${GCC_VERSION}")
 
-# c compiler
 set(CMAKE_C_COMPILER "${GCC_HOME}/bin/gcc" CACHE PATH "")
 
-# cpp compiler
 set(CMAKE_CXX_COMPILER "${GCC_HOME}/bin/g++" CACHE PATH "")
 
-# fortran support
+# Fortran support
 set(ENABLE_FORTRAN ON CACHE BOOL "")
-
-# fortran compiler
 set(CMAKE_Fortran_COMPILER "${GCC_HOME}/bin/gfortran" CACHE PATH "")
+#_blt_tutorial_compiler_config_end
 
 #------------------------------------------------------------------------------
 # MPI Support
 #------------------------------------------------------------------------------
+# _blt_tutorial_mpi_config_start
 set(ENABLE_MPI ON CACHE BOOL "")
 
 set(MPI_HOME             "/usr/tce/packages/mvapich2/mvapich2-2.3.6-${GCC_VERSION}" CACHE PATH "")
@@ -44,3 +43,4 @@ set(MPI_Fortran_COMPILER "${MPI_HOME}/bin/mpif90" CACHE PATH "")
 
 set(MPIEXEC              "/usr/bin/srun" CACHE PATH "")
 set(MPIEXEC_NUMPROC_FLAG "-n" CACHE PATH "")
+# _blt_tutorial_mpi_config_end

host-configs/llnl/toss_4_x86_64_ib/gcc@10.3.1_nvcc.cmake

@@ -0,0 +1,57 @@
+# Copyright (c) 2017-2023, Lawrence Livermore National Security, LLC and
+# other BLT Project Developers. See the top-level LICENSE file for details
+# 
+# SPDX-License-Identifier: (BSD-3-Clause)
+
+#------------------------------------------------------------------------------
+# Example host-config file for a cluster on a toss4 platform (e.g. quartz) at LLNL
+#------------------------------------------------------------------------------
+#
+# This file provides CMake with paths / details for:
+#  C,C++, & Fortran compilers + MPI
+# 
+#------------------------------------------------------------------------------
+
+#------------------------------------------------------------------------------
+# gcc@10.3.1 compilers
+#------------------------------------------------------------------------------
+
+# _blt_pascal_compiler_config_start
+set(GCC_VERSION "gcc-10.3.1")
+set(GCC_HOME "/usr/tce/packages/gcc/${GCC_VERSION}")
+
+set(CMAKE_C_COMPILER "${GCC_HOME}/bin/gcc" CACHE PATH "")
+set(CMAKE_CXX_COMPILER "${GCC_HOME}/bin/g++" CACHE PATH "")
+
+# Fortran support
+set(ENABLE_FORTRAN ON CACHE BOOL "")
+set(CMAKE_Fortran_COMPILER "${GCC_HOME}/bin/gfortran" CACHE PATH "")
+# _blt_pascal_compiler_config_end
+
+#------------------------------------------------------------------------------
+# MPI Support
+#------------------------------------------------------------------------------
+set(ENABLE_MPI ON CACHE BOOL "")
+
+set(MPI_HOME             "/usr/tce/packages/mvapich2/mvapich2-2.3.6-${GCC_VERSION}" CACHE PATH "")
+
+set(MPI_C_COMPILER       "${MPI_HOME}/bin/mpicc" CACHE PATH "")
+set(MPI_CXX_COMPILER     "${MPI_HOME}/bin/mpicxx" CACHE PATH "")
+set(MPI_Fortran_COMPILER "${MPI_HOME}/bin/mpif90" CACHE PATH "")
+
+set(MPIEXEC              "/usr/bin/srun" CACHE PATH "")
+set(MPIEXEC_NUMPROC_FLAG "-n" CACHE PATH "")
+
+#------------------------------------------------------------------------------
+# CUDA support
+#------------------------------------------------------------------------------
+set(ENABLE_CUDA ON CACHE BOOL "")
+
+set(CUDA_TOOLKIT_ROOT_DIR "/usr/tce/packages/cuda/cuda-12.2.2" CACHE PATH "")
+set(CMAKE_CUDA_COMPILER "${CUDA_TOOLKIT_ROOT_DIR}/bin/nvcc" CACHE PATH "")
+set(CMAKE_CUDA_HOST_COMPILER "${CMAKE_CXX_COMPILER}" CACHE PATH "")
+
+set(CMAKE_CUDA_ARCHITECTURES "70" CACHE STRING "")
+set(CMAKE_CUDA_FLAGS "-restrict --expt-extended-lambda -G" CACHE STRING "")
+
+set(CUDA_SEPARABLE_COMPILATION ON CACHE BOOL "" )

host-configs/llnl/toss_4_x86_64_ib_cray/cce@13.0.1_clang_hip.cmake

@@ -14,20 +14,17 @@
 #------------------------------------------------------------------------------
 # HPE Cray cce@13.0.1 compilers
 #------------------------------------------------------------------------------
-# _blt_tutorial_compiler_config_start
 set(CCE_HOME "/usr/tce/packages/cce-tce/cce-13.0.1")
 set(CMAKE_C_COMPILER   "${CCE_HOME}/bin/craycc" CACHE PATH "")
 set(CMAKE_CXX_COMPILER "${CCE_HOME}/bin/crayCC" CACHE PATH "")
 
 # Fortran support
 set(ENABLE_FORTRAN ON CACHE BOOL "")
 set(CMAKE_Fortran_COMPILER "${CCE_HOME}/bin/crayftn" CACHE PATH "")
-# _blt_tutorial_compiler_config_end
 
 #------------------------------------------------------------------------------
 # MPI Support
 #------------------------------------------------------------------------------
-# _blt_tutorial_mpi_config_start
 set(ENABLE_MPI ON CACHE BOOL "")
 
 set(MPI_HOME "/usr/tce/packages/cray-mpich-tce/cray-mpich-8.1.13-cce-13.0.1/")
@@ -36,19 +33,14 @@ set(MPI_C_COMPILER "${MPI_HOME}/bin/mpicc" CACHE PATH "")
 set(MPI_CXX_COMPILER "${MPI_HOME}/bin/mpicxx" CACHE PATH "")
 
 set(MPI_Fortran_COMPILER "${MPI_HOME}/bin/mpif90" CACHE PATH "")
-# _blt_tutorial_mpi_config_end
 
 #------------------------------------------------------------------------------
 # HIP support
 #------------------------------------------------------------------------------
-# _blt_tutorial_hip_config_start
 set(ENABLE_HIP ON CACHE BOOL "")
 
 set(ROCM_PATH "/opt/rocm-4.5.2/" CACHE PATH "")
 set(CMAKE_HIP_ARCHITECTURES "gfx908" CACHE STRING "gfx architecture to use when generating HIP/ROCm code")
 
 # Recommended link line when not using tce-wrapped compilers
 # set(CMAKE_EXE_LINKER_FLAGS "-Wl,--disable-new-dtags -L/opt/rocm-4.5.2/hip/lib -L/opt/rocm-4.5.2/lib -L/opt/rocm-4.5.2/lib64 -Wl,-rpath,/opt/rocm-4.5.2/hip/lib:/opt/rocm-4.5.2/lib:/opt/rocm-4.5.2/lib64 -lamdhip64 -lhsakmt -lhsa-runtime64 -lamd_comgr" CACHE STRING "")
-
-# _blt_tutorial_hip_config_end
-