Merge pull request #301 from lexming/cpath-opts

add documentation about new search path options in EasyBuild 5.0

Author: branfosj

docs/easybuild-v5/enhancements.md

@@ -117,19 +117,123 @@ See [separate dedicated section](../implementing-easyblocks.md#module_load_envir
 
 ## Provide control over how generated modules update search path for header files (via `--module-search-path-headers`) { : #module-search-path-headers }
 
-*(more info soon)*
+EasyBuild 5.0 introduces a new option called `--module-search-path-headers`.
+This option can be used to select which environment variables will be injected
+in modules generated by EasyBuild to define search paths to C/C++ header files
+or Fortran MOD files, which are commonly found in `include` directories.
+
+Available settings follow what is supported by current versions of C/C++ and
+Fortran compilers from GNU and Intel, which all support the
+[environment variables defined by GNU C Pre-Processor](https://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html):
+
+- `cpath` (default): This is the traditional mode of operation of EasyBuild.
+Module files generated by EasyBuild 5.0 continue to prepend search paths to
+headers to the `CPATH` environment variable by default. The `CPATH` environment
+variable has a high precedence, only surpassed by explicit `-I` options in the
+compilation command. 
+
+- `include_paths`: Module files generated by EasyBuild 5.0 will prepend search
+paths to headers to the environment variables `C_INCLUDE_PATH`,
+`CPLUS_INCLUDE_PATH` and `OBJC_INCLUDE_PATH`. These three environment variables
+have lower precedence than `CPATH` and the paths defined in the option
+`-isystem`. Therefore, this setting is useful for software providing include
+folders that could collide with those from other loaded modules.
+
+This option is also available as easyconfig parameter
+`module_search_path_headers`. Which has precedence over the global
+`--module-search-path-headers` build option.
+
+The Easyconfig parameter `modextrapaths` has a new special key called
+`MODULE_LOAD_ENV_HEADERS` that allows to add search paths in the generated
+module according to `--module-search-path-headers`.
+
+```python
+modextrapaths = {
+    MODULE_LOAD_ENV_HEADERS: 'include/extra_dir',
+}
+```
+
+Adding search paths explicitly to `CPATH` or any other environment variable by
+name continues to work as usual in EasyBuild 5.0.
 
 ---
 
 ## Provide control over how EasyBuild specifies path to header files during installation (via `--search-path-cpp-headers`) { : #search-path-cpp-headers}
 
-*(more info soon)*
+EasyBuild 5.0 introduces a new option called `--search-path-cpp-headers`
+that controls the method used at build time to pass search paths to `include`
+directories to the compiler.
+
+Available settings follow what is supported by current versions of C/C++ and
+Fortran compilers from GNU and Intel, which all support the
+[environment variables defined by GNU C Pre-Processor](https://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html):
+
+- `flags` (default): EasyBuild sets the environment variable `CPPFLAGS` in the
+build environment with the list of paths to include directories as `-I`
+options. Passing search paths through `CPPFLAGS` has the highest precedence as
+[GNU Make](https://www.gnu.org/software/make/) will inject its contents
+directly in the preprocessor and compiler commands. Hence, this method
+minimizes the risk that the build process could be perturbed by the environment
+of the host system. This is the traditional mode of operation of EasyBuild.
+
+- `cpath`: EasyBuild adds search paths to `include` directories to the
+environment variable `CPATH` in the build environment. This option has less
+precedence than the `-I` options injected by `flags`, but still has more
+precedence than any other option.
+
+- `include_paths`: EasyBuild adds search paths to `include` directories to the
+environment variables `C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH` and
+`OBJC_INCLUDE_PATH` in the build environment. These three environment variables
+have lower precedence than the `-I` options or `CPATH`. Therefore, this setting
+is advisable for builds needing minor perturbations to their own build settings
+and those defined by the loaded modules.
+
+Search paths added by EasyBuild at build time are independent to those that
+might be defined by the modules of loaded dependencies. EasyBuild will generate
+a new list of search paths from scratch to existing include directories in
+installations of loaded dependencies. This approach improves the resilience of
+the build by detaching the build process from modifications done by modules to
+the environment. Nonetheless, changes to the environment made by loaded modules
+still come into play, but with less precedence by default.
+
+This option is also available as easyconfig parameter
+`search_path_cpp_headers`. Which has precedence over the global
+`--search-path-cpp-headers` build option.
 
 ---
 
 ## Provide control over how EasyBuild specifies path to libraries during installation (via `--search-path-linker`) { : #search-path-linker }
 
-*(more info soon)*
+EasyBuild 5.0 introduces a new option called `--search-path-linker`
+that controls the method used at build time to pass search paths to libraries
+to the linker.
+
+Available settings:
+
+- `flags` (default): EasyBuild sets the environment variable `LDFLAGS` in the
+build environment with the list of search paths to libraries as `-L` options.
+Passing search paths through `LDFLAGS` has the highest precedence as
+[GNU Make](https://www.gnu.org/software/make/) will inject its contents
+directly in the linker and compiler commands. Hence, this method
+minimizes the risk that the build process could be perturbed by the environment
+of the host system. This is the traditional mode of operation of EasyBuild.
+
+- `cpath`: EasyBuild adds search paths to libraries to the environment variable
+[LIBRARY_PATH](https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html#index-LIBRARY_005fPATH)
+in the build environment. This option has less precedence than the `-L` options
+injected by `flags`.
+
+Search paths added by EasyBuild at build time are independent to those that
+might be defined by the modules of loaded dependencies. EasyBuild will generate
+a new list of search paths from scratch to existing library sub-directories in
+installations of loaded dependencies. This approach improves the resilience of
+the build by detaching the build process from modifications done by modules to
+the environment. Nonetheless, changes to the environment made by loaded modules
+still come into play, but with less precedence by default.
+
+This option is also available as easyconfig parameter
+`search_path_linker`. Which has precedence over the global
+`--search-path-linker` build option.
 
 ---