diff --git a/docs/easybuild-v5/enhancements.md b/docs/easybuild-v5/enhancements.md index b265543401..3343ed1295 100644 --- a/docs/easybuild-v5/enhancements.md +++ b/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. ---