diff --git a/.gitmodules b/.gitmodules index 303cc47eb..fa7bd2819 100644 --- a/.gitmodules +++ b/.gitmodules @@ -2,10 +2,6 @@ path = spack url = https://github.com/jcsda/spack branch = release/2.0 -[submodule "doc/CMakeModules"] - path = doc/CMakeModules - url = https://github.com/noaa-emc/cmakemodules - branch = v1.3.0 [submodule "repos/builtin"] path = repos/builtin url = https://github.com/jcsda/spack-packages diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt deleted file mode 100644 index b738eb9c1..000000000 --- a/doc/CMakeLists.txt +++ /dev/null @@ -1,30 +0,0 @@ -cmake_minimum_required(VERSION 3.18 FATAL_ERROR) - -project(spack-stack VERSION 2.0.0) - -list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/CMakeModules/Modules") - -find_package(Sphinx REQUIRED) - -# configured documentation tools and intermediate build results -set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build") - -# Sphinx cache with pickled ReST documents -set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees") - -# HTML output directory -set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html") - -configure_file( - "${CMAKE_CURRENT_SOURCE_DIR}/source/conf.py" - "${BINARY_BUILD_DIR}/conf.py" - @ONLY) - -add_custom_target(spack-stack-doc-html ALL - ${SPHINX_EXECUTABLE} - -q -b html - -c "${BINARY_BUILD_DIR}" - -d "${SPHINX_CACHE_DIR}" - "${CMAKE_CURRENT_SOURCE_DIR}/source" - "${SPHINX_HTML_DIR}" - COMMENT "Building HTML documentation with Sphinx") diff --git a/doc/CMakeModules b/doc/CMakeModules deleted file mode 160000 index 607d9b463..000000000 --- a/doc/CMakeModules +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 607d9b4633395b4be88d87a1df88b46302d48d0c diff --git a/doc/modulefile_templates/gcc b/doc/modulefile_templates/gcc deleted file mode 100644 index f6c0f5afd..000000000 --- a/doc/modulefile_templates/gcc +++ /dev/null @@ -1,23 +0,0 @@ -#%Module1.0 - -module-whatis "Provides a gcc-10.1.0 installation for use with spack." - -conflict gnu -conflict gcc - -proc ModulesHelp { } { -puts stderr "Provides a gcc-10.1.0 installation for use with spack." -} - - -# Set this value -set GCC_PATH "/glade/work/epicufsrt/contrib/spack-stack/casper/gcc-10.1.0" - -prepend-path PATH "${GCC_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${GCC_PATH}/lib" -prepend-path LD_LIBRARY_PATH "${GCC_PATH}/lib64" -prepend-path LIBRARY_PATH "${GCC_PATH}/lib" -prepend-path LIBRARY_PATH "${GCC_PATH}/lib64" -prepend-path CPATH "${GCC_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${GCC_PATH}" -prepend-path MANPATH "${GCC_PATH}/share/man" diff --git a/doc/modulefile_templates/git-lfs b/doc/modulefile_templates/git-lfs deleted file mode 100644 index 3b6c1e097..000000000 --- a/doc/modulefile_templates/git-lfs +++ /dev/null @@ -1,15 +0,0 @@ -#%Module1.0 - -module-whatis "Provides git-lfs-2.10.0 for use with spack." - -conflict git-lfs - -proc ModulesHelp { } { -puts stderr "Provides git-lfs-2.10.0 for use with spack." -} - -# Set this value -set GITLFS_PATH "/my/path/to/spack-stack/git-lfs-2.10.0" - -prepend-path PATH "${GITLFS_PATH}/bin" -prepend-path MANPATH "${GITLFS_PATH}/share/man" diff --git a/doc/modulefile_templates/libfabric b/doc/modulefile_templates/libfabric deleted file mode 100644 index 970294a2b..000000000 --- a/doc/modulefile_templates/libfabric +++ /dev/null @@ -1,18 +0,0 @@ -#%Module1.0 - -module-whatis "Provides a libfabric installation for use with spack." - -conflict libfabric - -proc ModulesHelp { } { -puts stderr "Provides a libfabric installation for use with spack." -} - -# Set this value -set LIBFABRIC_PATH "/opt/cray/libfabric/1.15.2.0" - -prepend-path PATH "${LIBFABRIC_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${LIBFABRIC_PATH}/lib64" -prepend-path LIBRARY_PATH "${LIBFABRIC_PATH}/lib64" -prepend-path CPATH "${LIBFABRIC_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${LIBFABRIC_PATH}" diff --git a/doc/modulefile_templates/mysql b/doc/modulefile_templates/mysql deleted file mode 100644 index 76fdb1646..000000000 --- a/doc/modulefile_templates/mysql +++ /dev/null @@ -1,19 +0,0 @@ -#%Module1.0 - -module-whatis "Provides a mysql-8.0.31 installation for use with spack." - -conflict mysql - -proc ModulesHelp { } { -puts stderr "Provides a mysql-8.0.31 installation for use with spack." -} - -# Set this value -set MYSQL_PATH "/work/noaa/da/role-da/spack-stack/mysql-8.0.31" - -prepend-path PATH "${MYSQL_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${MYSQL_PATH}/lib" -prepend-path LIBRARY_PATH "${MYSQL_PATH}/lib" -prepend-path CPATH "${MYSQL_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${MYSQL_PATH}" -setenv mysql_ROOT "${MYSQL_PATH}" \ No newline at end of file diff --git a/doc/modulefile_templates/node.js b/doc/modulefile_templates/node.js deleted file mode 100644 index 7f5fc113c..000000000 --- a/doc/modulefile_templates/node.js +++ /dev/null @@ -1,23 +0,0 @@ -#%Module1.0 - -module-whatis "Provides an node.js-20.10.0 installation for use with spack." - -# Only allow one instance of compiler to load -conflict ecflow - -proc ModulesHelp { } { -puts stderr "Provides an node.js-20.10.0 installation for use with spack." -} - -if { [ module-info mode load ] && ![ is-loaded gcc/10.3.0 ] } { - module load gcc/10.3.0 -} - -# Set this value -set NODEJS_PATH "/p/app/projects/NEPTUNE/spack-stack/node-js-20.10.0/gcc-10.3.0" - -prepend-path PATH "${NODEJS_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${NODEJS_PATH}/lib" -prepend-path LIBRARY_PATH "${NODEJS_PATH}/lib" -prepend-path CPATH "${NODEJS_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${NODEJS_PATH}" diff --git a/doc/modulefile_templates/openmpi b/doc/modulefile_templates/openmpi deleted file mode 100644 index b13398bbb..000000000 --- a/doc/modulefile_templates/openmpi +++ /dev/null @@ -1,37 +0,0 @@ -#%Module1.0 - -module-whatis "Provides an openmpi-4.1.3 installation for use with spack and gcc-10.1.0." - -conflict openmpi -conflict mpich -conflict mpi - -proc ModulesHelp { } { -puts stderr "Provides an openmpi-4.1.3 installation for use with spack and gcc-10.1.0." -} - -if { [ module-info mode load ] && ![ is-loaded comp/gcc/10.1.0 ] } { - module load comp/gcc/10.1.0 -} - -# Set this value -set OPENMPI_PATH "/discover/swdev/jcsda/spack-stack/openmpi-4.1.3/gcc-10.1.0" - -prepend-path PATH "${OPENMPI_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${OPENMPI_PATH}/lib" -prepend-path LIBRARY_PATH "${OPENMPI_PATH}/lib" -prepend-path CPATH "${OPENMPI_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${OPENMPI_PATH}" -prepend-path MANPATH "${OPENMPI_PATH}/share/man" - -# Settings specific for Discover -setenv MPIHOME ${OPENMPI_PATH} -setenv MPI_HOME ${OPENMPI_PATH} -unsetenv SLURM_EXPORT_ENV -setenv PSM2_PATH_SELECTION "static_base" -setenv SLURM_CPU_BIND "none" - -# Settings specific for Cheyenne and Hercules -setenv MPI_ROOT ${OPENMPI_PATH} -setenv UCX_MAX_RNDV_RAILS "1" -setenv OMPI_MCA_btl "^openib" diff --git a/doc/modulefile_templates/qt b/doc/modulefile_templates/qt deleted file mode 100644 index 9ba14fbc5..000000000 --- a/doc/modulefile_templates/qt +++ /dev/null @@ -1,18 +0,0 @@ -#%Module1.0 - -module-whatis "Provides a qt-5.15.2 installation for use with spack." - -conflict qt - -proc ModulesHelp { } { -puts stderr "Provides a qt-5.15.2 installation for use with spack." -} - -# Set this value -set QT_PATH "/discover/swdev/jcsda/spack-stack/qt-5.15.2/5.15.2/gcc_64" - -prepend-path PATH "${QT_PATH}/bin" -prepend-path LD_LIBRARY_PATH "${QT_PATH}/lib" -prepend-path LIBRARY_PATH "${QT_PATH}/lib" -prepend-path CPATH "${QT_PATH}/include" -prepend-path CMAKE_PREFIX_PATH "${QT_PATH}" diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index e4d7905c5..000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -urllib3<2 diff --git a/doc/source/Acronyms.rst b/doc/source/Acronyms.rst deleted file mode 100644 index 8ef55c114..000000000 --- a/doc/source/Acronyms.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _Acronyms: - -Acronyms -************************* - -.. table:: - :widths: 20 80 - - +----------------+---------------------------------------------------+ - | Abbreviation | Explanation | - +================+===================================================+ - | ESMF | The Earth System Modeling Framework | - +----------------+---------------------------------------------------+ - | FMS | Flexible Modeling System | - +----------------+---------------------------------------------------+ - | HTML | Hypertext Markup Language | - +----------------+---------------------------------------------------+ - | JEDI | Joint Effort for Data assimilation Integration | - +----------------+---------------------------------------------------+ - | JCSDA | Joint Center for Satellite Data Assimilation | - +----------------+---------------------------------------------------+ - | MPI | Message Passing Interface | - +----------------+---------------------------------------------------+ - | NOAA | National Oceanic and Atmospheric Administration | - +----------------+---------------------------------------------------+ - | OpenMP | Open Multi-Processing | - +----------------+---------------------------------------------------+ - | UCAR | University Corporation for Atmospheric Research | - +----------------+---------------------------------------------------+ - | UFS | Unified Forecast System | - +----------------+---------------------------------------------------+ diff --git a/doc/source/AddingTestPackages.rst b/doc/source/AddingTestPackages.rst deleted file mode 100644 index 991b85962..000000000 --- a/doc/source/AddingTestPackages.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _Add_Test_Packages: - -Adding test packages (chaining environments) -******************************************** - -Releases of spack-stack are deployed quarterly on supported platforms. Between releases, additional packages may be installed through the following steps, which make use of Spack's environment chaining capabilities. This allows parts of the stack to be replaced while leaving the release environment untouched. - -To install in an additional environment within an official spack-stack space, simply ``cd`` into the appropriate spack-stack root directory and run ``. setup.sh`` before continuing to the following steps. To create a chained environment in a personal space outside of an official installation, it is recommended that you use the same spack-stack release as the one from which you wish to use an upstream environment. For instance, if you are targeting an environment installed under ``spack-stack-1.4.1/``, then use ``git clone --recurse-submodules https://github.com/jcsda/spack-stack -b release/1.4.1`` to set up your installation, then in the newly created spack-stack directory run ``. setup.sh`` and proceed with the following steps. The following steps install a hypothetical new version of NetCDF C on Hera that also rebuilds all of its dependencies for the UFS Weather Model. Note that it is recommended to use one or more `meta-modules `_ (e.g., 'ufs-weather-model-env') in the spec as opposed to only providing specific packages, as using the meta-modules will ensure that all of the module files needed from the upstream environment for a given application are copied into the downstream environment by the module refresh command. Make sure to use the same compiler as the upstream environment. - -.. code-block:: bash - - spack stack create env --name netcdf-test --template empty --site hera --compiler gcc \ - --upstream /scratch1/NCEPDEV/nems/role.epic/spack-stack/spack-stack-1.4.1/envs/ue-gcc/install [--upstream /path/to/second/install] [--modify-pkg netcdf-c] - cd envs/netcdf-test - spack env activate . - spack add ufs-weather-model-env%intel ^netcdf-c@5.0.0 - spack concretize 2>&1 | tee log.concretize - spack install 2>&1 | tee log.install - spack module lmod refresh --upstream-modules - spack stack setup-meta-modules - -To use the environment, access it in the same way as a regular spack-stack installation, i.e., add the directory provided by ``spack stack setup-meta-modules`` ending with '/modulefiles/Core' to your MODULEPATH variable. This will give access to the upstream modules needed while avoiding package conflicts; do not use the upstream environment in ``$MODULEPATH`` directly. - -.. note:: - The ``--upstream`` option for the ``spack stack create env`` command adds a specified Spack/spack-stack installation path as an upstream environment in the resulting spack.yaml, and can be invoked multiple times in order to include multiple upstream environments. The command will *give a warning but not fail* if an invalid directory is provided (either because it does not end with the typical ``install`` directory name, or because it does not exist). Be mindful of these warnings, and if the path does not exist, check for typos and make sure that you are using the path for the correct system from the table in :numref:`Section %s `. - -.. note:: - The ``--modify-pkg`` option for the ``spack stack create env`` command should be used by spack-stack maintainers whenever a package recipe needs to be modified for between-release deployments (i.e., chained environments that live in an official spack-stack release), such as when a new version, variant, or patch needs to be added. This option creates a separate, custom Spack repo specific to the environment being created, and lives under that environment's directory structure (i.e., ``$SPACK_ENV/envrepo/``). It requires the name of the package to be customized, and can be invoked multiple times to customize multiple packages. Each package specified will be copied into the custom repo, and the environment's repo configuration will be automatically updated to use those custom copies. It is important to use this option in order to avoid contaminating or breaking the existing installation. - -.. note:: - More details on chaining spack environments and a few words of caution can be found in the `Spack documentation `_. Those words of caution need to be taken seriously, especially those referring to not deleting modulefiles and dependencies in the upstream spack environment (if having permissions to do so)! diff --git a/doc/source/AutomatedBuilds.rst b/doc/source/AutomatedBuilds.rst deleted file mode 100644 index c901c3ebe..000000000 --- a/doc/source/AutomatedBuilds.rst +++ /dev/null @@ -1,55 +0,0 @@ -================ -Automated builds -================ - -.. _AutomatedBuildWorkflow: - -Workflow -************************* - -The spack-stack repository now contains scripts for implementing scheduled, automated building, unit testing, and build caching of packages. These scripts live under utils/weekly_build/. They download their own copy of spack-stack (the develop branch, by default) and build one or more environments under that directory structure, which may be transient or reused. - -Script failures are detected by non-zero exit codes. - -The list of packages to be unit tested is stored in the ``$PACKAGES_TO_TEST`` variable in ShellSetup.sh. As unit testing needs are identified, this list should be updated to be as comprehensive as possible based on https://github.com/JCSDA/spack-stack/wiki/Automated-testing-and-building#unit-testing-requirements. - -.. _AutomatedBuildAddPlatform: - -Overview of implementing on a new platform -****************************************** - -Use a clean environment. Do NOT run setup.sh in the directory containing the build scripts (util/weekly_build/) to be run. Nothing in spack-stack outside of the build scripts is needed to get the automated build workflow running, as the workflow will take care of download a copy of spack-stack to be used for doing the automated builds themselves. - -------------------------------- -Platform-specific configuration -------------------------------- - -The ShellSetup.sh script points to a script in the sites/ subdirectory based on the site name as set by the third argument of each build script (stored and used as ``$PLATFORM`` throughout the scripts). Note that a number of variables and functions can be set or overridden here: - - ``$COMPILERS``: Space-delimited list of compilers to be built against on a given system. - - ``$TEMPLATES``: Space-delimited list of templates to install. Default is 'unified-env'. - - ``$PACKAGES_TO_TEST``: Space-delimited list of packages for which units tests should be run. - - ``$PACKAGES_TO_INSTALL``: Space-delimited list of packages to be installed. For many systems it can be left empty so as to install the entire Unified Environment. - - ``alert_cmd()``: This function should be set for each system. It is invoked when any step fails (non-zero exit code somewhere in the workflow), and so can be used to send emails, post to Slack or GitHub, etc. - - ``spack_wrapper()``: This function runs the Spack command, where the first argument is a log file name. It should not typically need to be redefined by platform. - - ``spack_install_wrapper()``: This function determines the means by which the ``spack`` command is invoked for the install steps, and can be overridden for each platform. If testing and installation will be performed outside of a batch scheduler, i.e., directly on a login node, then the default can probably be used. However, overriding this function allows, for instance, for job schedulers to be invoked (srun, qsub, etc.), as well as for parallel installations to be performed. Note that the first argument is a log file name, so custom versions of this function will most likely need to use ``shift`` to properly access the remaining arguments. - - ``$INSTALL_OPTS``: Additional ``spack install`` flags to be supplied to ``spack_install_wrapper()``. - - ``$TEST_``: Set this variable to ON in order to enable the corresponding test under util/weekly_build/apptests/. - - ``$BUILD_CACHE``: Name of or path to (beginning with '\file://') build cache directory. Defaults to 'local-binary' mirror defined in site's mirrors.yaml. - - ``$SOURCE_CACHE``: Name of or path to (beginning with '\file://') source cache directory. Defaults to 'local-source' mirror defined in site's mirrors.yaml. - - ``$PADDED_LENGTH``: Padded length setting for Spack build cache generation. It should be as long as possible without the build failing. - - ``$KEEP_WEEKLY_BUILD_DIR``: Set to 'YES' to use a persistent directory structure for automated builds. - - ``$DISABLE_TESTING``: Set to 'YES' to switch off build-time package testing regardless of whether ``$PACKAGES_TO_TEST`` is set. - ------------------------------- -Setting up weekly builds: cron ------------------------------- - -Prior to running, obtain a current copy of the build scripts by cloning the spack-stack repository to the platform of interest (/path/to/spack-stack-auto-build/). - -If /path/to/spack-stack is the local spack-stack root directory containing spack-stack-x.y.z installations, run ``mkdir -p /path/to/spack-stack/weekly_build/logs``. - -In crontab, add: - -.. code-block:: console - - 0 1 * * SUN /path/to/spack-stack-auto-build/util/weekly_build/SpackStackBuildCache_AllSteps.sh $(date +\%y\%m\%d) /path/to/spack-stack/weekly_build acorn > /path/to/spack-stack/weekly_build/logs/cron.$(date +\%y\%m\%d).out 2>&1 diff --git a/doc/source/BuildingContainers.rst b/doc/source/BuildingContainers.rst deleted file mode 100644 index 52da0326f..000000000 --- a/doc/source/BuildingContainers.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _BuildingContainers: - - -Creating Containers -******************** - -================= -Container recipes -================= - -Container recipes are self-contained except that at container creation time (``spack stack create ctr ...``) package information from the common ``packages.yaml`` (or a manually provided version) is added to the ``packages:`` section, and specs are added in the section ``specs`` from the specs file provided as an argument. Container recipes are defined in ``configs/containers``, and specs are defined in ``configs/containers/specs``. - -**WORK IN PROGRESS** - - ------------------------ -Container build example ------------------------ - -It is important to know that container builds do not allow for multiple versions of the same package (e.g., ``fms@2022.01`` and ``fms@release-jcsda``), which needs to be taken into account when creating the specs in ``configs/containers/specs/*.yaml``. - -.. code-block:: console - - # See a list of preconfigured containers - spack stack create ctr -h - - # Create container spack definition (spack.yaml) in directory envs/ - spack stack create ctr --container=docker-ubuntu-gcc-openmpi --specs=jedi-ci - - # Descend into container environment directory - cd envs/docker-ubuntu-gcc-openmpi - - # Docker: create Dockerfile and build container - # See section "container" in spack.yaml for additional information - spack containerize > Dockerfile - docker build -t myimage . - docker run -it myimage diff --git a/doc/source/CreatingEnvironments.rst b/doc/source/CreatingEnvironments.rst deleted file mode 100644 index fc02c289f..000000000 --- a/doc/source/CreatingEnvironments.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _CreatingEnvironment: - -Creating and installing new environments -**************************************** - -The following instructions are a simplified version of the instructions found in :numref:`Sections %s ` and :numref:`%s `, and should work for systems where spack-stack already has a site configuration, or where minimal configuration is necessary. For more detailed instructions, including how to generate new site configurations and more details of when and how to use external packages, see :numref:`Sections %s ` and :numref:`%s `. To chain a new Spack environment to an existing one, such as to test a new package version based on dependencies already installed in the upstream environment, see :numref:`%s `. - -Note that items in "<>" should be replaced with the appropriate values (site names, etc.), and items in '[]' are optional. ** and *