Toolchain File vs Environment Variables: Which Precedence Should CMake Use for Compiler Selection?

Short answer

Environment variables win over the toolchain file. When CMake populates the cache for the first time, it applies sources in this order: command-line -D definitions first, then environment variables such as CMAKE_C_COMPILER, then assignments inside the toolchain file, and finally its built-in compiler detection. Because a toolchain file is processed with set() semantics that do not overwrite an already-defined cache variable, its CMAKE_C_COMPILER/CMAKE_CXX_COMPILER assignments are silently ignored if the variable already came from the environment or the command line.

Confirmed behavior vs. caveats

The precedence order above is well-established and generator-independent: it happens during initial cache population, before any generator-specific logic runs, so Visual Studio, NMake Makefiles, and Ninja all see the same resolved values. Two caveats are worth flagging:

• Generator toolset overrides: the Visual Studio generator selects a platform toolset (e.g., v143) that can effectively pick a compiler version independent of CMAKE_CXX_COMPILER unless you also pass -T or set CMAKE_GENERATOR_TOOLSET. The precedence rule still holds, but the resulting compiler may not be the binary you named.
• Older CMake releases: in versions before roughly 3.15, the "don't overwrite an existing definition" check in toolchain processing was less strict, so an unconditional set(CMAKE_C_COMPILER ...) in a toolchain file could clobber the environment value. Pin a modern CMake (3.20+ is a safe baseline) in CI.

Verifying on your machine

Configure once with both mechanisms and inspect the cache:

cmake -S . -B build -G "NMake Makefiles" \
  -DCMAKE_TOOLCHAIN_FILE=mytoolchain.cmake
# with CMAKE_C_COMPILER set in the environment
grep CMAKE_C_COMPILER build/CMakeCache.txt

The cache entry should show the environment value, not the toolchain file's path. Repeat with -G "Visual Studio 17 2022"; the precedence pattern should be identical, though you should also confirm the selected toolset in the generated .vcxproj.

Deterministic CI recommendation

Do not rely on the precedence rule at all. Pick exactly one source of truth:

1. Pass the compilers explicitly on the command line (-DCMAKE_C_COMPILER=... -DCMAKE_CXX_COMPILER=...), which outranks everything, or put them only in the toolchain file and unset the environment variables in the CI job.
2. Always configure into a fresh build directory (or delete CMakeCache.txt); compiler variables are frozen in the cache after the first configure, so stale caches are the most common cause of "inconsistent outputs across generators."
3. In the toolchain file, guard assignments: if(NOT DEFINED CMAKE_C_COMPILER), so local overrides remain possible.

If you still see divergence after these steps, the missing diagnostic is the generator and CMake version pair where it happens — that combination determines whether a toolset override or an old-version quirk is responsible.