Merge pull request #307 from lexming/modextrapaths

update documentation of EasyBuild 5.0 with revamp of modextrapaths

Author: branfosj

docs/easybuild-v5/deprecated-functionality.md

@@ -18,6 +18,9 @@ Some functionality is being deprecated in EasyBuild v5.0, and will no longer be
 - [GC3Pie as job backend][gc3pie-job-backend]
 - [Using `optarch` value without leading dash][optarch-dash]
 - [`COMPILER*_FLAGS` attributes in `Compiler` class][compiler-constants]
+- [Easyconfig parameter `modextrapaths_append`][deprec_modextrapaths_append]
+- [Easyconfig parameter `allow_append_abs_path`][deprec_allow_append_abs]
+- [Easyconfig parameter `allow_prepend_abs_path`][deprec_allow_prepend_abs]
 
 If you trigger any deprecated functionality when using EasyBuild v5.0, a warning message will be printed.
 
@@ -126,3 +129,49 @@ The following checksum types are deprecated and should no longer be used: `md5`,
 ## `COMPILER*_FLAGS` attributes in `Compiler` class {: #compiler-constants }
 
 *(replaced by `Compiler.COMPILER*_OPTIONS`, more info soon)*
+
+---
+
+## Easyconfig parameter `modextrapaths_append` {: #deprec_modextrapaths_append }
+
+The functionality of `modextrapaths_append` is now implemented in
+`modextrapaths` through its `prepend` option:
+
+```python
+modextrapaths = {
+    'ENV_VAR_NAME': {
+        'paths': 'path/to/extra/subdir',
+        'prepend': False,
+    },
+}
+```
+
+---
+
+## Easyconfig parameter `allow_append_abs_path` {: #deprec_allow_append_abs }
+
+The functionality of `allow_append_abs_path` is now implemented in
+`modextrapaths`, which now accepts absolute paths by default and the position
+of paths can be controlled through its `prepend` option:
+
+```python
+modextrapaths = {
+    'ENV_VAR_NAME': {
+        'paths': '/absolute/path/to/extra/subdir',
+        'prepend': False,
+    },
+}
+```
+
+---
+
+## Easyconfig parameter `allow_prepend_abs_path` {: #deprec_allow_prepend_abs }
+
+The functionality of `allow_prepend_abs_path` is now implemented in
+`modextrapaths`, which now accepts absolute paths by default:
+
+```python
+modextrapaths = {
+    'ENV_VAR_NAME': '/absolute/path/to/extra/subdir',
+}
+```

docs/easybuild-v5/enhancements.md

@@ -20,6 +20,7 @@ Various significant enhancements are included in EasyBuild v5.0, including:
 - [Provide control over how EasyBuild specifies path to header files during installation (via `--search-path-cpp-headers`)][search-path-cpp-headers]
 - [Provide control over how EasyBuild specifies path to libraries during installation (via `--search-path-linker`)][search-path-linker]
 - [Support not using `$PYTHONPATH` to specify the location of installed Python packages (via `--prefer-python-search-path`)][PYTHONPATH-vs-EBPYTHONPREFIXES]
+- [Revamp of easyconfig parameter `modextrapaths`][modextrapaths-revamp]
 - [Detect Fortran `.mod` files in `GCCcore` installations][mod-files]
 - [Let `ConfigureMake` generic easyblock error out on unknown `configure` options][configuremake-unknown-configure-options]
 
@@ -292,6 +293,56 @@ This option is also available as easyconfig parameter
 
 ---
 
