docs: when to use CMakeToolchain's variable choices

[prince-chrismc]

Docs!

trying to capture #13794 (comment)

[prince-chrismc]

Just as a note the policies that are currently being set with cache variables will go away with the next client since there was a fix :)

[conan-center-bot]

Conan v1 pipeline

[jwillikers]

Great, thanks!

[uilianries]

LGTM

[conan-center-bot]

This PR has been triggered again because there are existing changes in master branch that are related to these same references resulting in different recipe-revisions. The build is being triggered on the PR context in case some additional fix is needed after merging those changes.

[SSE4]

should I check just project's root CMakeLists.txt, or all of them?

[prince-chrismc]

Depends on the project... I mean maybe if they have multiple layers with different options and multiple projects all being combined yeah you might possibly need to -- but I have not see that thankfully

[SSE4]

I am reading cmake doc:

In CMake there are two types of variables: normal variables and cache variables.
Normal variables are meant for the internal use of the script 
(just like variables in most programming languages); 
they are not persisted across CMake runs. 
Cache variables (unless set with INTERNAL) are mostly intended 
for configuration settings where the first CMake run determines 
a suitable default value, which the user can then override, 
by editing the cache with tools such as ccmake or cmake-gui.

so, non-cache variables are considered internal, and are not supposed to be modified from the outside.
given that, maybe it's a good practice to always set variables we use in conanfile as CACHE?
otherwise, it indicates we're trying to modify from the outside something that is not supposed to be modified that way. it may results in a logic errors in CMake script (like, variables may get contradictory values).

[prince-chrismc]

so, non-cache variables are considered internal, and are not supposed to be modified from the outside.
given that, maybe it's a good practice to always set variables we use in conanfile as CACHE?
otherwise, it indicates we're trying to modify from the outside something that is not supposed to be modified that way. it may results in a logic errors in CMake script (like, variables may get contradictory values).

The problem here is the language does not come from the variables but the present. So the meaning and invocation are different https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset

In conan toolchain lingo "cache variables are command line inputs" and "variables are value input before the project is loaded". Both are valid ways but has different magnitudes of importance. This is significant because if a human passes something at the command line - it should take precedence - they should be able to have the final say.

In the most general case, of course.

Hopefully that clears up things.

[SSE4]

so, non-cache variables are considered internal, and are not supposed to be modified from the outside.
given that, maybe it's a good practice to always set variables we use in conanfile as CACHE?
otherwise, it indicates we're trying to modify from the outside something that is not supposed to be modified that way. it may results in a logic errors in CMake script (like, variables may get contradictory values).

The problem here is the language does not come from the variables but the present. So the meaning and invocation are different https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset

In conan toolchain lingo "cache variables are command line inputs" and "variables are value input before the project is loaded". Both are valid ways but has different magnitudes of importance. This is significant because if a human passes something at the command line - it should take precedence - they should be able to have the final say.

In the most general case, of course.

Hopefully that clears up things.

maybe it deserves a better explanation in docs then. but we can add it later, if needed.

[uilianries]

LGTM