Merge pull request #271 from LLNL/devops/docker-envs

Devops/docker envs

Author: mdavis36

RELEASE_NOTES.md

@@ -1,7 +1,21 @@
-Version vX.Y.Z -- Release date xxxx-xx-xx
+Version vYYYY.MM.p -- Release date YYYY-MM-DD
+==============================================
+  * Important Notes:
+    * External users of the code will need to supply config files for tpl-manager to find system libraries correctly. Steps to do this are detailed in the external user build guide. 
+
+Notable changes include:
+
+  * New features/ API changes:
+
+  * Build changes / improvements:
+    * tpl-manager.py will no longer use generic x86_64 configs for non LC systems. Users will be required to supply their own configs for pointing spack at external packages.
+
+  * Bug Fixes / improvements:
+
+Version v2024.01.1 -- Release date 2024-02-17
 ==============================================
   * Important Notes:
-    * 
+    * This is a patch release for v2024.01.0.
 
 Notable changes include:
 
@@ -15,6 +29,8 @@ Notable changes include:
 
   * Bug Fixes / improvements:
     * Fixed bug with ConstantBoundary in the presence of porosity with the new porosity models introduced in v2024.01.00.
+    * Updating header lists for including Spheral modules in external projects.
+    * Adding effective viscous pressure back to FSISPH.
     * Initial volumes for damage models were incorrectly not taking into account pore space when computing failure statistics for seeding flaws.  Fixed.
 
 Version v2024.01.00 -- Release date 2024-01-19

cmake/InstallTPLs.cmake

@@ -19,6 +19,7 @@ if (NOT ENABLE_CXXONLY)
   # Find the appropriate Python
   find_package(Python3 COMPONENTS Interpreter Development)
   set(PYTHON_EXE ${Python3_EXECUTABLE})
+  set(SPHERAL_SITE_PACKAGES_PATH "lib/python${Python3_VERSION_MAJOR}.${Python3_VERSION_MINOR}/site-packages" )
   list(APPEND SPHERAL_BLT_DEPENDS Python3::Python)
 
   # Set the PYB11Generator path

cmake/SpheralVersion.cmake

@@ -1 +1 @@
-set(SPHERAL_VERSION 2024.01.0)
+set(SPHERAL_VERSION 2024.01.1)

cmake/spheral/SpheralAddLibs.cmake

@@ -233,7 +233,7 @@ function(spheral_add_pybind11_library package_name)
   target_compile_options(${MODULE_NAME} PRIVATE ${SPHERAL_PYB11_TARGET_FLAGS})
 
   install(TARGETS     ${MODULE_NAME}
-          DESTINATION Spheral
+          DESTINATION ${SPHERAL_SITE_PACKAGES_PATH}/Spheral
           )
 
   # Set the r-path of the C++ lib such that it is independent of the build dir when installed

cmake/spheral/SpheralInstallPythonFiles.cmake

@@ -7,13 +7,14 @@
 # Note, if ENABLE_CXXONLY is set, this function does nothing
 #-----------------------------------------------------------------------------------
 
+
 function(spheral_install_python_files)
 
   if (NOT ENABLE_CXXONLY)
     install(FILES ${ARGV}
-            DESTINATION Spheral)
+      DESTINATION DESTINATION ${SPHERAL_SITE_PACKAGES_PATH}/Spheral)
     install(CODE "execute_process( \
-            COMMAND ${PYTHON_EXE} -m compileall Spheral \
+    COMMAND ${PYTHON_EXE} -m compileall DESTINATION ${SPHERAL_SITE_PACKAGES_PATH}/Spheral \
             WORKING_DIRECTORY ${CMAKE_INSTALL_PREFIX})")
   endif()
 

docs/build_guide/external/index.rst

@@ -9,7 +9,7 @@ This guide is designed to help external users build and install Spheral on non L
    :caption: External Building Guide:
 
    quickstart.rst
-   ubuntu_update.rst
+   system_packages.rst
    cloning.rst
    updating.rst
    tpls.rst