+## Revamp of easyconfig parameter `modextrapaths` { : #modextrapaths-revamp }
+
+The easyconfig parameter `modextrapaths` has become in EasyBuild 5.0 the only
+tool needed in easyconfigs to add extra search paths into the generated module
+file. The environment variables targeted in `modextrapaths` now can also be
+defined with a dictionary of options to fully control how their extra search
+paths will be added into the environment.
+
+```python
+modextrapaths = {
+    'ENV_VAR_NAME': 'extra/subdir',
+    'WEIRD_ENV_VAR': {
+        'paths': ['another/subdir1', 'another/subdir2'],
+        'delimiter': '+',
+        'prepend': False,
+    },
+}
+```
+
+The example above shows the standard definition of an environment variable
+`$ENV_VAR_NAME` that will get an extra path prepended to it. So the result in
+the environment once the module file is loaded will look like `$ENV_VAR_NAME =
+"/path/to/softwareroot/extra/subdir:/existing/path"`. On the other hand, the
+environment variable `$WEIRD_ENV_VAR` uses a custom delimiter `+` and its paths
+will be appended. So we can expect as result an environment variable that looks
+like `$WEIRD_ENV_VAR = "/existing/path+/path/to/softwareroot/another/subdir1+/path/to/softwareroot/another/subdir2"`.
+
+Complete list of options to `modextrapaths`:
+
+- `paths`: string with a single path or list of strings with multiple paths.
+  Paths are glob patterns and can be relative or absolute.
+- `delimiter`: character used as search path separator (default: `:`)
+- `prepend`: position of paths in the environment variable (default: `True`)
+- `var_type`: type of contents as defined in `easybuild.tools.modules.ModEnvVarType`
+  (default:`ModEnvVarType.PATH_WITH_FILES`)
+
+Another improvement in EasyBuild 5.0 is the addition of a global variable
+called `MODULE_LOAD_ENV_HEADERS` that can be used as a special key in
+`modextrapaths` to add extra search paths for headers according to [new option
+`--module-search-path-headers`][module-search-path-headers].
+
+The revamp of `modextrapaths` renders several easyconfig parameters obsolete,
+which have become deprecated in EasyBuild 5.0:
+
+- [`modextrapaths_append`][deprec_modextrapaths_append]
+- [`allow_append_abs_path`][deprec_allow_append_abs]
+- [`allow_prepend_abs_path`][deprec_allow_prepend_abs]
+
+---
+
 ## Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options { : #configuremake-unrecognized-configure-options }
 
 *(more info soon)*

docs/easybuild-v5/index.md

@@ -81,6 +81,7 @@ Various significant enhancements are included in EasyBuild v5.0, including:
 - [Provide control over how EasyBuild specifies path to header files during installation (via `--search-path-cpp-headers`)](enhancements.md#search-path-cpp-headers)
 - [Provide control over how EasyBuild specifies path to libraries during installation (via `--search-path-linker`)](enhancements.md#search-path-linker)
 - [Support not using `$PYTHONPATH` to specify the location of installed Python packages (via `--prefer-python-search-path`)](enhancements.md#PYTHONPATH-vs-EBPYTHONPREFIXES)
+- [Revamp of easyconfig parameter `modextrapaths`](enhancements.md#modextrapaths-revamp)
 - [Detect Fortran `.mod` files in `GCCcore` installations](enhancements.md#mod-files)
 - [Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options](enhancements.md#configuremake-unrecognized-configure-options)
 
@@ -131,6 +132,9 @@ Some functionality is being deprecated in EasyBuild v5.0, and is scheduled to be
 - [GC3Pie as job backend](deprecated-functionality.md#gc3pie-job-backend)
 - [Using `optarch` value without leading dash](deprecated-functionality.md#optarch-dash)
 - [`COMPILER*_FLAGS` attributes in `Compiler` class](deprecated-functionality.md#compiler-constants) (replaced with `COMPILER*_OPTIONS`)
+- [Easyconfig parameter `modextrapaths_append`](deprecated-functionality.md#deprec_modextrapaths_append) (integrated in `modextrapaths`)
+- [Easyconfig parameter `allow_append_abs_path`](deprecated-functionality.md#deprec_allow_append_abs) (integrated in `modextrapaths`)
+- [Easyconfig parameter `allow_prepend_abs_path`](deprecated-functionality.md#deprec_allow_prepend_abs) (integrated in `modextrapaths`)
 
 ---