From 9989f8e2675495763d35b26ccc9fcc07db7fd50f Mon Sep 17 00:00:00 2001 From: Massimiliano Culpo Date: Sun, 30 Oct 2016 20:41:41 +0100 Subject: module file support: major rework of docs (#2169) * module file support: major rework of docs * module file support: fixed issues found by @adamjstewart - list or enumeration should not be indented - use console instead of bash or csh in things that are not scripts - other typos * module file support: fixed other issues found by @adamjstewart - tables should not be indented - substitute lines with pyobject to import an entire function - get help output running commands - typos * module file support: fixes according to review comments - @citibeth moved `spack module loads` after `spack load` - @glennpj tried to clarify installation table + changes to language - @tgamblin Removed top level section and moved the whole thing into the reference manual * module file support: moved directive before spack module loads --- lib/spack/docs/basic_usage.rst | 566 ---------------------------- lib/spack/docs/index.rst | 1 + lib/spack/docs/module_file_support.rst | 659 +++++++++++++++++++++++++++++++++ 3 files changed, 660 insertions(+), 566 deletions(-) create mode 100644 lib/spack/docs/module_file_support.rst diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index 24b53b7593..ca89846d46 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -811,572 +811,6 @@ versions are now filtered out. .. _shell-support: -------------------------------- -Integration with module systems -------------------------------- - -Spack provides some integration with `Environment Modules -`_ to make it easier to use the -packages it installs. If your system does not already have -Environment Modules, see :ref:`InstallEnvironmentModules`. - -.. note:: - - Spack also supports `Dotkit - `_, which is used - by some systems. If you system does not already have a module - system installed, you should use Environment Modules or LMod. - -^^^^^^^^^^^^^^^^^^^^^^^^ -Spack and module systems -^^^^^^^^^^^^^^^^^^^^^^^^ - -You can enable shell support by sourcing some files in the -``/share/spack`` directory. - -For ``bash`` or ``ksh``, run: - -.. code-block:: sh - - export SPACK_ROOT=/path/to/spack - . $SPACK_ROOT/share/spack/setup-env.sh - -For ``csh`` and ``tcsh`` run: - -.. code-block:: csh - - setenv SPACK_ROOT /path/to/spack - source $SPACK_ROOT/share/spack/setup-env.csh - -You can put the above code in your ``.bashrc`` or ``.cshrc``, and -Spack's shell support will be available on the command line. - -When you install a package with Spack, it automatically generates a module file -that lets you add the package to your environment. - -Currently, Spack supports the generation of `Environment Modules -`__ and `Dotkit -`_. Generated -module files for each of these systems can be found in these -directories: - -.. code-block:: sh - - $SPACK_ROOT/share/spack/modules - $SPACK_ROOT/share/spack/dotkit - -The directories are automatically added to your ``MODULEPATH`` and -``DK_NODE`` environment variables when you enable Spack's `shell -support `_. - -^^^^^^^^^^^^^^^^^^^^^^^ -Using Modules & Dotkits -^^^^^^^^^^^^^^^^^^^^^^^ - -If you have shell support enabled you should be able to run either -``module avail`` or ``use -l spack`` to see what modules/dotkits have -been installed. Here is sample output of those programs, showing lots -of installed packages. - -.. code-block:: console - - $ module avail - - ------- /home/gamblin2/spack/share/spack/modules/linux-debian7-x86_64 -------- - adept-utils@1.0%gcc@4.4.7-5adef8da libelf@0.8.13%gcc@4.4.7 - automaded@1.0%gcc@4.4.7-d9691bb0 libelf@0.8.13%intel@15.0.0 - boost@1.55.0%gcc@4.4.7 mpc@1.0.2%gcc@4.4.7-559607f5 - callpath@1.0.1%gcc@4.4.7-5dce4318 mpfr@3.1.2%gcc@4.4.7 - dyninst@8.1.2%gcc@4.4.7-b040c20e mpich@3.0.4%gcc@4.4.7 - gcc@4.9.1%gcc@4.4.7-93ab98c5 mpich@3.0.4%gcc@4.9.0 - gmp@6.0.0a%gcc@4.4.7 mrnet@4.1.0%gcc@4.4.7-72b7881d - graphlib@2.0.0%gcc@4.4.7 netgauge@2.4.6%gcc@4.9.0-27912b7b - launchmon@1.0.1%gcc@4.4.7 stat@2.1.0%gcc@4.4.7-51101207 - libNBC@1.1.1%gcc@4.9.0-27912b7b sundials@2.5.0%gcc@4.9.0-27912b7b - libdwarf@20130729%gcc@4.4.7-b52fac98 - -.. code-block:: console - - $ use -l spack - - spack ---------- - adept-utils@1.0%gcc@4.4.7-5adef8da - adept-utils @1.0 - automaded@1.0%gcc@4.4.7-d9691bb0 - automaded @1.0 - boost@1.55.0%gcc@4.4.7 - boost @1.55.0 - callpath@1.0.1%gcc@4.4.7-5dce4318 - callpath @1.0.1 - dyninst@8.1.2%gcc@4.4.7-b040c20e - dyninst @8.1.2 - gmp@6.0.0a%gcc@4.4.7 - gmp @6.0.0a - libNBC@1.1.1%gcc@4.9.0-27912b7b - libNBC @1.1.1 - libdwarf@20130729%gcc@4.4.7-b52fac98 - libdwarf @20130729 - libelf@0.8.13%gcc@4.4.7 - libelf @0.8.13 - libelf@0.8.13%intel@15.0.0 - libelf @0.8.13 - mpc@1.0.2%gcc@4.4.7-559607f5 - mpc @1.0.2 - mpfr@3.1.2%gcc@4.4.7 - mpfr @3.1.2 - mpich@3.0.4%gcc@4.4.7 - mpich @3.0.4 - mpich@3.0.4%gcc@4.9.0 - mpich @3.0.4 - netgauge@2.4.6%gcc@4.9.0-27912b7b - netgauge @2.4.6 - sundials@2.5.0%gcc@4.9.0-27912b7b - sundials @2.5.0 - -The names here should look familiar, they're the same ones from -``spack find``. You *can* use the names here directly. For example, -you could type either of these commands to load the callpath module: - -.. code-block:: console - - $ use callpath@1.0.1%gcc@4.4.7-5dce4318 - -.. code-block:: console - - $ module load callpath@1.0.1%gcc@4.4.7-5dce4318 - -Neither of these is particularly pretty, easy to remember, or -easy to type. Luckily, Spack has its own interface for using modules -and dotkits. You can use the same spec syntax you're used to: - - ========================= ========================== - Environment Modules Dotkit - ========================= ========================== - ``spack load `` ``spack use `` - ``spack unload `` ``spack unuse `` - ========================= ========================== - -And you can use the same shortened names you use everywhere else in -Spack. For example, this will add the ``mpich`` package built with -``gcc`` to your path: - -.. code-block:: console - - $ spack install mpich %gcc@4.4.7 - - # ... wait for install ... - - $ spack use mpich %gcc@4.4.7 - Prepending: mpich@3.0.4%gcc@4.4.7 (ok) - $ which mpicc - ~/src/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc - -Or, similarly with modules, you could type: - -.. code-block:: console - - $ spack load mpich %gcc@4.4.7 - -These commands will add appropriate directories to your ``PATH``, -``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``. When you no longer -want to use a package, you can type unload or unuse similarly: - -.. code-block:: console - - $ spack unload mpich %gcc@4.4.7 # modules - $ spack unuse mpich %gcc@4.4.7 # dotkit - -.. note:: - - These ``use``, ``unuse``, ``load``, and ``unload`` subcommands are - only available if you have enabled Spack's shell support *and* you - have dotkit or modules installed on your machine. - -^^^^^^^^^^^^^^^^^^^^^^ -Ambiguous module names -^^^^^^^^^^^^^^^^^^^^^^ - -If a spec used with load/unload or use/unuse is ambiguous (i.e. more -than one installed package matches it), then Spack will warn you: - -.. code-block:: console - - $ spack load libelf - ==> Error: Multiple matches for spec libelf. Choose one: - libelf@0.8.13%gcc@4.4.7 arch=linux-debian7-x86_64 - libelf@0.8.13%intel@15.0.0 arch=linux-debian7-x86_64 - -You can either type the ``spack load`` command again with a fully -qualified argument, or you can add just enough extra constraints to -identify one package. For example, above, the key differentiator is -that one ``libelf`` is built with the Intel compiler, while the other -used ``gcc``. You could therefore just type: - -.. code-block:: console - - $ spack load libelf %intel - -To identify just the one built with the Intel compiler. - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Module files generation and customization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Environment Modules and Dotkit files are generated when packages are installed, -and are placed in the following directories under the Spack root: - -.. code-block:: sh - - $SPACK_ROOT/share/spack/modules - $SPACK_ROOT/share/spack/dotkit - -The content that gets written in each module file can be customized in two ways: - -#. overriding part of the ``spack.Package`` API within a ``package.py`` -#. writing dedicated configuration files - -^^^^^^^^^^^^^^^^^^^^^^^^ -Override ``Package`` API -^^^^^^^^^^^^^^^^^^^^^^^^ - -There are currently two methods in ``spack.Package`` that may affect the content -of module files: - -.. code-block:: python - - def setup_environment(self, spack_env, run_env): - """Set up the compile and runtime environments for a package.""" - pass - -.. code-block:: python - - def setup_dependent_environment(self, spack_env, run_env, dependent_spec): - """Set up the environment of packages that depend on this one""" - pass - -As briefly stated in the comments, the first method lets you customize the -module file content for the package you are currently writing, the second -allows for modifications to your dependees module file. In both cases one -needs to fill ``run_env`` with the desired list of environment modifications. - -"""""""""""""""""""""""""""""""""""""""""""""""" -Example : ``builtin/packages/python/package.py`` -"""""""""""""""""""""""""""""""""""""""""""""""" - -The ``python`` package that comes with the ``builtin`` Spack repository -overrides ``setup_dependent_environment`` in the following way: - -.. code-block:: python - - def setup_dependent_environment(self, spack_env, run_env, extension_spec): - if extension_spec.package.extends(self.spec): - run_env.prepend_path('PYTHONPATH', os.path.join(extension_spec.prefix, self.site_packages_dir)) - -to insert the appropriate ``PYTHONPATH`` modifications in the module -files of python packages. - -^^^^^^^^^^^^^^^^^ -Recursive Modules -^^^^^^^^^^^^^^^^^ - -In some cases, it is desirable to load not just a module, but also all -the modules it depends on. This is not required for most modules -because Spack builds binaries with RPATH support. However, not all -packages use RPATH to find their dependencies: this can be true in -particular for Python extensions, which are currently *not* built with -RPATH. - -Scripts to load modules recursively may be made with the command: - -.. code-block:: console - - $ spack module loads --dependencies - -An equivalent alternative is: - -.. code-block :: console - - $ source <( spack module loads --dependencies ) - -.. warning:: - - The ``spack load`` command does not currently accept the - ``--dependencies`` flag. Use ``spack module loads`` instead, for - now. - -.. See #1662 - - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Module Commands for Shell Scripts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Although Spack is flexible, the ``module`` command is much faster. -This could become an issue when emitting a series of ``spack load`` -commands inside a shell script. By adding the ``--shell`` flag, -``spack module find`` may also be used to generate code that can be -cut-and-pasted into a shell script. For example: - -.. code-block:: console - - $ spack module loads --dependencies py-numpy git - # bzip2@1.0.6%gcc@4.9.3=linux-x86_64 - module load bzip2-1.0.6-gcc-4.9.3-ktnrhkrmbbtlvnagfatrarzjojmkvzsx - # ncurses@6.0%gcc@4.9.3=linux-x86_64 - module load ncurses-6.0-gcc-4.9.3-kaazyneh3bjkfnalunchyqtygoe2mncv - # zlib@1.2.8%gcc@4.9.3=linux-x86_64 - module load zlib-1.2.8-gcc-4.9.3-v3ufwaahjnviyvgjcelo36nywx2ufj7z - # sqlite@3.8.5%gcc@4.9.3=linux-x86_64 - module load sqlite-3.8.5-gcc-4.9.3-a3eediswgd5f3rmto7g3szoew5nhehbr - # readline@6.3%gcc@4.9.3=linux-x86_64 - module load readline-6.3-gcc-4.9.3-se6r3lsycrwxyhreg4lqirp6xixxejh3 - # python@3.5.1%gcc@4.9.3=linux-x86_64 - module load python-3.5.1-gcc-4.9.3-5q5rsrtjld4u6jiicuvtnx52m7tfhegi - # py-setuptools@20.5%gcc@4.9.3=linux-x86_64 - module load py-setuptools-20.5-gcc-4.9.3-4qr2suj6p6glepnedmwhl4f62x64wxw2 - # py-nose@1.3.7%gcc@4.9.3=linux-x86_64 - module load py-nose-1.3.7-gcc-4.9.3-pwhtjw2dvdvfzjwuuztkzr7b4l6zepli - # openblas@0.2.17%gcc@4.9.3+shared=linux-x86_64 - module load openblas-0.2.17-gcc-4.9.3-pw6rmlom7apfsnjtzfttyayzc7nx5e7y - # py-numpy@1.11.0%gcc@4.9.3+blas+lapack=linux-x86_64 - module load py-numpy-1.11.0-gcc-4.9.3-mulodttw5pcyjufva4htsktwty4qd52r - # curl@7.47.1%gcc@4.9.3=linux-x86_64 - module load curl-7.47.1-gcc-4.9.3-ohz3fwsepm3b462p5lnaquv7op7naqbi - # autoconf@2.69%gcc@4.9.3=linux-x86_64 - module load autoconf-2.69-gcc-4.9.3-bkibjqhgqm5e3o423ogfv2y3o6h2uoq4 - # cmake@3.5.0%gcc@4.9.3~doc+ncurses+openssl~qt=linux-x86_64 - module load cmake-3.5.0-gcc-4.9.3-x7xnsklmgwla3ubfgzppamtbqk5rwn7t - # expat@2.1.0%gcc@4.9.3=linux-x86_64 - module load expat-2.1.0-gcc-4.9.3-6pkz2ucnk2e62imwakejjvbv6egncppd - # git@2.8.0-rc2%gcc@4.9.3+curl+expat=linux-x86_64 - module load git-2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd - -The script may be further edited by removing unnecessary modules. - - -^^^^^^^^^^^^^^^ -Module Prefixes -^^^^^^^^^^^^^^^ - -On some systems, modules are automatically prefixed with a certain -string; ``spack module loads`` needs to know about that prefix when it -issues ``module load`` commands. Add the ``--prefix`` option to your -``spack module loads`` commands if this is necessary. - -For example, consider the following on one system: - -..code-block:: console - - $ module avail - linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y - - $ spack module loads antlr # WRONG! - # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64 - module load antlr-2.7.7-gcc-5.3.0-bdpl46y - - $ spack module loads --prefix linux-SuSE11-x86_64/ antlr - # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64 - module load linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y - -^^^^^^^^^^^^^^^^^^^ -Configuration files -^^^^^^^^^^^^^^^^^^^ - -Another way of modifying the content of module files is writing a -``modules.yaml`` configuration file. Following usual Spack conventions, this -file can be placed either at *site* or *user* scope. - -The default site configuration reads: - -.. literalinclude:: ../../../etc/spack/defaults/modules.yaml - :language: yaml - -It basically inspects the installation prefixes for the -existence of a few folders and, if they exist, it prepends a path to a given -list of environment variables. - -For each module system that can be enabled a finer configuration is possible: - -.. code-block:: yaml - - modules: - tcl: - # contains environment modules specific customizations - dotkit: - # contains dotkit specific customizations - -The structure under the ``tcl`` and ``dotkit`` keys is almost equal, and will -be showcased in the following by some examples. - -""""""""""""""""""""""""""""""""""""""" -Select module files by spec constraints -""""""""""""""""""""""""""""""""""""""" - -Using spec syntax it's possible to have different customizations for different -groups of module files. - -Considering : - -.. code-block:: yaml - - modules: - tcl: - all: # Default addition for every package - environment: - set: - BAR: 'bar' - ^openmpi:: # A double ':' overrides previous rules - environment: - set: - BAR: 'baz' - zlib: - environment: - prepend_path: - LD_LIBRARY_PATH: 'foo' - zlib%gcc@4.8: - environment: - unset: - - FOOBAR - -what will happen is that: - - - every module file will set ``BAR=bar`` - - unless the associated spec satisfies ``^openmpi`` in which case ``BAR=baz`` - - any spec that satisfies ``zlib`` will additionally prepend ``foo`` to ``LD_LIBRARY_PATH`` - - any spec that satisfies ``zlib%gcc@4.8`` will additionally unset ``FOOBAR`` - -.. note:: - Order does matter - The modifications associated with the ``all`` keyword are always evaluated - first, no matter where they appear in the configuration file. All the other - spec constraints are instead evaluated top to bottom. - -"""""""""""""""""""""""""""""""""""""""" -Filter modifications out of module files -"""""""""""""""""""""""""""""""""""""""" - -Modifications to certain environment variables in module files are generated by -default. Suppose you would like to avoid having ``CPATH`` and ``LIBRARY_PATH`` -modified by your dotkit modules. Then : - -.. code-block:: yaml - - modules: - dotkit: - all: - filter: - # Exclude changes to any of these variables - environment_blacklist: ['CPATH', 'LIBRARY_PATH'] - -will generate dotkit module files that will not contain modifications to either -``CPATH`` or ``LIBRARY_PATH`` and environment module files that instead will -contain those modifications. - -""""""""""""""""""""" -Autoload dependencies -""""""""""""""""""""" - -The following lines in ``modules.yaml``: - -.. code-block:: yaml - - modules: - tcl: - all: - autoload: 'direct' - -will produce environment module files that will automatically load their direct -dependencies. - -.. note:: - Allowed values for ``autoload`` statements - Allowed values for ``autoload`` statements are either ``none``, ``direct`` - or ``all``. In ``tcl`` configuration it is possible to use the option - ``prerequisites`` that accepts the same values and will add ``prereq`` - statements instead of automatically loading other modules. - -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -Blacklist or whitelist the generation of specific module files -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Sometimes it is desirable not to generate module files, a common use case being -not providing the users with software built using the system compiler. - -A configuration file like: - -.. code-block:: yaml - - modules: - tcl: - whitelist: ['gcc', 'llvm'] # Whitelist will have precedence over blacklist - blacklist: ['%gcc@4.4.7'] # Assuming gcc@4.4.7 is the system compiler - -will skip module file generation for anything that satisfies ``%gcc@4.4.7``, -with the exception of specs that satisfy ``gcc`` or ``llvm``. - -"""""""""""""""""""""""""""""""""""""""""""""""" -Customize the naming scheme and insert conflicts -"""""""""""""""""""""""""""""""""""""""""""""""" - -A configuration file like: - -.. code-block:: yaml - - modules: - tcl: - naming_scheme: '{name}/{version}-{compiler.name}-{compiler.version}' - all: - conflict: ['{name}', 'intel/14.0.1'] - -will create module files that will conflict with ``intel/14.0.1`` and with the -base directory of the same module, effectively preventing the possibility to -load two or more versions of the same software at the same time. - -.. note:: - Tokens available for the naming scheme - currently only the tokens shown in the example are available to construct - the naming scheme - -.. note:: - The ``conflict`` option is ``tcl`` specific - -The names of environment modules generated by spack are not always easy to -fully comprehend due to the long hash in the name. There are two module -configuration options to help with that. The first is a global setting to -adjust the hash length. It can be set anywhere from 0 to 32 and has a default -length of 7. This is the representation of the hash in the module file name and -does not affect the size of the package hash. Be aware that the smaller the -hash length the more likely naming conflicts will occur. The following snippet -shows how to set hash length in the module file names: - -.. code-block:: yaml - - modules: - tcl: - hash_length: 7 - -To help make module names more readable, and to help alleviate name conflicts -with a short hash, one can use the ``suffixes`` option in the modules -configuration file. This option will add strings to modules that match a spec. -For instance, the following config options, - -.. code-block:: yaml - - modules: - tcl: - all: - suffixes: - ^python@2.7.12: 'python-2.7.12' - ^openblas: 'openblas' - -will add a ``python-2.7.12`` version string to any packages compiled with -python matching the spec, ``python@2.7.12``. This is useful to know which -version of python a set of python extensions is associated with. Likewise, the -``openblas`` string is attached to any program that has openblas in the spec, -most likely via the ``+blas`` variant specification. - -^^^^^^^^^^^^^^^^^^^^^^^^^ -Regenerating Module files -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Module and dotkit files are generated when packages are installed, and -are placed in the directory ``share/spack/modules`` under the Spack -root. The command ``spack refresh`` will regenerate them all without -re-building the packages; for example, if module format or options -have changed: - -.. code-block:: console - - $ spack module refresh - ==> Regenerating tcl module files. - ==> Regenerating dotkit module files. - -.. _extensions: - --------------------------- Extensions & Python support --------------------------- diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst index 2463a208ab..026b01b628 100644 --- a/lib/spack/docs/index.rst +++ b/lib/spack/docs/index.rst @@ -53,6 +53,7 @@ or refer to the full manual below. configuration mirrors + module_file_support package_list command_index diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst new file mode 100644 index 0000000000..502152bc73 --- /dev/null +++ b/lib/spack/docs/module_file_support.rst @@ -0,0 +1,659 @@ +=============================== +Integration with module systems +=============================== + +The use of module systems to manage user environment in a controlled way +is a common practice at HPC centers that is often embraced also by individual +programmers on their development machines. To support this common practice +Spack provides integration with `Environment Modules +`_ , `LMod +`_ and `Dotkit `_ by: + +* generating module files after a successful installation +* providing commands that can leverage the spec syntax to manipulate modules + +In the following you will see how to activate shell support for commands in Spack +that requires it, and discover what benefits this may bring with respect to deal +directly with automatically generated module files. + +.. note:: + + If your machine does not already have a module system installed, + we advise you to use either Environment Modules or LMod. See :ref:`InstallEnvironmentModules` + for more details. + +------------- +Shell support +------------- + +You can enable shell support by sourcing the appropriate setup file +in the ``$SPACK_ROOT/share/spack`` directory. +For ``bash`` or ``ksh`` users: + +.. code-block:: console + + $ . ${SPACK_ROOT}/share/spack/setup-env.sh + +For ``csh`` and ``tcsh`` instead: + +.. code-block:: console + + $ source $SPACK_ROOT/share/spack/setup-env.csh + + +.. note:: + You can put the source line in your ``.bashrc`` or ``.cshrc`` to + have Spack's shell support available on the command line at any login. + + +---------------------------- +Using module files via Spack +---------------------------- + +If you have shell support enabled you should be able to run either +``module avail`` or ``use -l spack`` to see what module/dotkit files have +been installed. Here is sample output of those programs, showing lots +of installed packages. + +.. code-block:: console + + $ module avail + + ------- /home/gamblin2/spack/share/spack/modules/linux-debian7-x86_64 -------- + adept-utils@1.0%gcc@4.4.7-5adef8da libelf@0.8.13%gcc@4.4.7 + automaded@1.0%gcc@4.4.7-d9691bb0 libelf@0.8.13%intel@15.0.0 + boost@1.55.0%gcc@4.4.7 mpc@1.0.2%gcc@4.4.7-559607f5 + callpath@1.0.1%gcc@4.4.7-5dce4318 mpfr@3.1.2%gcc@4.4.7 + dyninst@8.1.2%gcc@4.4.7-b040c20e mpich@3.0.4%gcc@4.4.7 + gcc@4.9.1%gcc@4.4.7-93ab98c5 mpich@3.0.4%gcc@4.9.0 + gmp@6.0.0a%gcc@4.4.7 mrnet@4.1.0%gcc@4.4.7-72b7881d + graphlib@2.0.0%gcc@4.4.7 netgauge@2.4.6%gcc@4.9.0-27912b7b + launchmon@1.0.1%gcc@4.4.7 stat@2.1.0%gcc@4.4.7-51101207 + libNBC@1.1.1%gcc@4.9.0-27912b7b sundials@2.5.0%gcc@4.9.0-27912b7b + libdwarf@20130729%gcc@4.4.7-b52fac98 + +.. code-block:: console + + $ use -l spack + + spack ---------- + adept-utils@1.0%gcc@4.4.7-5adef8da - adept-utils @1.0 + automaded@1.0%gcc@4.4.7-d9691bb0 - automaded @1.0 + boost@1.55.0%gcc@4.4.7 - boost @1.55.0 + callpath@1.0.1%gcc@4.4.7-5dce4318 - callpath @1.0.1 + dyninst@8.1.2%gcc@4.4.7-b040c20e - dyninst @8.1.2 + gmp@6.0.0a%gcc@4.4.7 - gmp @6.0.0a + libNBC@1.1.1%gcc@4.9.0-27912b7b - libNBC @1.1.1 + libdwarf@20130729%gcc@4.4.7-b52fac98 - libdwarf @20130729 + libelf@0.8.13%gcc@4.4.7 - libelf @0.8.13 + libelf@0.8.13%intel@15.0.0 - libelf @0.8.13 + mpc@1.0.2%gcc@4.4.7-559607f5 - mpc @1.0.2 + mpfr@3.1.2%gcc@4.4.7 - mpfr @3.1.2 + mpich@3.0.4%gcc@4.4.7 - mpich @3.0.4 + mpich@3.0.4%gcc@4.9.0 - mpich @3.0.4 + netgauge@2.4.6%gcc@4.9.0-27912b7b - netgauge @2.4.6 + sundials@2.5.0%gcc@4.9.0-27912b7b - sundials @2.5.0 + +The names here should look familiar, they're the same ones from +``spack find``. You *can* use the names here directly. For example, +you could type either of these commands to load the callpath module: + +.. code-block:: console + + $ use callpath@1.0.1%gcc@4.4.7-5dce4318 + +.. code-block:: console + + $ module load callpath@1.0.1%gcc@4.4.7-5dce4318 + +Neither of these is particularly pretty, easy to remember, or +easy to type. Luckily, Spack has its own interface for using modules +and dotkits. You can use the same spec syntax you're used to: + +========================= ========================== +Environment Modules Dotkit +========================= ========================== +``spack load `` ``spack use `` +``spack unload `` ``spack unuse `` +========================= ========================== + +And you can use the same shortened names you use everywhere else in +Spack. For example, this will add the ``mpich`` package built with +``gcc`` to your path: + +.. code-block:: console + + $ spack install mpich %gcc@4.4.7 + + # ... wait for install ... + + $ spack use mpich %gcc@4.4.7 + Prepending: mpich@3.0.4%gcc@4.4.7 (ok) + $ which mpicc + ~/src/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc + +Or, similarly with modules, you could type: + +.. code-block:: console + + $ spack load mpich %gcc@4.4.7 + +These commands will add appropriate directories to your ``PATH``, +``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``. When you no longer +want to use a package, you can type unload or unuse similarly: + +.. code-block:: console + + $ spack unload mpich %gcc@4.4.7 # modules + $ spack unuse mpich %gcc@4.4.7 # dotkit + +.. note:: + + These ``use``, ``unuse``, ``load``, and ``unload`` subcommands are + only available if you have enabled Spack's shell support *and* you + have dotkit or modules installed on your machine. + +---------------------- +Ambiguous module names +---------------------- + +If a spec used with load/unload or use/unuse is ambiguous (i.e. more +than one installed package matches it), then Spack will warn you: + +.. code-block:: console + + $ spack load libelf + ==> Error: Multiple matches for spec libelf. Choose one: + libelf@0.8.13%gcc@4.4.7 arch=linux-debian7-x86_64 + libelf@0.8.13%intel@15.0.0 arch=linux-debian7-x86_64 + +You can either type the ``spack load`` command again with a fully +qualified argument, or you can add just enough extra constraints to +identify one package. For example, above, the key differentiator is +that one ``libelf`` is built with the Intel compiler, while the other +used ``gcc``. You could therefore just type: + +.. code-block:: console + + $ spack load libelf %intel + +To identify just the one built with the Intel compiler. + +.. _extensions: + +---------------------- +``spack module loads`` +---------------------- + +In some cases, it is desirable to load not just a module, but also all +the modules it depends on. This is not required for most modules +because Spack builds binaries with RPATH support. However, not all +packages use RPATH to find their dependencies: this can be true in +particular for Python extensions, which are currently *not* built with +RPATH. + +Scripts to load modules recursively may be made with the command: + +.. code-block:: console + + $ spack module loads --dependencies + +An equivalent alternative is: + +.. code-block :: console + + $ source <( spack module loads --dependencies ) + +.. warning:: + + The ``spack load`` command does not currently accept the + ``--dependencies`` flag. Use ``spack module loads`` instead, for + now. + +.. See #1662 + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Module Commands for Shell Scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Although Spack is flexible, the ``module`` command is much faster. +This could become an issue when emitting a series of ``spack load`` +commands inside a shell script. By adding the ``--shell`` flag, +``spack module find`` may also be used to generate code that can be +cut-and-pasted into a shell script. For example: + +.. code-block:: console + + $ spack module loads --dependencies py-numpy git + # bzip2@1.0.6%gcc@4.9.3=linux-x86_64 + module load bzip2-1.0.6-gcc-4.9.3-ktnrhkrmbbtlvnagfatrarzjojmkvzsx + # ncurses@6.0%gcc@4.9.3=linux-x86_64 + module load ncurses-6.0-gcc-4.9.3-kaazyneh3bjkfnalunchyqtygoe2mncv + # zlib@1.2.8%gcc@4.9.3=linux-x86_64 + module load zlib-1.2.8-gcc-4.9.3-v3ufwaahjnviyvgjcelo36nywx2ufj7z + # sqlite@3.8.5%gcc@4.9.3=linux-x86_64 + module load sqlite-3.8.5-gcc-4.9.3-a3eediswgd5f3rmto7g3szoew5nhehbr + # readline@6.3%gcc@4.9.3=linux-x86_64 + module load readline-6.3-gcc-4.9.3-se6r3lsycrwxyhreg4lqirp6xixxejh3 + # python@3.5.1%gcc@4.9.3=linux-x86_64 + module load python-3.5.1-gcc-4.9.3-5q5rsrtjld4u6jiicuvtnx52m7tfhegi + # py-setuptools@20.5%gcc@4.9.3=linux-x86_64 + module load py-setuptools-20.5-gcc-4.9.3-4qr2suj6p6glepnedmwhl4f62x64wxw2 + # py-nose@1.3.7%gcc@4.9.3=linux-x86_64 + module load py-nose-1.3.7-gcc-4.9.3-pwhtjw2dvdvfzjwuuztkzr7b4l6zepli + # openblas@0.2.17%gcc@4.9.3+shared=linux-x86_64 + module load openblas-0.2.17-gcc-4.9.3-pw6rmlom7apfsnjtzfttyayzc7nx5e7y + # py-numpy@1.11.0%gcc@4.9.3+blas+lapack=linux-x86_64 + module load py-numpy-1.11.0-gcc-4.9.3-mulodttw5pcyjufva4htsktwty4qd52r + # curl@7.47.1%gcc@4.9.3=linux-x86_64 + module load curl-7.47.1-gcc-4.9.3-ohz3fwsepm3b462p5lnaquv7op7naqbi + # autoconf@2.69%gcc@4.9.3=linux-x86_64 + module load autoconf-2.69-gcc-4.9.3-bkibjqhgqm5e3o423ogfv2y3o6h2uoq4 + # cmake@3.5.0%gcc@4.9.3~doc+ncurses+openssl~qt=linux-x86_64 + module load cmake-3.5.0-gcc-4.9.3-x7xnsklmgwla3ubfgzppamtbqk5rwn7t + # expat@2.1.0%gcc@4.9.3=linux-x86_64 + module load expat-2.1.0-gcc-4.9.3-6pkz2ucnk2e62imwakejjvbv6egncppd + # git@2.8.0-rc2%gcc@4.9.3+curl+expat=linux-x86_64 + module load git-2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd + +The script may be further edited by removing unnecessary modules. + + +^^^^^^^^^^^^^^^ +Module Prefixes +^^^^^^^^^^^^^^^ + +On some systems, modules are automatically prefixed with a certain +string; ``spack module loads`` needs to know about that prefix when it +issues ``module load`` commands. Add the ``--prefix`` option to your +``spack module loads`` commands if this is necessary. + +For example, consider the following on one system: + +.. code-block:: console + + $ module avail + linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y + + $ spack module loads antlr # WRONG! + # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64 + module load antlr-2.7.7-gcc-5.3.0-bdpl46y + + $ spack module loads --prefix linux-SuSE11-x86_64/ antlr + # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64 + module load linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y + +======================= +Module files generation +======================= + +Module files are generated by post-install hooks after the successful +installation of a package. They are placed in the following directories +under the Spack root: + + +----------------------------------------+------------------------------------+------------------------+ + | | **Module Files Root directory** | **Compatible systems** | + +========================================+====================================+========================+ + | **Dotkit Module Files** | share/spack/dotkit | DotKit | + +----------------------------------------+------------------------------------+------------------------+ + | **Non-Hierarchical TCL Module Files** | share/spack/modules | Env. Modules/LMod | + +----------------------------------------+------------------------------------+------------------------+ + | **Lua Hierarchical Module Files** | share/spack/lmod | LMod | + +----------------------------------------+------------------------------------+------------------------+ + + +Though Spack ships with sensible defaults for the generation of module files, +one can customize many aspects of it to accommodate package or site specific needs. +These customizations are enabled by either: + + 1. overriding certain callback APIs in the Python packages + 2. writing specific rules in the ``modules.yaml`` configuration file + +The former method fits best cases that are site independent, e.g. injecting variables +from language interpreters into their extensions. The latter instead permits to +fine tune the content, naming and creation of module files to meet site specific conventions. + +-------------------------- +Overriding ``Package`` API +-------------------------- + +There are two methods that can be overridden in any ``package.py`` to affect the +content of generated module files. The first one is: + +.. code-block:: python + + def setup_environment(self, spack_env, run_env): + """Set up the compile and runtime environments for a package.""" + pass + +and can alter the content of *the same package where it is overridden* +by adding actions to ``run_env``. The second method is: + +.. code-block:: python + + def setup_dependent_environment(self, spack_env, run_env, dependent_spec): + """Set up the environment of packages that depend on this one""" + pass + +and has similar effects on module file of dependees. Even in this case +``run_env`` must be filled with the desired list of environment modifications. + +.. note:: + The ``R`` package and callback APIs + A typical example in which overriding both methods prove to be useful + is given by the ``R`` package. This package installs libraries and headers + in non-standard locations and it is possible to prepend the appropriate directory + to the corresponding environment variables: + + ================== ================================= + LIBRARY_PATH ``self.prefix/rlib/R/lib`` + LD_LIBRARY_PATH ``self.prefix/rlib/R/lib`` + CPATH ``self.prefix/rlib/R/include`` + ================== ================================= + + with the following snippet: + + .. literalinclude:: ../../../var/spack/repos/builtin/packages/R/package.py + :pyobject: R.setup_environment + + The ``R`` package also knows which environment variable should be modified + to make language extensions provided by other packages available, and modifies + it appropriately in the override of the second method: + + .. literalinclude:: ../../../var/spack/repos/builtin/packages/R/package.py + :lines: 128-129,146-151 + +------------------------------ +Configuration file for modules +------------------------------ + +The name of the configuration file that controls module generation behavior +is ``modules.yaml``. The default configuration: + +.. literalinclude:: ../../../etc/spack/defaults/modules.yaml + :language: yaml + +activates generation for ``tcl`` and ``dotkit`` module files and inspects +the installation folder of each package for the presence of a set of subdirectories +(``bin``, ``man``, ``share/man``, etc.). If any is found its full path is prepended +to the environment variables listed below the folder name. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Activation of other systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Any other module file generator shipped with Spack can be activated adding it to the +list under the ``enable`` key in the module file. Currently the only generator that +is not activated by default is ``lmod``, which produces hierarchical lua module files. +For each module system that can be enabled a finer configuration is possible. + +Directives that are aimed at driving the generation of a particular type of module files +should be listed under a top level key that corresponds to the generator being +customized: + +.. code-block:: yaml + + modules: + enable: + - tcl + - dotkit + - lmod + tcl: + # contains environment modules specific customizations + dotkit: + # contains dotkit specific customizations + lmod: + # contains lmod specific customizations + +All these module sections allow for both: + +1. global directives that usually affect the whole layout of modules or the naming scheme +2. directives that affect only a set of packages and modify their content + +For the latter point in particular it is possible to use anonymous specs +to select an appropriate set of packages on which the modifications should be applied. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Selection by anonymous specs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The procedure to select packages using anonymous specs is a natural +extension of using them to install packages, the only difference being +that specs in this case **are not required to have a root package**. +Consider for instance this snippet: + +.. code-block:: yaml + + modules: + tcl: + # The keyword `all` selects every package + all: + environment: + set: + BAR: 'bar' + # This anonymous spec selects any package that + # depends on openmpi. The double colon at the + # end clears the set of rules that matched so far. + ^openmpi:: + environment: + set: + BAR: 'baz' + # Selects any zlib package + zlib: + environment: + prepend_path: + LD_LIBRARY_PATH: 'foo' + # Selects zlib compiled with gcc@4.8 + zlib%gcc@4.8: + environment: + unset: + - FOOBAR + +During module file generation, the configuration above will instruct +Spack to set the environment variable ``BAR=bar`` for every module, +unless the associated spec satisfies ``^openmpi`` in which case ``BAR=baz``. +In addition in any spec that satisfies ``zlib`` the value ``foo`` will be +prepended to ``LD_LIBRARY_PATH`` and in any spec that satisfies ``zlib%gcc@4.8`` +the variable ``FOOBAR`` will be unset. + +.. note:: + Order does matter + The modifications associated with the ``all`` keyword are always evaluated + first, no matter where they appear in the configuration file. All the other + spec constraints are instead evaluated top to bottom. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Blacklist or whitelist the generation of specific module files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Anonymous specs are also used to prevent module files from being written or +to force them to be written. A common case for that at HPC centers is to hide +from users all of the software that needs to be built with system compilers. +Suppose for instance to have ``gcc@4.4.7`` provided by your system. Then +with a configuration file like this one: + +.. code-block:: yaml + + modules: + tcl: + whitelist: ['gcc', 'llvm'] # Whitelist will have precedence over blacklist + blacklist: ['%gcc@4.4.7'] # Assuming gcc@4.4.7 is the system compiler + +you will skip the generation of module files for any package that +is compiled with ``gcc@4.4.7``, with the exception of any ``gcc`` +or any ``llvm`` installation. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Customize the naming scheme +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The names of environment modules generated by spack are not always easy to +fully comprehend due to the long hash in the name. There are two module +configuration options to help with that. The first is a global setting to +adjust the hash length. It can be set anywhere from 0 to 32 and has a default +length of 7. This is the representation of the hash in the module file name and +does not affect the size of the package hash. Be aware that the smaller the +hash length the more likely naming conflicts will occur. The following snippet +shows how to set hash length in the module file names: + +.. code-block:: yaml + + modules: + tcl: + hash_length: 7 + +To help make module names more readable, and to help alleviate name conflicts +with a short hash, one can use the ``suffixes`` option in the modules +configuration file. This option will add strings to modules that match a spec. +For instance, the following config options, + +.. code-block:: yaml + + modules: + tcl: + all: + suffixes: + ^python@2.7.12: 'python-2.7.12' + ^openblas: 'openblas' + +will add a ``python-2.7.12`` version string to any packages compiled with +python matching the spec, ``python@2.7.12``. This is useful to know which +version of python a set of python extensions is associated with. Likewise, the +``openblas`` string is attached to any program that has openblas in the spec, +most likely via the ``+blas`` variant specification. + +.. note:: + TCL module files + A modification that is specific to ``tcl`` module files is the possibility + to change the naming scheme of modules. + + .. code-block:: yaml + + modules: + tcl: + naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVERSION}' + all: + conflict: ['${PACKAGE}', 'intel/14.0.1'] + + will create module files that will conflict with ``intel/14.0.1`` and with the + base directory of the same module, effectively preventing the possibility to + load two or more versions of the same software at the same time. The tokens + that are available for use in this directive are the same understood by + the ``Spec.format`` method. + + +.. note:: + LMod hierarchical module files + When ``lmod`` is activated Spack will generate a set of hierarchical lua module + files that are understood by LMod. The generated hierarchy always contains the + three layers ``Core`` / ``Compiler`` / ``MPI`` but can be further extended to + any other virtual dependency present in Spack. A case that could be useful in + practice is for instance: + + .. code-block:: yaml + + modules: + enable: + - lmod + lmod: + core_compilers: ['gcc@4.8'] + hierarchical_scheme: ['lapack'] + + that will generate a hierarchy in which the ``lapack`` layer is treated as the ``mpi`` + one. This allows a site to build the same libraries or applications against different + implementations of ``mpi`` and ``lapack``, and let LMod switch safely from one to the + other. + +.. warning:: + Deep hierarchies and ``lmod spider`` + For hierarchies that are deeper than three layers ``lmod spider`` may have some issues. + See `this discussion on the LMod project `_. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Filter out environment modifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Modifications to certain environment variables in module files are generated by +default, for instance by prefix inspections in the default configuration file. +There are cases though where some of these modifications are unwanted. +Suppose you need to avoid having ``CPATH`` and ``LIBRARY_PATH`` +modified by your ``dotkit`` modules: + +.. code-block:: yaml + + modules: + dotkit: + all: + filter: + # Exclude changes to any of these variables + environment_blacklist: ['CPATH', 'LIBRARY_PATH'] + +The configuration above will generate dotkit module files that will not contain +modifications to either ``CPATH`` or ``LIBRARY_PATH`` and environment module +files that instead will contain these modifications. + +^^^^^^^^^^^^^^^^^^^^^ +Autoload dependencies +^^^^^^^^^^^^^^^^^^^^^ + +In some cases it can be useful to have module files directly autoload their dependencies. +This may be the case for Python extensions, if not activated using ``spack activate``: + +.. code-block:: yaml + + modules: + tcl: + ^python: + autoload: 'direct' + +The configuration file above will produce module files that will automatically +load their direct dependencies. The allowed values for the ``autoload`` statement +are either ``none``, ``direct`` or ``all``. + +.. note:: + TCL prerequisites + In the ``tcl`` section of the configuration file it is possible to use + the ``prerequisites`` directive that accepts the same values as ``autoload``. + It will produce module files that have a ``prereq`` + statement instead of automatically loading other modules. + +======================== +Module files maintenance +======================== + +Spack not only provides great flexibility in the generation of module files +and in the customization of both their layout and content, but also ships with +a tool to ease the burden of their maintenance in production environments. +This tool is the ``spack module`` command: + +.. command-output:: spack module --help + +------------------------ +``spack module refresh`` +------------------------ + +The command that regenerates module files to update their content or their layout +is ``module refresh``: + +.. command-output:: spack module refresh --help + +A set of packages can be selected using anonymous specs for the optional +``constraint`` positional argument. The argument ``--module-type`` identifies +the type of module files to refresh. Optionally the entire tree can be deleted +before regeneration if the change in layout is radical. + +------------------- +``spack module rm`` +------------------- + +If instead what you need is just to delete a few module files, then the right +command is ``module rm``: + +.. command-output:: spack module rm --help + +.. note:: + We care about your module files! + Every modification done on modules that are already existing will + ask for a confirmation by default. If the command is used in a script it is + possible though to pass the ``-y`` argument, that will skip this safety measure. -- cgit v1.2.3-70-g09d2