docs/build_guide/external/system_packages.rst

@@ -0,0 +1,12 @@
+.. _required system packages:
+
+Required System Packages
+########################
+
+This guide assumes the use of an Ubuntu 20.04 system using ``apt`` as the package manager. For other other operating systems please install the corresponding packages as seen below.
+
+::
+
+  sudo apt update
+  sudo apt upgrade
+  sudo apt install build-essential git gfortran mpich autotools-dev autoconf sqlite pkg-config uuid gettext cmake libncurses-dev libgdbm-dev libffi-dev libssl-dev libexpat-dev libreadline-dev liblapack-dev libbz2-dev locales python python3 unzip libtool wget curl tk-dev

docs/build_guide/external/ubuntu_update.rst

@@ -12,9 +12,6 @@ Update and install necessary package dependencies.
   sudo apt upgrade
   sudo apt install build-essential git gfortran mpich autotools-dev autoconf sqlite pkg-config uuid gettext cmake libncurses-dev libgdbm-dev libffi-dev libssl-dev libexpat-dev libreadline-dev liblapack-dev libbz2-dev locales python python3 unzip libtool wget curl tk-dev
 
-.. warning::
-   For alternative Linux distros your mileage may vary, ensure you are installing compatible packages to the ones listed above.
-
 [ex_update_sys-section-end]
 
 ..
