From 5b070418e77d4f608ed8e55b4ea46be2fe0685e3 Mon Sep 17 00:00:00 2001
From: Glenn Johnson <glennpj@gmail.com>
Date: Wed, 12 Oct 2016 01:14:42 -0500
Subject: [PATCH] Documentation for modules configuration options (#1685)
This PR add documentation for the `suffixes` and `hash_length` options
for modules.yaml.
This resolves #1416.
---
lib/spack/docs/basic_usage.rst | 35 ++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index bbedfff3fc..306d64409d 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1333,6 +1333,41 @@ load two or more versions of the same software at the same time.
.. 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
^^^^^^^^^^^^^^^^^^^^^^^^^
--
GitLab