为何CMake不遵循LIBRARY_PATH与CPATH环境变量？

Let's break this down into two clear parts: why CMake behaves this way, and whether manually adding these paths makes sense for your HPC workflow.

Why CMake Doesn’t Auto-Include LIBRARY_PATH/CPATH in System Paths #

CMake’s core design is built around build reproducibility—it wants your CMakeLists.txt to work consistently across different environments, not just your current HPC session. Here are the key reasons behind this choice:

• Separation of compiler vs. CMake logic: LIBRARY_PATH and CPATH are compiler-specific environment variables (used by gcc, clang, etc. to locate headers/libraries during compilation). CMake doesn’t rely on these for its own find_package() or find_library()/find_path() calls because those are part of CMake’s independent lookup system. The compiler will still see these variables when CMake invokes it, but CMake’s search logic intentionally doesn’t inherit them by default.

• Avoiding transient session dependencies: HPC modules are per-user, per-session settings. If CMake automatically pulled in these paths, your build script might fail when run in a different module environment (or on a machine without those modules loaded). CMake prioritizes explicit, script-defined paths over temporary environment variables to ensure builds are portable.

• System vs. user path distinction: CMAKE_SYSTEM_INCLUDE_PATH and CMAKE_SYSTEM_LIBRARY_PATH are reserved for system-wide installed libraries/headers (like those in /usr/include or /usr/lib). HPC modules typically install software in module-specific or user-managed directories, which aren’t "system" paths in CMake’s eyes. Mixing them could lead to unexpected priority issues—for example, a module library overriding a system library unintentionally.

Is Manually Appending These Paths Reasonable? #

Yes—but with careful consideration. In HPC environments where modules are the standard way to manage dependencies, manually adding CPATH/LIBRARY_PATH to CMake’s search paths is a common and pragmatic approach. However, you should choose the right CMake variables to append to:

Recommended Approach: Use CMAKE_INCLUDE_PATH/CMAKE_LIBRARY_PATH #

Instead of modifying the SYSTEM variables, append to CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH. These are CMake’s dedicated variables for user-provided search paths, and they’re respected by find_path()/find_library() and find_package() (especially Config-mode searches that check these paths).

Add this snippet to the top of your CMakeLists.txt:

# Add CPATH entries to CMake's include search paths
if(DEFINED ENV{CPATH})
  string(REPLACE ":" ";" CPATH_DIRS "$ENV{CPATH}")
  list(APPEND CMAKE_INCLUDE_PATH ${CPATH_DIRS})
endif()

# Add LIBRARY_PATH entries to CMake's library search paths
if(DEFINED ENV{LIBRARY_PATH})
  string(REPLACE ":" ";" LIBRARY_PATH_DIRS "$ENV{LIBRARY_PATH}")
  list(APPEND CMAKE_LIBRARY_PATH ${LIBRARY_PATH_DIRS})
endif()

When to Use CMAKE_SYSTEM_* Paths? #

Only do this if the modules you’re loading provide libraries that are effectively system-wide for your HPC cluster (e.g., a cluster-wide MPI installation managed via modules). Modifying the system variables will give these paths higher priority in CMake’s search order, which might be desirable if you want to ensure module libraries are picked over local user installations. But be cautious—this can make your build less portable if moved to a cluster with different module setups.

Alternative: Use CMAKE_PREFIX_PATH #

If your HPC modules set CMAKE_PREFIX_PATH (some do this explicitly), that’s even better. CMAKE_PREFIX_PATH is CMake’s primary variable for specifying prefix directories where libraries/headers are installed, and find_package() will automatically check these paths for config files like <PackageName>Config.cmake.

One Quick Note #

Remember that even if you don’t add these paths to CMake’s variables, the compiler will still use CPATH and LIBRARY_PATH when compiling your code. The problem only arises when using CMake’s find_* commands, which rely on CMake’s own search logic. So if you’re directly including headers or linking libraries without find_package(), you might not even need to modify CMake’s paths—though using find_package() is still recommended for robustness.

内容的提问来源于stack exchange，提问作者Flamefire