From b192dbab91dfca08410c6ba46e579f7489542bc5 Mon Sep 17 00:00:00 2001 From: David Trudgian Date: Fri, 15 Sep 2023 10:29:29 +0100 Subject: [PATCH 1/2] Clarify build environment handling * Host env not passed into the build scriptlets. * Values can be passed in using new templating support. * Re-write SINGULARITY_ENVIRONMENT example, which was less than clear. Fixes #15 Signed-off-by: jason yang --- build_env.rst | 9 +++++++++ definition_files.rst | 26 +++++++++++++++++++------- 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/build_env.rst b/build_env.rst index a9804562..0ffbc3bf 100644 --- a/build_env.rst +++ b/build_env.rst @@ -261,6 +261,15 @@ meaning that no intermediate decrypted data is ever present on disk. See Environment Variables ********************* +You can set environment variables on the host to influence the behaviour of a +build. Note that environment variables are not passed into the build itself, and +cannot be accessed in the ``%post`` section of a definition file. To pass values +into a build, use the :ref:`templating / build-args support ` +introduced in {Singularity} 4.0. + +Environment variables that control a build are generally associated with an +equivalent CLI option. The order of precendence is: + #. If a flag is represented by both a CLI option and an environment variable, and both are set, the CLI option will take precedence. This is true for all environment variables with the exception for ``{ENVPREFIX}_BIND`` and diff --git a/definition_files.rst b/definition_files.rst index 03381842..f545f906 100755 --- a/definition_files.rst +++ b/definition_files.rst @@ -366,12 +366,18 @@ This section is where you can download files from the internet with tools like ``git`` and ``wget``, install new software and libraries, write configuration files, create new directories, etc. +The commands in the ``%post`` section run in a clean environment. Environment +variables from the host are not passed into the build. To pass values into a +build you should use the :ref:`templating / build-args support ` +introduced in {Singularity} 4.0. + Consider the ``%post`` section from the example definition file above: .. code:: {command} %post apt-get update && apt-get install -y netcat + NOW=`date` echo "export NOW=\"${NOW}\"" >> ${ENVPREFIX}_ENVIRONMENT @@ -379,13 +385,19 @@ This ``%post`` scriptlet uses the Ubuntu package manager ``apt`` to update the container and install the program ``netcat`` (that will be used in the ``%startscript`` section below). -The script also sets an environment variable at build time. Note that -the value of this variable cannot be anticipated, and therefore cannot -be set earlier in the ``%environment`` section. For situations like -this, the ``${ENVPREFIX}_ENVIRONMENT`` variable is provided. Assigning a -value to this variable will cause it to be written to a file called -``/.singularity.d/env/91-environment.sh`` that will be sourced by the -container at runtime. +The scriptlet also sets an environment variable called ``NOW`` to the current +date and time. It then writes an ``export`` statement for ``NOW`` into the file +that is pointed to by ``${ENVPREFIX}_ENVIRONMENT``. This demonstrates how to set +container environment variables (available when the container is run), that are +not known when the definition file is written. Because the value of ``$NOW`` is +only known when the ``date`` command in the ``%post`` scriptlet is run, it +cannot be added to the ``%environment`` section. + +Directing output into ``${ENVPREFIX}_ENVIRONMENT`` will cause it to be written +to a shell script file called ``/.singularity.d/env/91-environment.sh`` that +will be sourced by the container at runtime. The ``export NAME=VALUE`` syntax is +needed to make the environment variable available to all processes that are +started in the container. .. note:: From f0e6f4bfccf667b58512fc63a53c2af6714d0cc6 Mon Sep 17 00:00:00 2001 From: jason yang Date: Tue, 12 Mar 2024 09:56:15 +0900 Subject: [PATCH 2/2] patch cherry picked docs Signed-off-by: jason yang --- build_env.rst | 3 +-- definition_files.rst | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/build_env.rst b/build_env.rst index 0ffbc3bf..561c9631 100644 --- a/build_env.rst +++ b/build_env.rst @@ -264,8 +264,7 @@ Environment Variables You can set environment variables on the host to influence the behaviour of a build. Note that environment variables are not passed into the build itself, and cannot be accessed in the ``%post`` section of a definition file. To pass values -into a build, use the :ref:`templating / build-args support ` -introduced in {Singularity} 4.0. +into a build, use the :ref:`templating / build-args support `. Environment variables that control a build are generally associated with an equivalent CLI option. The order of precendence is: diff --git a/definition_files.rst b/definition_files.rst index f545f906..4e92d36f 100755 --- a/definition_files.rst +++ b/definition_files.rst @@ -368,8 +368,7 @@ write configuration files, create new directories, etc. The commands in the ``%post`` section run in a clean environment. Environment variables from the host are not passed into the build. To pass values into a -build you should use the :ref:`templating / build-args support ` -introduced in {Singularity} 4.0. +build you should use the :ref:`templating / build-args support `. Consider the ``%post`` section from the example definition file above: