Merge pull request #118 from hpcugent/develop

update docs to 20150430.01 (EasyBuild v2.1.0)

docs/Changelog.rst

@@ -3,6 +3,29 @@
 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`
+
+* **release 20150407.01** (`Apr 7th 2015`):
+
+  * add link to :ref:`unit_tests` page in dedicated section at :ref:`installation` page
+    (see :ref:`install_running_unit_tests`)
+  * clarify relation between ``--installpath``, ``--prefix``, ``-subdir-*`` and ``--installpath-*``
+    configuration options (see :ref:`installpath`)
+  * mention ``--show-default-configfiles`` command line option in relevant section
+    (see :ref:`default_configuration_files`)
+
 * **release 20150327.01** (`Mar 27th 2015`):
 
   * documented deprecated functionality w.r.t. error reporting (see :ref:`depr_error_reporting`)

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/Installation.rst

@@ -127,6 +127,8 @@ For example::
   may make a big difference, if you have installed both versions 1.9.0 and 1.15.2,
   with respect to what is the version being loaded by default.
 
+.. _install_running_unit_tests:
+
 Running unit tests
 ~~~~~~~~~~~~~~~~~~
 
@@ -135,6 +137,8 @@ After completion of the bootstrap procedure and loading the
 
     python -m test.framework.suite
 
+More details about the EasyBuild unit tests are available at :ref:`unit_tests`.
+
 If this does not complete successfully, `please open an issue`_ to report it.
 
 .. _please open an issue: https://github.com/hpcugent/easybuild-framework/issues/new

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".