diff options
Diffstat (limited to 'lib/spack/docs/module_file_support.rst')
| -rw-r--r-- | lib/spack/docs/module_file_support.rst | 89 |
1 files changed, 53 insertions, 36 deletions
diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst index 502152bc73..19a8161477 100644 --- a/lib/spack/docs/module_file_support.rst +++ b/lib/spack/docs/module_file_support.rst @@ -1,6 +1,8 @@ -=============================== -Integration with module systems -=============================== +.. _modules: + +===================================== +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 @@ -106,6 +108,12 @@ you could type either of these commands to load the callpath module: $ module load callpath@1.0.1%gcc@4.4.7-5dce4318 +.. _cmd-spack-load: + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``spack load / unload`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 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: @@ -153,9 +161,9 @@ want to use a package, you can type unload or unuse similarly: 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: @@ -181,9 +189,11 @@ To identify just the one built with the Intel compiler. .. _extensions: ----------------------- +.. _cmd-spack-module-loads: + +^^^^^^^^^^^^^^^^^^^^^^ ``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 @@ -284,9 +294,9 @@ For example, consider the following on one system: # 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 -======================= +----------------------------- +Auto-generating Module Files +----------------------------- Module files are generated by post-install hooks after the successful installation of a package. They are placed in the following directories @@ -314,9 +324,9 @@ The former method fits best cases that are site independent, e.g. injecting vari 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 --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``Package`` file 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: @@ -364,9 +374,11 @@ and has similar effects on module file of dependees. Even in this case .. literalinclude:: ../../../var/spack/repos/builtin/packages/R/package.py :lines: 128-129,146-151 ------------------------------- -Configuration file for modules ------------------------------- +.. _modules-yaml: + +---------------------------------- +Configuration in ``modules.yaml`` +---------------------------------- The name of the configuration file that controls module generation behavior is ``modules.yaml``. The default configuration: @@ -597,8 +609,9 @@ 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``: +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 @@ -607,20 +620,20 @@ This may be the case for Python extensions, if not activated using ``spack activ ^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``. +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`` + 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 -======================== +------------------------ +Maintaining Module Files +------------------------ 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 @@ -629,12 +642,14 @@ This tool is the ``spack module`` command: .. command-output:: spack module --help ------------------------- +.. _cmd-spack-module-refresh: + +^^^^^^^^^^^^^^^^^^^^^^^^ ``spack module refresh`` ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ -The command that regenerates module files to update their content or their layout -is ``module refresh``: +The command that regenerates module files to update their content or +their layout is ``module refresh``: .. command-output:: spack module refresh --help @@ -643,9 +658,11 @@ A set of packages can be selected using anonymous specs for the optional the type of module files to refresh. Optionally the entire tree can be deleted before regeneration if the change in layout is radical. -------------------- +.. _cmd-spack-module-rm: + +^^^^^^^^^^^^^^^^^^^^^^^^ ``spack module rm`` -------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ If instead what you need is just to delete a few module files, then the right command is ``module rm``: @@ -653,7 +670,7 @@ 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. + 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. |