diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 250 | ||||
| -rw-r--r-- | lib/spack/docs/getting_started.rst | 80 | ||||
| -rw-r--r-- | lib/spack/docs/module_file_support.rst | 351 |
3 files changed, 344 insertions, 337 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index 6642b2adbd..221516238e 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -31,7 +31,7 @@ colorized output. .. code-block:: console - $ spack --color always | less -R + $ spack --color always | less -R -------------------------- Listing available packages @@ -329,85 +329,6 @@ the tarballs in question to it (see :ref:`mirrors`): $ spack install galahad ------------------------------ -Deprecating insecure packages ------------------------------ - -``spack deprecate`` allows for the removal of insecure packages with -minimal impact to their dependents. - -.. warning:: - - The ``spack deprecate`` command is designed for use only in - extraordinary circumstances. This is a VERY big hammer to be used - with care. - -The ``spack deprecate`` command will remove one package and replace it -with another by replacing the deprecated package's prefix with a link -to the deprecator package's prefix. - -.. warning:: - - The ``spack deprecate`` command makes no promises about binary - compatibility. It is up to the user to ensure the deprecator is - suitable for the deprecated package. - -Spack tracks concrete deprecated specs and ensures that no future packages -concretize to a deprecated spec. - -The first spec given to the ``spack deprecate`` command is the package -to deprecate. It is an abstract spec that must describe a single -installed package. The second spec argument is the deprecator -spec. By default it must be an abstract spec that describes a single -installed package, but with the ``-i/--install-deprecator`` it can be -any abstract spec that Spack will install and then use as the -deprecator. The ``-I/--no-install-deprecator`` option will ensure -the default behavior. - -By default, ``spack deprecate`` will deprecate all dependencies of the -deprecated spec, replacing each by the dependency of the same name in -the deprecator spec. The ``-d/--dependencies`` option will ensure the -default, while the ``-D/--no-dependencies`` option will deprecate only -the root of the deprecate spec in favor of the root of the deprecator -spec. - -``spack deprecate`` can use symbolic links or hard links. The default -behavior is symbolic links, but the ``-l/--link-type`` flag can take -options ``hard`` or ``soft``. - ------------------------ -Verifying installations ------------------------ - -The ``spack verify`` command can be used to verify the validity of -Spack-installed packages any time after installation. - -At installation time, Spack creates a manifest of every file in the -installation prefix. For links, Spack tracks the mode, ownership, and -destination. For directories, Spack tracks the mode, and -ownership. For files, Spack tracks the mode, ownership, modification -time, hash, and size. The Spack verify command will check, for every -file in each package, whether any of those attributes have changed. It -will also check for newly added files or deleted files from the -installation prefix. Spack can either check all installed packages -using the `-a,--all` or accept specs listed on the command line to -verify. - -The ``spack verify`` command can also verify for individual files that -they haven't been altered since installation time. If the given file -is not in a Spack installation prefix, Spack will report that it is -not owned by any package. To check individual files instead of specs, -use the ``-f,--files`` option. - -Spack installation manifests are part of the tarball signed by Spack -for binary package distribution. When installed from a binary package, -Spack uses the packaged installation manifest instead of creating one -at install time. - -The ``spack verify`` command also accepts the ``-l,--local`` option to -check only local packages (as opposed to those used transparently from -``upstream`` spack instances) and the ``-j,--json`` option to output -machine-readable json data for any errors. ------------------------- Seeing installed packages @@ -676,6 +597,93 @@ structured the way you want: "hash": "zvaa4lhlhilypw5quj3akyd3apbq5gap" } + +------------------------ +Using installed packages +------------------------ + +There are several different ways to use Spack packages once you have +installed them. As you've seen, spack packages are installed into long +paths with hashes, and you need a way to get them into your path. The +easiest way is to use :ref:`spack load <cmd-spack-load>`, which is +described in the next section. + +Some more advanced ways to use Spack packages include: + +* :ref:`environments <environments>`, which you can use to bundle a + number of related packages to "activate" all at once, and +* :ref:`environment modules <modules>`, which are commonly used on + supercomputing clusters. Spack generates module files for every + installation automatically, and you can customize how this is done. + +.. _cmd-spack-load: + +^^^^^^^^^^^^^^^^^^^^^^^ +``spack load / unload`` +^^^^^^^^^^^^^^^^^^^^^^^ + +If you have :ref:`shell support <shell-support>` enabled you can use the +``spack load`` command to quickly get a package on your ``PATH``. + +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 load mpich %gcc@4.4.7 + $ which mpicc + ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc + +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 + + +""""""""""""""" +Ambiguous specs +""""""""""""""" + +If a spec used with load/unload or is ambiguous (i.e. more than one +installed package matches it), then Spack will warn you: + +.. code-block:: console + + $ spack load libelf + ==> Error: libelf matches multiple packages. + Matching packages: + qmm4kso libelf@0.8.13%gcc@4.4.7 arch=linux-debian7-x86_64 + cd2u6jt libelf@0.8.13%intel@15.0.0 arch=linux-debian7-x86_64 + Use a more specific spec + +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. If you want to be +*very* specific, you can load it by its hash. For example, to load the +first ``libelf`` above, you would run: + +.. code-block:: console + + $ spack load /qmm4kso + +We'll learn more about Spack's spec syntax in the next section. + + .. _sec-specs: -------------------- @@ -1234,6 +1242,88 @@ add a version specifier to the spec: Notice that the package versions that provide insufficient MPI versions are now filtered out. + +----------------------------- +Deprecating insecure packages +----------------------------- + +``spack deprecate`` allows for the removal of insecure packages with +minimal impact to their dependents. + +.. warning:: + + The ``spack deprecate`` command is designed for use only in + extraordinary circumstances. This is a VERY big hammer to be used + with care. + +The ``spack deprecate`` command will remove one package and replace it +with another by replacing the deprecated package's prefix with a link +to the deprecator package's prefix. + +.. warning:: + + The ``spack deprecate`` command makes no promises about binary + compatibility. It is up to the user to ensure the deprecator is + suitable for the deprecated package. + +Spack tracks concrete deprecated specs and ensures that no future packages +concretize to a deprecated spec. + +The first spec given to the ``spack deprecate`` command is the package +to deprecate. It is an abstract spec that must describe a single +installed package. The second spec argument is the deprecator +spec. By default it must be an abstract spec that describes a single +installed package, but with the ``-i/--install-deprecator`` it can be +any abstract spec that Spack will install and then use as the +deprecator. The ``-I/--no-install-deprecator`` option will ensure +the default behavior. + +By default, ``spack deprecate`` will deprecate all dependencies of the +deprecated spec, replacing each by the dependency of the same name in +the deprecator spec. The ``-d/--dependencies`` option will ensure the +default, while the ``-D/--no-dependencies`` option will deprecate only +the root of the deprecate spec in favor of the root of the deprecator +spec. + +``spack deprecate`` can use symbolic links or hard links. The default +behavior is symbolic links, but the ``-l/--link-type`` flag can take +options ``hard`` or ``soft``. + +----------------------- +Verifying installations +----------------------- + +The ``spack verify`` command can be used to verify the validity of +Spack-installed packages any time after installation. + +At installation time, Spack creates a manifest of every file in the +installation prefix. For links, Spack tracks the mode, ownership, and +destination. For directories, Spack tracks the mode, and +ownership. For files, Spack tracks the mode, ownership, modification +time, hash, and size. The Spack verify command will check, for every +file in each package, whether any of those attributes have changed. It +will also check for newly added files or deleted files from the +installation prefix. Spack can either check all installed packages +using the `-a,--all` or accept specs listed on the command line to +verify. + +The ``spack verify`` command can also verify for individual files that +they haven't been altered since installation time. If the given file +is not in a Spack installation prefix, Spack will report that it is +not owned by any package. To check individual files instead of specs, +use the ``-f,--files`` option. + +Spack installation manifests are part of the tarball signed by Spack +for binary package distribution. When installed from a binary package, +Spack uses the packaged installation manifest instead of creating one +at install time. + +The ``spack verify`` command also accepts the ``-l,--local`` option to +check only local packages (as opposed to those used transparently from +``upstream`` spack instances) and the ``-j,--json`` option to output +machine-readable json data for any errors. + + .. _extensions: --------------------------- diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst index 569e5b94d2..052a028045 100644 --- a/lib/spack/docs/getting_started.rst +++ b/lib/spack/docs/getting_started.rst @@ -44,50 +44,50 @@ Getting Spack is easy. You can clone it from the `github repository This will create a directory called ``spack``. -^^^^^^^^^^^^^^^^^^^^^^^^ -Add Spack to the Shell -^^^^^^^^^^^^^^^^^^^^^^^^ +.. _shell-support: -We'll assume that the full path to your downloaded Spack directory is -in the ``SPACK_ROOT`` environment variable. Add ``$SPACK_ROOT/bin`` -to your path and you're ready to go: +^^^^^^^^^^^^^ +Shell support +^^^^^^^^^^^^^ -.. code-block:: console +Once you have cloned Spack, we recommend sourcing the appropriate script +for your shell: - # For bash/zsh users - $ export SPACK_ROOT=/path/to/spack - $ export PATH=$SPACK_ROOT/bin:$PATH +.. code-block:: console - # For tsch/csh users - $ setenv SPACK_ROOT /path/to/spack - $ setenv PATH $SPACK_ROOT/bin:$PATH + # For bash/zsh/sh + $ . spack/share/spack/setup-env.sh - # For fish users - $ set -x SPACK_ROOT /path/to/spack - $ set -U fish_user_paths /path/to/spack $fish_user_paths + # For tcsh/csh + $ source spack/share/spack/setup-env.csh -.. code-block:: console + # For fish + $ . spack/share/spack/setup-env.fish - $ spack install libelf +That's it! You're ready to use Spack. -For a richer experience, use Spack's shell support: +Sourcing these files will put the ``spack`` command in your ``PATH``, set +up your ``MOUDLEPATH`` to use Spack's packages, and add other useful +shell integration for :ref:`certain commands <packaging-shell-support>`, +:ref:`environments <environments>`, and :ref:`modules <modules>`. For +``bash``, it also sets up tab completion. -.. code-block:: console +If you do not want to use Spack's shell support, you can always just run +the ``spack`` command directly from ``spack/bin/spack``. - # Note you must set SPACK_ROOT - # For bash/zsh users - $ . $SPACK_ROOT/share/spack/setup-env.sh +^^^^^^^^^^^^^^^^^^ +Check Installation +^^^^^^^^^^^^^^^^^^ - # For tcsh/csh users - $ source $SPACK_ROOT/share/spack/setup-env.csh +With Spack installed, you should be able to run some basic Spack +commands. For example: - # For fish users - $ source $SPACK_ROOT/share/spack/setup-env.fish +.. command-output:: spack spec netcdf-c -This automatically adds Spack to your ``PATH`` and allows the ``spack`` -command to be used to execute spack :ref:`commands <shell-support>` and -:ref:`useful packaging commands <packaging-shell-support>`. +In theory, Spack doesn't need any additional installation; just +download and run! But in real life, additional steps are usually +required before Spack can work in a practical sense. Read on... ^^^^^^^^^^^^^^^^^ Clean Environment @@ -103,17 +103,6 @@ environment*, especially for ``PATH``. Only software that comes with the system, or that you know you wish to use with Spack, should be included. This procedure will avoid many strange build errors. - -^^^^^^^^^^^^^^^^^^ -Check Installation -^^^^^^^^^^^^^^^^^^ - -With Spack installed, you should be able to run some basic Spack -commands. For example: - -.. command-output:: spack spec netcdf-c - - ^^^^^^^^^^^^^^^^^^^^^^^^^^ Optional: Alternate Prefix ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -132,15 +121,6 @@ copy of spack installs packages into its own ``$PREFIX/opt`` directory. -^^^^^^^^^^ -Next Steps -^^^^^^^^^^ - -In theory, Spack doesn't need any additional installation; just -download and run! But in real life, additional steps are usually -required before Spack can work in a practical sense. Read on... - - .. _compiler-config: ---------------------- diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst index 73047a7754..1d39f16b89 100644 --- a/lib/spack/docs/module_file_support.rst +++ b/lib/spack/docs/module_file_support.rst @@ -10,14 +10,16 @@ Modules ======= 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 integrates with `Environment Modules -<http://modules.sourceforge.net/>`_ and `LMod -<http://lmod.readthedocs.io/en/latest/>`_ by -providing post-install hooks that generate module files and commands to manipulate them. +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 integrates with `Environment Modules +<http://modules.sourceforge.net/>`_ and `LMod +<http://lmod.readthedocs.io/en/latest/>`_ by providing post-install hooks +that generate module files and commands to manipulate them. -.. _shell-support: +Modules are one of several ways you can use Spack packages. For other +options that may fit your use case better, you should also look at +:ref:`spack load <spack-load>` and :ref:`environments <environments>`. ---------------------------- Using module files via Spack @@ -60,206 +62,9 @@ to load the ``cmake`` module: $ module load cmake-3.7.2-gcc-6.3.0-fowuuby -Neither of these is particularly pretty, easy to remember, or -easy to type. Luckily, Spack has its own interface for using modules. - -^^^^^^^^^^^^^ -Shell support -^^^^^^^^^^^^^ - -To enable additional Spack commands for loading and unloading module files, -and to add the correct path to ``MODULEPATH``, you need to source the appropriate -setup file in the ``$SPACK_ROOT/share/spack`` directory. This will activate shell -support for the commands that need it. For ``bash``, ``ksh`` or ``zsh`` users: - -.. code-block:: console - - $ . ${SPACK_ROOT}/share/spack/setup-env.sh - -For ``csh`` and ``tcsh`` instead: - -.. code-block:: console - - $ set SPACK_ROOT ... - $ source $SPACK_ROOT/share/spack/setup-env.csh - -Note that in the latter case it is necessary to explicitly set ``SPACK_ROOT`` -before sourcing the setup file (you will get a meaningful error message -if you don't). - -If you want to have Spack's shell support available on the command line at -any login you can put this source line in one of the files that are sourced -at startup (like ``.profile``, ``.bashrc`` or ``.cshrc``). Be aware though -that the startup time may be slightly increased because of that. - - -.. _cmd-spack-load: - -^^^^^^^^^^^^^^^^^^^^^^^ -``spack load / unload`` -^^^^^^^^^^^^^^^^^^^^^^^ - -Once you have shell support enabled you can use the same spec syntax -you're used to 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 load mpich %gcc@4.4.7 - $ which mpicc - ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc - -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 - -.. note:: - - The ``load`` and ``unload`` subcommands are only available if you - have enabled Spack's shell support. These command DO NOT use the - underlying Spack-generated module files. - -^^^^^^^^^^^^^^^ -Ambiguous specs -^^^^^^^^^^^^^^^ - -If a spec used with load/unload or is ambiguous (i.e. more than one -installed package matches it), then Spack will warn you: - -.. code-block:: console - - $ spack load libelf - ==> Error: libelf matches multiple packages. - Matching packages: - 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 - Use a more specific spec - -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. - -.. _cmd-spack-module-loads: - -^^^^^^^^^^^^^^^^^^^^^^^^^^ -``spack module tcl loads`` -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In some cases, it is desirable to use a Spack-generated module, rather -than relying on Spack's built-in user-environment modification -capabilities. To translate a spec into a module name, use ``spack -module tcl loads`` or ``spack module lmod loads`` depending on the -module system desired. - - -To load not just a module, but also all the modules it depends on, use -the ``--dependencies`` option. 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 tcl loads --dependencies <spec> - -An equivalent alternative using `process substitution <http://tldp.org/LDP/abs/html/process-sub.html>`_ is: - -.. code-block :: console - - $ source <( spack module tcl loads --dependencies <spec> ) - - -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 ``--dependencies`` flag, -``spack module tcl loads`` may also be used to generate code that can be -cut-and-pasted into a shell script. For example: - -.. code-block:: console - - $ spack module tcl 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 tcl loads`` needs to know about that prefix when it -issues ``module load`` commands. Add the ``--prefix`` option to your -``spack module tcl 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 tcl 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 tcl 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 +Neither of these is particularly pretty, easy to remember, or easy to +type. Luckily, Spack offers many facilities for customizing the module +scheme used at your site. ------------------------- Module file customization @@ -697,3 +502,135 @@ subcommand is ``rm``: 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. + + +.. _modules-in-shell-scripts: + +------------------------------------ +Using Spack modules in shell scripts +------------------------------------ + +The easiest To enable additional Spack commands for loading and unloading +module files, and to add the correct path to ``MODULEPATH``, you need to +source the appropriate setup file. Assuming Spack is installed in +``$SPACK_ROOT``, run the appropriate command for your shell: + +. code-block:: console + + # For bash/zsh/sh + $ . $SPACK_ROOT/share/spack/setup-env.sh + + # For tcsh/csh + $ source $SPACK_ROOT/share/spack/setup-env.csh + + # For fish + $ . $SPACK_ROOT/share/spack/setup-env.fish + +If you want to have Spack's shell support available on the command line +at any login you can put this source line in one of the files that are +sourced at startup (like ``.profile``, ``.bashrc`` or ``.cshrc``). Be +aware that the shell startup time may increase slightly as a result. + +.. _cmd-spack-module-loads: + +^^^^^^^^^^^^^^^^^^^^^^^^^^ +``spack module tcl loads`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases, it is desirable to use a Spack-generated module, rather +than relying on Spack's built-in user-environment modification +capabilities. To translate a spec into a module name, use ``spack +module tcl loads`` or ``spack module lmod loads`` depending on the +module system desired. + + +To load not just a module, but also all the modules it depends on, use +the ``--dependencies`` option. 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 tcl loads --dependencies <spec> + +An equivalent alternative using `process substitution <http://tldp.org/LDP/abs/html/process-sub.html>`_ is: + +.. code-block:: console + + $ source <( spack module tcl loads --dependencies <spec> ) + + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 ``--dependencies`` flag, +``spack module tcl loads`` may also be used to generate code that can be +cut-and-pasted into a shell script. For example: + +.. code-block:: console + + $ spack module tcl 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 tcl loads`` needs to know about that prefix when it +issues ``module load`` commands. Add the ``--prefix`` option to your +``spack module tcl 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 tcl 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 tcl 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 |