diff --git a/docs/Changelog.rst b/docs/Changelog.rst index 821054a1..41390767 100644 --- a/docs/Changelog.rst +++ b/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`) diff --git a/docs/Wrapping_dependencies.rst b/docs/Wrapping_dependencies.rst new file mode 100644 index 00000000..369cec75 --- /dev/null +++ b/docs/Wrapping_dependencies.rst @@ -0,0 +1,43 @@ +.. _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 later) 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 depending on a specific version of +a particular software package by specifying the dependency only on the ``.`` 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 +other than ``Java``. diff --git a/docs/conf.py b/docs/conf.py index 861a0462..1488d026 100644 --- a/docs/conf.py +++ b/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: diff --git a/docs/index.rst b/docs/index.rst index 8cb46213..0412df50 100644 --- a/docs/index.rst +++ b/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 ============