Merge pull request #117 from boegel/eb210

documentation updates for EasyBuild v2.1.0

docs/Changelog.rst

@@ -3,6 +3,16 @@
 Changelog for EasyBuild documentation
 -------------------------------------
 
+* **release 20150430.01** (`Apr 30th 2015`): updated documentation for EasyBuild v2.1.0
+
+  * also cover extensions in page on concepts and terminology (see :ref:`extensions`)
+  * add documentation on :ref:`partial_installations`, covering ``--stop``, ``--skip`` and ``--module-only``
+  * add documentation on :ref:`manipulating_dependencies`, covering ``--filter-deps`` and ``--hide-deps``
+  * document ``-module-syntax`` configuration option (see :ref:`module_syntax`)
+  * add note on detection of unknown ``$EASYBUILD``-prefixed environment variables (see :ref:`configuration_env_vars`)
+  * mention support for prepending/appending to ``--robot-paths`` (see :ref:`robot_search_path_prepend_append`)
+  * update release notes for EasyBuild v2.1.0 (see :ref:`release_notes`)
+
 * **release 20150425.01** (`Apr 25th 2015`):
 
   * add documentation on :ref:`using_external_modules`

docs/Concepts_and_Terminology.rst

@@ -153,3 +153,20 @@ Therefore, reproducing installations becomes trivial.
 
 EasyBuild version |version| includes support for over 511 different software packages,
 spread over 2800 easyconfig files describing distinct builds.