@@ -47,6 +44,12 @@ Build our TPL dependencies from source with the Spheral tpl-management tool (``t
 .. note::
   This command will generate a ``.cmake`` file with the naming convention ``<system-type>-<compiler-spec>``. The following commands will refer to this format as ``<host-config>`` for generalization across operating systems and architectures. You will need to substitute the correct format in the following commands. 
 
+.. warning::
+   For operating systems other than Ubuntu 20.04 you should get an error to the effect of:
+   ``[ERROR: invalid spack config dir: /<path>/scripts/spack/configs/<OperatingSystem><Version> ]``
+   You will **need** to follow the steps outlined in :ref:`ERROR: invalid spack config dir` before proceeding with this quickstart guide.
+
+
 [ex_tpl-section-end]
 
 [lc_tpl-section-start]

docs/build_guide/include/quickstart.rst.inc

@@ -66,6 +66,38 @@ Above we are telling ``tpl-manager`` to build our TPLs with the ``gcc`` that is
 .. note::
    Spheral minimally requires a C++14 compliant compiler.
 
+ERROR: invalid spack config dir
+===============================
+
+If you are trying to run ``tpl-manager.py`` on an operating system other than Ubuntu20.04, you will
+see an error to the effect of:
+``[ERROR: invalid spack config dir: /<path>/scripts/spack/configs/<OperatingSystem><Version> ]``
+
+We define configuration files for Ubuntu20.04, as well as our common LLNL operating systems.
+You will need to create a set of files for your own system.
+
+The configuration files tell spack where the packages installed in :ref:`Required System Packages`
+are located and what version they are. We have provided a ``generic`` set of config files to 
+help in setting this up for you.
+
+#. Copy the directory ``scripts/spack/configs/generic`` to ``scripts/spack/config/<OperatingSystem><Version>`` (you want to match the name of the directory to the one ``tpl-manager.py`` expects to find).
+
+
+#. For each package within the ``packages.py`` file of your new folder edit the version number to be the same as
+   what is installed on your system. There are a number of ways to retrieve versions for a given package:
+
+   * Most version numbers should be searchable through your package manager, there are however, some system libraries that may not be managed by your package manager.
+
+   * If the package has an executable, often you can run with some form of ``-V`` or ``--version``. e.g. for mpich:``mpiexec --version`` will report the MPI version.
+
+   * For packages that only provide libraries, often the system library will be symlinked to one with the version as the extension. e.g. ``ls -lha /usr/lib/x86_64_gnu-linux/libreadlines.so`` will show it is symlinked to ``libreadlines.so.8.1``.
+
+
+#. Each package requires the ``prefix:`` of the installation be provided. In most cases ``/usr`` is sufficient. Typically packages installed with a package manager will place files in: ``/usr/bin``, ``/usr/share``, ``/usr/lib``, ``/usr/lib64``, sometimes ``/usr/lib/x86_64.../``. Here the common prefix is ``/usr``. 
+
+   * If you are building Spheral on a system where you don't have permissions to run package manager and install to ``/usr``, then you might have installed the system packages somewhere else. In that case, replace the ``prefix:`` path for those given packages as necessary.
+
+
 [ex_running_tpl_manager-end]
 
 [lc_running_tpl_manager-start]

docs/build_guide/include/tpls.rst.inc

@@ -26,9 +26,9 @@
 author = 'J. Michael Owen'
 
 # The short X.Y version
-version = '2024.01.0'
+version = '2024.01.1'
 # The full version, including alpha/beta/rc tags
-release = '2024.01.0'
+release = '2024.01.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/conf.py

@@ -26,9 +26,9 @@ copyright = '2012, LLNS'
 author = 'J. Michael Owen'
 
 # The short X.Y version
-version = '2024.01.0'
+version = '2024.01.1'
 # The full version, including alpha/beta/rc tags
-release = '2024.01.0'
+release = '2024.01.1'
 
 
 # -- General configuration ---------------------------------------------------

docs/conf.py.in

@@ -9,7 +9,7 @@ to their environment.
 
 On LC systems we maintain:
   * ``Spheral/risky``
-  * ``Spheral/2024.01.0``
+  * ``Spheral/2024.01.1``
   * ``Spheral/2023.06.0``
   * ``Spheral/2023.03.1``
   * ``Spheral/2023.03.0`` (deprecated as of TOSS4 upgrade)

docs/developer/dev/continuous_deployment.rst

@@ -0,0 +1,75 @@
+*******************************************
+Docker Development Environment
+*******************************************
+
+Spheral builds an up-to-date docker container for every merge-request
+on ``develop``. Developers can use this container to do development tasks
+on local machines.
+
+===========================
+Creating a Dev Environment
+===========================
+
+We will use ``docker dev create`` with our spheral docker image and a 
+local repository. This will allow us to skip setting up a linux system with 
+external packages, gives us pre-built TPLs and allows us to edit a cloned 
+repository from our local machines IDE/text editor.bash::
+
+  > rm <path_to_local_repo>/compose-dev.yaml
+  > docker dev create --base-image ghcr.io/llnl/spheral --name <name_your_env> --path <path_to_local_repo> -o <path_to_local_repo>
+
+.. note::
+   You need to have **Docker Desktop**, **VSCode** and the **VSCode Dev Environment Extension** installed for this to work. You do not need to use VSCode to access the container, but the extension seems to do some of the lifting for us when setting up the volume to our local repo.
+
+**Output** ::
+
+  spheral-recursing_darwin <---- Name of dev environment
+  Creating Dev Environment "spheral-recursing_darwin"
+  populating volume from /Users/davis291/Projects/spheral
+  Creating Dev Environment "spheral-recursing_darwin"
+  detecting language
+  Detecting main repo language...
+  building compose stack
+  building compose stack
+  starting compose stack
+  starting compose stack
+   Network spheral-recursing_darwin_default  Creating
+   Network spheral-recursing_darwin_default  Created
+   Container spheral-recursing_darwin-app-1  Creating
+   Container spheral-recursing_darwin-app-1  Created
+   Container spheral-recursing_darwin-app-1  Starting
+   Container spheral-recursing_darwin-app-1  Started <---- Name of running container to connect to.
+  Dev Environment "spheral-recursing_darwin" (5bd37219d27eb68a77ce6fd8fee05a533a52017d8dcc72430867e2471e428e58) is running!%
+
+
+=============================
+Connecting to a Dev Container
+=============================
+
+Once the continaer has ben started you can connect directly through the terminal
+with the **Container** name (**NOT** the **Dev Environment** name).::
+
+  > docker exec -it spheral-recursing_darwin-app-1 /bin/bash
+  root@671dab5d0b00:/home/spheral/workspace/build_docker-gcc/install#
+
+This drops you into the install location of the ``spheral@develop`` build from
+github, this is a fully installed version of the latest ``develop`` spheral.
+
+.. tip:: 
+  VSCode & Docker Desktop:
+    * Open **Docker Desktop** and navigate to the **Dev Environment** tab. 
+    * Find the container name and select **OPEN IN VSCODE**.
+
+
+=============================
+Development Work
+=============================
+
+Your local Spheral repo is mounted from your local filesystem. You can develop directly from your
+IDE or text editor of choice. Then you can compile and run from within the container itself.
+
+- The local Spheral repository will be mounted in the container at ``/com.docker.devenvironments.code/``. 
+
+- There already exists a full build and install of Spheral at ``develop`` in ``/home/spheral/workspace/build_docker-gcc/install``. 
+
+- An updated host config file can be found at ``/home/spheral/wokspace/docker-gcc.cmake``.

docs/developer/dev/docker_dev_env.rst

@@ -9,6 +9,7 @@ Welcome to Spheral's developer documentation. This documentation is a work in pr
 
    dev/submodules.rst
    dev/diagnostic_tools.rst
+   dev/docker_dev_env.rst
    dev/release_process.rst
    dev/continuous_deployment.rst
 

docs/developer/development_docs.rst

@@ -109,10 +109,6 @@ def build_deps(args):
   for s in spec_list:
     print("** SPEC : {0}".format(s))
 
-  spack_config_dir_opt=""
-  if "SYS_TYPE" not in os.environ.keys():
-    spack_config_dir_opt="--spack-config-dir={0}".format(os.path.join(project_dir, "scripts/spack/configs/x86_64"))
-
   spack_upstream_opt=""
   if os.path.isdir(args.upstream_dir) and not args.no_upstream:
     spack_upstream_opt="--upstream {0}".format(args.upstream_dir)
@@ -124,17 +120,42 @@ def build_deps(args):
   # We use uberenv to set up our spack instance with our respective package.yaml files
   # config.yaml and custom spack packages recipes.
   print("** Running uberenv...")
+
   prefix_opt="--prefix=" + args.spheral_spack_dir
   uberenv_project_json_opt="--project-json={0}".format(uberenv_project_json)
 
   print("** Spheral Spack Dir : {0}".format(args.spheral_spack_dir))
-  sexe("python3 {0} --setup-only {1} {2} {3} {4} {5}".format(uberenv_path, prefix_opt, uberenv_project_json_opt, spack_config_dir_opt, spack_upstream_opt, uberenv_spack_url_opt), echo=True)
 
   # We just want to use the spac instance directly to generate our TPLs, we don't want
   # to have the spack instance take over our environment.
   os.environ["SPACK_DISABLE_LOCAL_CONFIG"] = "1"
   spack_cmd=os.path.join(args.spheral_spack_dir, "spack/bin/spack")
 
+  spheral_config_dir="scripts/spack/configs/"
+  spack_config_dir_opt=""
+  if "SYS_TYPE" not in os.environ.keys():
+    # We need to install spack without any configuration files so we can use
+    # spack arch to determine the OS of the system and later to use spack find
+    # for generating external package files on external systems.
+    if sexe("python3 {0} --setup-only {1} {2} {3} {4}".format(uberenv_path, prefix_opt, uberenv_project_json_opt, spack_upstream_opt, uberenv_spack_url_opt), echo=True): sys.exit(1)
+
+    spack_arch_os = sexe("{0} arch -o".format(spack_cmd), ret_output=True)[1].strip()
+    print("INFO : Detected Operating System :{0}".format(spack_arch_os))
+
+    spheral_config_dir += spack_arch_os
+
+    spack_config_dir_opt="--spack-config-dir={0}".format(os.path.join(project_dir, spheral_config_dir))
+  else:
+    spheral_config_dir += os.environ["SYS_TYPE"]
+
+
+  # Setup spack w/ Uberenv and the appropriate external package/compiler configs.
+  if sexe("python3 {0} --setup-only {1} {2} {3} {4} {5}".format(uberenv_path, prefix_opt, uberenv_project_json_opt, spack_config_dir_opt, spack_upstream_opt, uberenv_spack_url_opt), echo=True): sys.exit(1)
+
+  # Uberenv doesn't copy the concretizer.yaml options...
+  if os.path.exists(spheral_config_dir+"/concretizer.yaml"):
+    sexe("cp {0}/concretizer.yaml {1}".format(spheral_config_dir, os.path.join(args.spheral_spack_dir, "spack/etc/spack/defaults")), echo=True)
+
   # Optionally add a parallel job number for spack builds
   if args.spack_jobs:
     spack_cmd += " --jobs={0}".format(args.spack_jobs)
@@ -149,12 +170,19 @@ def build_deps(args):
   # Loop through the specs we want TPLs for and build/install/get them as necessary.
   if not args.init_only:
       for s in spec_list:
+
         print("** Building TPL's and generating host-config for {0}%{1} ...".format(package_name,s))
         os.environ["SPEC"] = s
         os.environ["LC_ALL"] = "en_US.UTF-8"
+
         if not args.no_spec:
             if sexe("{0} spec --fresh -I {1}@develop%{2}".format(spack_cmd, package_name, s), echo=True) : sys.exit(1)
-        if sexe("{0} dev-build --fresh --quiet --deprecated -u initconfig {2}@develop%{3} 2>&1 | tee -a \"dev-build-{3}-out.txt\"".format(spack_cmd, os.getcwd(), package_name, s), echo=True) : sys.exit(1)
+
+        # Install only the dependencies for Spheral
+        if sexe("{0} install --fail-fast --fresh --deprecated --only dependencies {2}@develop%{3} 2>&1 | tee -a \"dev-build-{3}-out.txt\"".format(spack_cmd, os.getcwd(), package_name, s), echo=True) : sys.exit(1)
+
+        # Using dev-build we can have spack generate an init-config with the local source files for spheral.
+        if sexe("{0} dev-build --fresh --deprecated -u initconfig {2}@develop%{3} 2>&1 | tee -a \"dev-build-{3}-out.txt\"".format(spack_cmd, os.getcwd(), package_name, s), echo=True) : sys.exit(1)
 
       if not args.no_clean:
         sexe("rm dev-build-* spack-build-* spack-configure-args.txt")

scripts/devtools/tpl-manager.py

@@ -0,0 +1,36 @@
+# -------------------------------------------------------------------------
+# This is the default spack configuration file.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing
+# `$SPACK_ROOT/etc/spack/concretizer.yaml`, `~/.spack/concretizer.yaml`,
+# or by adding a `concretizer:` section to an environment.
+# -------------------------------------------------------------------------
+concretizer:
+  # Whether to consider installed packages or packages from buildcaches when
+  # concretizing specs. If `true`, we'll try to use as many installs/binaries
+  # as possible, rather than building. If `false`, we'll always give you a fresh
+  # concretization.
+  reuse: true
+  # Options that tune which targets are considered for concretization. The
+  # concretization process is very sensitive to the number targets, and the time
+  # needed to reach a solution increases noticeably with the number of targets
+  # considered.
+  targets:
+    # Determine whether we want to target specific or generic microarchitectures.
+    # An example of the first kind might be for instance "skylake" or "bulldozer",
+    # while generic microarchitectures are for instance "aarch64" or "x86_64_v4".
+    granularity: generic
+    # If "false" allow targets that are incompatible with the current host (for
+    # instance concretize with target "icelake" while running on "haswell").
+    # If "true" only allow targets that are compatible with the host.
+    host_compatible: true
+  # When "true" concretize root specs of environments together, so that each unique
+  # package in an environment corresponds to one concrete spec. This ensures
+  # environments can always be activated. When "false" perform concretization separately
+  # on each root spec, allowing different versions and variants of the same package in
+  # an environment.
+  unify: true