document support for creating module 'wrappers' for dependencies

docs/Changelog.rst

@@ -5,6 +5,7 @@ Changelog for EasyBuild documentation
 
 (for EasyBuild release notes, see :ref:`release_notes`)
 
+* **release 20180921.01** (`Sep 21st 2018`): document support for wrapping dependencies (see :ref:`wrapping_dependencies`)
 * **release 20180920.01** (`Sep 20th 2018`): document support for downloading sources directly from a Git repository (see :ref:`common_easyconfig_param_sources_git_config`)
 * **release 20180711.01** (`Jul 11th 2018`): update release notes for EasyBuild v3.6.2 (see :ref:`release_notes_eb362`)
 * **release 20180710.01** (`Jul 10th 2018`): add definitions for ``2018b`` common toolchains (see :ref:`common_toolchains`)

docs/Wrapping_dependencies.rst

@@ -0,0 +1,42 @@
+.. _wrapping_dependencies:
+
+Wrapping dependencies
+=====================
+
+Since EasyBuild v3.7.0 a special-purpose generic easyblock named ``ModuleRC`` is available,
+which can be used to generate a (software-specific) ``.modulerc`` file
+(as opposed to generating an actual module file).
+
+.. note:: For compatibility with the different modules tools supported by EasyBuild (see :ref:`modules_tool`),
+          the ``.modulerc`` file is always generated in Tcl syntax (for now), regardless of the module syntax
+          that is used for module files. Only Lmod 7.8 or more recent supports ``.modulerc.lua`` files
+          in Lua syntax.
+
+The ``ModuleRC`` easyblock supports including ``module-version`` in the generated ``.modulerc`` file,
+which defines a so-called *"symbolic version"*.
+
+This can be used to install a *"wrapper"* for a particular module, which can be useful in the context
+of dependencies. For example, it can be used to avoid dependending on a specific version of
+a particular software package by specifying the dependency only on the ``<major>.<minor>`` version instead
+(i.e., without including the "subminor" version, which usually corresponds to a bugfix release).
+
+One particular example where this is employed is for ``Java``. Since the ``2018b`` generation of
+the :ref:`common_toolchains`, we use a wrapper for ``Java`` (e.g., ``Java/1.8``), rather than
+depending on a specific version (e.g., ``Java/1.8.0_181``):
+
+.. code::
+
+  # specify dependency on Java/1.8 "wrapper", rather than a specific Java version
+  dependencies = [('Java', '1.8', '', True)]
+
+This has a couple of advantages:
+
+* it helps with avoiding version conflicts on the ``Java`` dependency used by two (or more) otherwise independent
+  module files;
+
+* it allows to perform an in-place update of the ``Java`` wrapper to a more recent ``Java`` (bugfix) release
+  in the blink of an eye, since it only involves re-generating a ``.modulerc`` file (as opposed to performing
+  actual installation and generating a module file); in addition, it doesn't require updating/re-generating existing
+  module files that depend on the ``Java`` wrapper (since the version of the wrapper does not change)
+
+Since ``ModuleRC`` is a generic easyblock , it can also be employed to install module "wrappers" for dependencies.

docs/conf.py

@@ -43,7 +43,7 @@
 # The short X.Y version.
 version = '3.7.0dev'  # this is meant to reference the version of EasyBuild
 # The full version, including alpha/beta/rc tags.
-release = '20180920'  # this is meant to reference the version of the documentation itself
+release = '20180921'  # this is meant to reference the version of the documentation itself
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/index.rst

@@ -57,9 +57,11 @@ Advanced usage topics
     Archived-easyconfigs
     Backup_modules
     Common-toolchains
+    Containers
     Contributing
     Controlling_compiler_optimization_flags
     Cray-support
+    Detecting_loaded_modules
     Experimental_features
     Extended_dry_run
     Hooks
@@ -70,11 +72,10 @@ Advanced usage topics
     Packaging_support
     Partial_installations
     RPATH-support
-    Containers
     Submitting_jobs
     Tracing_progress
     Using_external_modules
-    Detecting_loaded_modules
+    Wrapping_dependencies
 
 Other topics
 ============