From 5aff99e51c1d6625dac3e478e2e058da3b654b26 Mon Sep 17 00:00:00 2001 From: Stephen Herbener Date: Tue, 5 Nov 2024 16:36:43 -0700 Subject: [PATCH 1/3] Added setting up a proper python virtual environment to the "using spack environments" instructions. --- doc/source/UsingSpackEnvironments.rst | 49 +++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/doc/source/UsingSpackEnvironments.rst b/doc/source/UsingSpackEnvironments.rst index a22dd9021..c15206770 100644 --- a/doc/source/UsingSpackEnvironments.rst +++ b/doc/source/UsingSpackEnvironments.rst @@ -5,6 +5,13 @@ Using spack-stack environments The following tutorial assumes you have a functioning spack-stack environment installed local to your system. This environment is provided on platforms described in :numref:`Section %s `. If you intend to run spack-stack on your developer machine or on a new platform, you can create an environment using the steps described in :numref:`Section %s `. +There are two primary steps in setting up a usable development environment. +The first is to load the spack-stack environment and the second is to create a python virtual environment that is based on the python executable included within the spack-stack installation. +The reason for the python virtual environment is to ensure that python based applications are utilizing the spack-stack python modules in a consistent manner. + +Load the spack-stack environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Spack environments are used by loading the modulefiles generated at the end of the installation process. These modules control the unix environment and allow CMake, ecbuild, and other build toolchains to resolve the version of software intended for the compilation task. The ``spack`` command itself is not needed in this setup, hence the instructions for creating new environments (``source setup.sh`` etc.) can be ignored. The following is sufficient for loading the modules, allowing them to be used while compiling and running user code. .. note:: @@ -28,3 +35,45 @@ Now list all available modules via ``module available``. You may be required to .. note:: When using ``lua`` modules, loading a different module will automatically switch the dependency modules. This is not the case for ``tcl`` modules. For the latter, it is recommended to start over with a clean shell and repeat the above steps. + +Build and activate a python virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is important that the creation of the python virtual environment be based on the python executable from the spack-stack installation. +This ensures consistency for python applications between the python executable and the spack-stack installed python packages (eg., numpy). +Without this consistency, it is easy for the wrong underlying library versions to get dynamically loaded and cause problems with applications crashing. + +After the :code:`module load stack-python-name/python-version` command is run, the environment variable :code:`python_ROOT` will be set to the path where the spack-stack installed python version is located. +The :code:`python_ROOT` variable can be used to ensure that you get the proper virtual environment set as shown here: + +.. code-block:: console + + ${python_ROOT}/bin/python3 -m venv + +Once the virtual environment is set, it must be activated: + +.. code-block:: console + + source /bin/activate + +and after activation the spack-stack python executable will be the first one in your PATH. +The implication of this is that you should activate the python virtual enviroment as the last step in setting up your environment to ensure that the path to the virtual environment python remains first in your PATH. Here is an example of the whole process: + +.. code-block:: console + + module purge + + module use $SPACK_STACK_GNU_ENV/install/modulefiles/Core + module load stack-gcc/12.2.0 + module load stack-openmpi/4.1.4 + module load stack-python/3.11.7 + + module load jedi-fv3-env + module load ewok-env + module load soca-env + + cd $HOME/projects/jedi + ${python_ROOT}/bin/python3 -m venv jedi_py_venv + source jedi_py_venv/bin/activate + + From b16af43102bde9b06549e446dd737e2ef63b7686 Mon Sep 17 00:00:00 2001 From: Stephen Herbener Date: Wed, 6 Nov 2024 09:37:35 -0700 Subject: [PATCH 2/3] Added step showing how to configure CMake to use the spack-stack based python virtual environment. --- doc/source/UsingSpackEnvironments.rst | 42 ++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/doc/source/UsingSpackEnvironments.rst b/doc/source/UsingSpackEnvironments.rst index c15206770..51619b09e 100644 --- a/doc/source/UsingSpackEnvironments.rst +++ b/doc/source/UsingSpackEnvironments.rst @@ -5,9 +5,10 @@ Using spack-stack environments The following tutorial assumes you have a functioning spack-stack environment installed local to your system. This environment is provided on platforms described in :numref:`Section %s `. If you intend to run spack-stack on your developer machine or on a new platform, you can create an environment using the steps described in :numref:`Section %s `. -There are two primary steps in setting up a usable development environment. +There are three steps in setting up a usable development environment. The first is to load the spack-stack environment and the second is to create a python virtual environment that is based on the python executable included within the spack-stack installation. The reason for the python virtual environment is to ensure that python based applications are utilizing the spack-stack python modules in a consistent manner. +The third step is to configure your build system to use the python virtual environment created in the second step. Load the spack-stack environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -36,8 +37,8 @@ Now list all available modules via ``module available``. You may be required to .. note:: When using ``lua`` modules, loading a different module will automatically switch the dependency modules. This is not the case for ``tcl`` modules. For the latter, it is recommended to start over with a clean shell and repeat the above steps. -Build and activate a python virtual environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create and activate a python virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is important that the creation of the python virtual environment be based on the python executable from the spack-stack installation. This ensures consistency for python applications between the python executable and the spack-stack installed python packages (eg., numpy). @@ -61,19 +62,52 @@ The implication of this is that you should activate the python virtual enviromen .. code-block:: console + # start from clean slate module purge + # load the base packages from the spack-stack environment module use $SPACK_STACK_GNU_ENV/install/modulefiles/Core module load stack-gcc/12.2.0 module load stack-openmpi/4.1.4 module load stack-python/3.11.7 + # load the additional environments required for your + # target application module load jedi-fv3-env module load ewok-env module load soca-env + # Create and activate the spack-stack based python + # virtual environment + # Note that you only need to create the virtual environment + # the first time. Once created you only need to activate + # the virtual environment. cd $HOME/projects/jedi - ${python_ROOT}/bin/python3 -m venv jedi_py_venv + ${python_ROOT}/bin/python3 -m venv jedi_py_venv # first time only source jedi_py_venv/bin/activate +Configure build system to utilize the python virtual environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configuring your application build system to use the python virtual environment will continue the goal of consistency mentioned above where all python scripts and packages within the target application are based on the spack-stack built python executable and packages. + +There are a variety of build systems in use, and CMake is quite commonly used so CMake will be used as an example for this step. +The CMake variable :code:`Python3_FIND_STRATEGY` can be used in conjunction with the python virtual environment to direct CMake to find and use the desired python virtual environment. +By default CMake chooses the latest python installation regardless of which comes first in your PATH. +By setting :code:`Python3_FIND_STRATEGY=LOCATION`, CMake will instead find and use the first python installation found in your PATH. +This is the reason for making the spack-stack based python virtual environment first in PATH in the step above. + +:code:`Python3_FIND_STRATEGY` can be set in two ways: the first in the project's top-level CMakeLists.txt file and the second on the cmake (or ecbuild) command line. +Here are examples of both methods: + +.. code-block:: console + + # In CMakeLists.txt + set( Python3_FIND_STRATEGY LOCATION ) + +.. code-block:: console + + # On the command line + cmake -DPython3_FIND_STRATEGY=LOCATION ... + From 246647e5dce350ea298e1eccb226b94eda948865 Mon Sep 17 00:00:00 2001 From: Stephen Herbener Date: Wed, 6 Nov 2024 10:24:37 -0700 Subject: [PATCH 3/3] [skip ci] Added note encouraging the use of the spack-stack installed python modules --- doc/source/UsingSpackEnvironments.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/source/UsingSpackEnvironments.rst b/doc/source/UsingSpackEnvironments.rst index 51619b09e..21d279c0b 100644 --- a/doc/source/UsingSpackEnvironments.rst +++ b/doc/source/UsingSpackEnvironments.rst @@ -10,6 +10,9 @@ The first is to load the spack-stack environment and the second is to create a p The reason for the python virtual environment is to ensure that python based applications are utilizing the spack-stack python modules in a consistent manner. The third step is to configure your build system to use the python virtual environment created in the second step. +When using a spack-stack environment please utilize the spack-stack installed python modules as much as possible to help maintain the consistency mentioned above. +Note that after loading the spack-stack environment, all of the spack-stack installed python modules have been added to :code:`PYTHONPATH` so they are immediately accessable in your spack-stack based python virtual environment. + Load the spack-stack environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^