Skip to content

Use environment variables to specify compiler preferences. - #5731

Merged
Regan Downer (v-regandowner) merged 3 commits into
MicrosoftDocs:mainfrom
crud89:cmake-presets-vs-compiler-selection
Sep 18, 2025
Merged

Regan Downer (v-regandowner) merged 3 commits into
MicrosoftDocs:mainfrom
crud89:cmake-presets-vs-compiler-selection

Conversation

@crud89

Copy link
Copy Markdown
Contributor

The documentation is using a problematic way to specify the compiler in a preset, namely by setting the CMAKE_<LANG>_COMPILER cache variables. This should be avoided, as it can cause problems with subsequent cache configuration runs. An example for where this becomes problematic is described here.

The CMake docs for those variables state:

This is the command that will be used as the compiler. Once set, you can not change this variable.

However, specifying a cache variable in a CMake preset will cause the variable to be reset with every subsequent cache configuration run. This usually results in a warning like the following:

You have changed variables that require your cache to be deleted.
Configure will be re-run and you may have to reset some variables.
The following variables have changed:
CMAKE_C_COMPILER= cl
CMAKE_CXX_COMPILER= cl

In the best case, this will simply delete and re-create the entire cache. In the worst case, however, this re-creation will cause problems as previously cached entries are reset. I frequently encountered this problem when resolving packages from vcpkg. The directories to the *Config.cmake files were removed during this process and the actual configuration step then failed because the package could no longer be resolved. This is the same problem as observed in the linked post above.

Instead of setting those cache variables directly, I've changed the documentation to use the CXX and CC environment variables. Those are used only during the initial cache configuration run to initialize the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER variables. This fixes the aforementioned issues in all projects, I've tested it.

The cache variables `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` must only be set during the initial cache creation. Specifying them in a preset will cause them to be reset during subsequent cache configurations, resulting in a cache invalidation, which can break the build. Using the `CC` and `CXX` environment variables to initialize those cache variables is the proper way to avoid this issue.
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 55088ae:

✅ Validation status: passed

File Status Preview URL Details
docs/build/cmake-presets-vs.md ✅Succeeded

For more details, please refer to the build report.

@v-dirichards

Diana Richards (v-dirichards) commented Sep 2, 2025

Copy link
Copy Markdown
Contributor

Tyler Whitney (@TylerMSFT)

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

@prmerger-automator prmerger-automator Bot added the aq-pr-triaged Tracking label for the PR review team label Sep 2, 2025
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit a78f16c:

✅ Validation status: passed

File Status Preview URL Details
docs/build/cmake-presets-vs.md ✅Succeeded

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 453dc40:

✅ Validation status: passed

File Status Preview URL Details
docs/build/cmake-presets-vs.md ✅Succeeded

For more details, please refer to the build report.

@TylerMSFT Tyler Whitney (TylerMSFT) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for improving the doc!

@TylerMSFT

Copy link
Copy Markdown
Collaborator

#sign-off

@v-regandowner
Regan Downer (v-regandowner) merged commit 42c515f into MicrosoftDocs:main Sep 18, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

aq-pr-triaged Tracking label for the PR review team ready-to-merge review-team-triage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants