summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/spack/docs/basic_usage.rst250
-rw-r--r--lib/spack/docs/getting_started.rst80
-rw-r--r--lib/spack/docs/module_file_support.rst351
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