add --search-path-cpp-headers configuration option to control how EasyBuild sets paths to headers at build time

[lexming]

Partial fix for #3331

EasyBuild (at build time) currently handles paths to headers of dependencies provided by EB through CPPFLAGS. The result is that the compilation command gets additional options of the form -I/path/to/include explicitly pointing the compiler to places with extra headers.

The GCC prepocessor also supports the following environment variables that define the search paths for headers, which have lower precedence than -I command line options:

• CPATH
• C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH

(see https://gcc.gnu.org/onlinedocs/cpp/Environment-Variables.html#Environment-Variables-1)

This PR adds a new build option and toolchain option called cpp-headers-search-path to control how EasyBuild will handle paths to headers at build time:

• CPPFLAGS: current approach by setting CPPFLAGS and injecting -I/path/to/include to compilation command
• CPATH: new approach by adding paths to include directories to CPATH environment variable
• INCLUDE_PATHS: new approach by adding paths to include directories to C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH independently

Notes:

• all these options and environment variables are also supported by LLVM and the Intel compilers.
• option CPPFLAGS stays the default. So this PR does not change current behavior.
• the toolchain option has precedence over the build option as it is more specific and (probably) easyconfigs setting this option will not work with any other setting.
• FCC toolchain can now be drastically simplified by leveraging inheritance to the new Toolchain._add_dependency_cpp_headers() method (@migueldiascosta can you please check that this works on your side?)
• replaced hardcoded settings for LDFLAGS and CPPFLAGS with new Toolchain methods in ACML toolchain
• added unit test for cpp-headers-search-paths option

[Flamefire]

What about $INCLUDE for fortran modules? spack/spack#14749 (comment)

For Intel ifort the .mod file search path uses CPATH and INCLUDE

[lexming]

@Flamefire that's out of scope of this PR. This handles all supported options by CPP, which does not apply to Fortran. For Fortran we first need to check what is supported by the different Fortran preprocessors (gfortran for GNU and FPP for Intel) and probably it will need a different option in EB.

[lexming]

Actually, after checking the docs, it turns out that the Fortran compilers in both GNU and Intel do support the same environment variables defined by CPP. So this PR already applies to Fortran as well:

• gfortran uses the C prepocessor 🤷, see https://gcc.gnu.org/onlinedocs/gfortran/Preprocessing-Options.html
• Intel Fortran compiler only supports CPATH as search path of include directories in Linux environments, see https://www.intel.com/content/www/us/en/docs/fortran-compiler/developer-guide-reference/2024-2/supported-environment-variables.html ( ⚠️ INCLUDE is only supported on Windows )

[Flamefire]

Ok, I see. Only potential issue I see is that setting $CPATH here might make Intel-Fortran pick things up it didn't before.
But I guess that was already the case as we put the same paths in CPATH in the module files, don't we?

Also: How are existing entries handled? I.e. if CPATH=/folder1:/folder2 and adding both here (again) would they be duplicated? Would the order get changed?

Edit: That was supposed to be a reply to #4645 (comment) ;-)

[Flamefire]

Still some refinements of the new functions which I think are required to avoid subtile issues.

[Flamefire]

Looks good to me. One (very) minor suggestion where I'm not sure. See the comment.

[Micket]

Looks like @Flamefire is happy with it. I tested a couple of builds and it seems fine.