diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/spack/docs/basic_usage.rst | 137 |
1 files changed, 92 insertions, 45 deletions
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst index ddf7109a40..0a0c2c678c 100644 --- a/lib/spack/docs/basic_usage.rst +++ b/lib/spack/docs/basic_usage.rst @@ -308,19 +308,19 @@ completely remove the directory in which the package was installed. spack uninstall mpich If there are still installed packages that depend on the package to be -uninstalled, spack will issue a warning. In general, it is safer to -remove dependent packages *before* removing their dependencies. Not -doing so risks breaking packages on your system. To remove a package -without regard for its dependencies, run ``spack uninstall -f -<package>`` to override the warning. +uninstalled, spack will refuse to uninstall. If you know what you're +doing, you can override this with ``spack uninstall -f <package>``. +However, running this risks breaking other installed packages. In +general, it is safer to remove dependent packages *before* removing +their dependencies. A line like ``spack uninstall mpich`` may be ambiguous, if multiple ``mpich`` configurations are installed. For example, if both ``mpich@3.0.2`` and ``mpich@3.1`` are installed, it could refer to either one, and Spack cannot determine which one to uninstall. Spack -will ask you to provide a version number to remove any ambiguity. For -example, ``spack uninstall mpich@3.1`` is unambiguous in the -above scenario. +will ask you to provide a version number to remove the ambiguity. For +example, ``spack uninstall mpich@3.1`` is unambiguous in the above +scenario. .. _sec-specs: @@ -641,35 +641,41 @@ versions are now filtered out. .. _shell-support: -Interactive Shell Support +Environment Modules ------------------------------- -Spack provides some limited shell support to make it easier to use the -packages it provides. You can enable shell support by sourcing some -files in the ``/share/spack`` directory. +.. note:: -For ``bash`` or ``ksh``, run:: + Environment module support is currently experimental and should not + be considered a stable feature of Spack. In particular, the + interface and/or generated module names may change in future + versions. + +Spack provides some limited integration with environment module +systems to make it easier to use the packages it provides. + +You can enable shell support by sourcing some files in the +``/share/spack`` directory. + +For ``bash`` or ``ksh``, run: + +.. code-block:: sh - . $SPACK_ROOT/share/spack/setup-env.sh + . $SPACK_ROOT/share/spack/setup-env.sh For ``csh`` and ``tcsh`` run: - setenv SPACK_ROOT /path/to/spack - source $SPACK_ROOT/share/spack/setup-env.csh +.. 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. -Environment Modules ------------------------------- -.. note:: - - Environment module support is currently experimental and should not - be considered a stable feature of Spack. In particular, the - interface and/or generated module names may change in future - versions. When you install a package with Spack, it automatically generates an environment module that lets you add the package to your environment. @@ -736,50 +742,63 @@ of installed packages. 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: +you could type either of these commands to load the callpath module +(assuming dotkit and modules are installed): .. code-block:: sh use callpath@1.0.1%gcc@4.4.7-5dce4318 - module load callpath@1.0.1%gcc@4.4.7-5dce4318 -And they would work fine. However, that is not particularly pretty, -easy to remember, or easy to type. +.. code-block:: sh + + module load callpath@1.0.1%gcc@4.4.7-5dce4318 -Luckily, Spack has its own interface for using modules and dotkits. -You can use the same spec syntax you're used to: +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: -Modules: - * ``spack load <spec>`` - * ``spack unload <spec>`` -Dotkit: - * ``spack use <spec>`` - * ``spack unuse <spec>`` + ========================= ========================== + Modules Dotkit + ========================= ========================== + ``spack load <spec>`` ``spack use <spec>`` + ``spack unload <spec>`` ``spack unuse <spec>`` + ========================= ========================== And you can use the same shortened names you use everywhere else in -Spack. For example: +Spack. For example, this will add the ``mpich`` package built with +``gcc`` to your path: .. code-block:: sh $ spack install mpich %gcc@4.4.7 + # ... wait for install ... - $ spack use mpich%gcc@4.4.7 + + $ spack use mpich %gcc@4.4.7 Prepending: mpich@3.0.4%gcc@4.4.7 (ok) $ which mpicc ~/src/spack/opt/chaos_5_x86_64_ib/gcc@4.4.7/mpich@3.0.4/bin/mpicc -Or, similarly with modules: +Or, similarly with modules, you could type: + +.. code-block:: sh + $ spack load mpich %gcc@4.4.7 -The generated files will add appropriate directories to you ``PATH``, -``MANPATH``, and ``LD_LIBRARY_PATH`` to assist you and other programs -with finding the libraries you've installed. +These commands will add appropriate directories to your ``PATH``, +``MANPATH``, and ``LD_LIBRARY_PATH``. When you no longer want to use +a package, you can type unload or unuse similarly: -You can unuse/unload packages similarly. +.. code-block:: sh + + $ spack unload mpich %gcc@4.4.7 # modules + $ spack unuse mpich %gcc@4.4.7 # dotkit -These commands are only available if you have enabled Spack's shell -support, but they allow you to use Spack's abbreviated names for -packages to get them into your environment. +.. 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 ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -806,6 +825,34 @@ used ``gcc``. You could therefore just type: To identify just the one built with the Intel compiler. + +Regenerating Module files +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Module and dotkit files are generated when packages are installed, and +are placed in the following directories under the Spack root: + + * ``$SPACK_ROOT/share/spack/modules`` + * ``$SPACK_ROOT/share/spack/dotkit`` + +Sometimes you may need to regenerate the modules files. For example, +if newer, fancier module support is added to Spack at some later date, +you may want to regenerate all the modules to take advantage of these +new features. + +``spack module refresh`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Running ``spack module refresh`` will remove the +``share/spack/modules`` and ``share/spack/dotkit`` directories, then +regenerate all module and dotkit files from scratch: + +.. code-block:: sh + + $ spack module refresh + ==> Regenerating tcl module files. + ==> Regenerating dotkit module files. + Getting Help ----------------------- |