+
+.. _extensions:
+
+Extensions
+----------
+
+Some software packages support installing additional add-ons alongside the 'main' software, either in the same
+installation prefix, or in a separate location.
+
+In EasyBuild, we use the neutral term '**extensions**' to refer these add-ons.
+
+Well-known examples include:
+
+* Perl modules (http://www.cpan.org/modules/)
+* Python packages (https://pypi.python.org/pypi)
+* R libraries (http://cran.r-project.org/web/packages/)
+* Ruby gems (http://guides.rubygems.org/what-is-a-gem/)

docs/Configuration.rst

@@ -226,6 +226,8 @@ file. This can be used as an empty template configuration file:
     [basic]
     # Print build overview incl. dependencies (full paths) (def False)
 
+.. _configuration_env_vars:
+
 Environment variables
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -247,6 +249,8 @@ shown in the sections below.
 .. tip:: Any configuration option of EasyBuild which can be tuned by command line
   or via the configuration file, can also be tuned via a corresponding environment variable.
 
+.. note:: If any ``$EASYBUILD``-prefixed environment variables are defined that do not correspond to a known
+  configuration option, EasyBuild will report an error message and exit.
 
 Command line arguments
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -563,6 +567,8 @@ For example:
     $ export EASYBUILD_SUBDIR_SOFTWARE=installs
     $ eb --installpath=$HOME/easybuild --subdir-modules=module_files ...
 
+.. _modules_tool:
+
 Modules tool (``--modules-tool``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -608,3 +614,40 @@ For more details, see the dedicated page: https://github.com/hpcugent/easybuild/
 
 .. _`http://docs.python.org/2/library/configparser.html`: http://docs.python.org/2/library/configparser.html
 
+.. _module_syntax:
+
+Module files syntax (``--module-syntax``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*default*: ``Tcl``
+
+*supported since*: EasyBuild v2.1
+
+The syntax to use for generated module files can be specified using the ``--module-syntax`` configuration setting.
+
+Possible values are:
+
+* ``Lua``: generate module files in Lua syntax
+
+  * this requires the use of Lmod as a modules tool to consume the module files (see :ref:`modules_tool`)
+  * module file names will have the ``.lua`` extension
+
+* ``Tcl``: generate module files in Tcl syntax
+
+  * Tcl module files can be consumed by all supported modules tools
+  * module files will contain a header string ``#%Module`` indicating that they are composed in Tcl syntax
+
+.. note::
+  Lmod is able to deal with having module files in place in both Tcl and Lua syntax. When a module file in Lua
+  syntax (i.e., with a ``.lua`` file name extension) is available, a Tcl module file with the same name will be
+  ignored. The Tcl-based environment modules tool will simply ignore module files in Lua syntax, since they do not
+  contain the header string that is included in Tcl module files.
+
+.. note::
+  Using module files in Lua syntax has the advantage that Lmod does not need to translate from Lua to Tcl internally
+  when processing the module files, which benefits responsiveness of Lmod when used interactively by users. In terms
+  of Lmod-specific aspects of module files, the syntax of the module file does *not* matter; Lmod-specific statements
+  supported by EasyBuild can be included in Tcl module files as well, by guarding them by a condition that only
+  evaluates positively when Lmod is consuming the module file, i.e.
+  '``if { [ string match "*tcl2lua.tcl" $env(_) ] } { ... }``'. Only conditional load statements like
+  '``load(atleast("gcc","4.8"))``' can only be used in Lua module files.

docs/Manipulating_dependencies.rst

@@ -0,0 +1,75 @@
+.. _manipulating_dependencies:
+
+Manipulating dependencies
+=========================
+
+A couple of different ways are available to manipulate the list of dependencies that are specified for the software
+packages being installed.
+
+.. _filter_deps:
+
+Filtering out dependencies using ``--filter-deps``
+--------------------------------------------------
+
+To avoid that certain dependencies are being installed, a list of software names can be specified to ``--filter-deps``.
+Any time a dependency with a name from this list is specified, it will be simply filtered out by EasyBuild, and
+thus disregarded when resolving dependencies, loading modules for the dependencies in the build environment, and
+including '``module load``' statements in the generated module files.
+
+This can be useful when particular tools and libraries are already provided by OS packages (or in some other way),
+and should not be reinstalled as modules by EasyBuild.
+
+For example:
+
+* overview of dependencies of HDF5::
+
+    $ eb HDF5-1.8.13-intel-2015a.eb -D
+     ...
+     * [ ] $CFGS/i/intel/intel-2015a.eb (module: intel/2015a)
+     * [ ] $CFGS/z/zlib/zlib-1.2.8-intel-2015a.eb (module: zlib/1.2.8-intel-2015a)   
+     * [ ] $CFGS/s/Szip/Szip-2.1-intel-2015a.eb (module: Szip/2.1-intel-2015a)
+     * [ ] $CFGS/h/HDF5/HDF5-1.8.13-intel-2015a.eb (module: HDF5/1.8.13-intel-2015a)
+
+* overview of dependencies of HDF5, with zlib and Szip excluded::
+
+    $ eb HDF5-1.8.13-intel-2015a.eb --filter-deps=zlib,Szip -D 
+     ... 
+     * [ ] $CFGS/i/intel/intel-2015a.eb (module: intel/2015a)
+     * [ ] $CFGS/h/HDF5/HDF5-1.8.13-intel-2015a.eb (module: HDF5/1.8.13-intel-2015a)
+
+
+.. _hide_deps:
+
+Installing dependencies as hidden modules using ``--hide-deps``
+---------------------------------------------------------------
+
+Selected software packages can be marked to be installed as hidden modules (i.e., modules that are not visible via
+'``module avail``', but can be loaded) whenever they are included as a dependency, via the ``--hide-deps``
+configuration option.
+
+For example (note the preceding '``.``' in the last part of the module names for zlib and Szip)::
+
+ $ eb HDF5-1.8.13-intel-2015a.eb --hide-deps=zlib,Szip -D
+  ...
+  * [ ] $CFGS/i/intel/intel-2015a.eb (module: intel/2015a)
+  * [ ] $CFGS/z/zlib/zlib-1.2.8-intel-2015a.eb (module: zlib/.1.2.8-intel-2015a)
+  * [ ] $CFGS/s/Szip/Szip-2.1-intel-2015a.eb (module: Szip/.2.1-intel-2015a)
+  * [ ] $CFGS/h/HDF5/HDF5-1.8.13-intel-2015a.eb (module: HDF5/1.8.13-intel-2015a)
+
+.. note::
+  Using Lmod (version >= 5.7.5), hidden modules can be made visible in the output of '``module avail``' using the
+  ``--show-hidden`` option.
+
+  For example::
+
+   $ module avail bzip2
+
+   Use "module spider" to find all possible modules.
+   Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".
+
+   $ module --show-hidden avail bzip2
+   ----- /home/example/.local/easybuild/modules/all -----
+   bzip2/.1.0.6
+
+   Use "module spider" to find all possible modules.
+   Use "module keyword key1 key2 ..." to search for all possible modules matching any of the "keys".