There is no official documentation about this specific internal work of CMake, so please find below a summary of what I have learned about CMake so far ...
Which files are processed depends on
- Host and Target Operating System
- Target compiler
- Your computer environment (variables, registry, installed software)
- Your project CMake script files that may include
- Your toolchain file
- Selected Programming Languages
- Any external projects / libraries / files / scripts
There are many possible combinations of these parameters, but most of the time CMake does everything possible to automatically determine the correct settings for you, and you do not need to worry about how to do this. The good news is - when you need to know - this follows some internal patterns.
Interestingly, it only slightly depends on the CMake generator you choose.
Initial Step: Detecting and Verifying the Compiler
This basically starts with the project() command. As an example, for example, for the CXX language, the main files for detecting the compiler (see also root files in the output of the question):
share/cmake-xy/Modules/CMakeDetermineCXXCompiler.cmake
This basically tries to determine the compiler's executable location and calls it to get a more specific compiler identifier.
In addition, it, for example, determines the extensions of the source / output file based on the host computer environment and the target operating system.
share/cmake-xy/Modules/CMakeCXXCompiler.cmake.in
This is the template for storing the result of compiler detection in ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/xyz/CMakeCXXCompiler.cmake .
These variables are CMAKE_CXX_COMPILER , CMAKE_CXX_SOURCE_FILE_EXTENSIONS , CMAKE_CXX_IGNORE_EXTENSIONS and CMAKE_CXX_COMPILER_ENV_VAR
share/cmake-xy/Modules/CMakeCXXInformation.cmake
This file sets the base flags for the compiler. This is also when the compiler, host, and target have the greatest impact on tuning with these calls:
include(Platform/${CMAKE_SYSTEM_NAME}-${CMAKE_CXX_COMPILER_ID}-CXX-${CMAKE_SYSTEM_PROCESSOR} OPTIONAL) include(Platform/${CMAKE_SYSTEM_NAME}-${CMAKE_CXX_COMPILER_ID}-CXX OPTIONAL) include(Platform/${CMAKE_SYSTEM_NAME}-${CMAKE_BASE_NAME} OPTIONAL) include(Platform/${CMAKE_SYSTEM_NAME} OPTIONAL)
share/cmake-xy/Modules/CMakeTestCXXCompiler.cmake
This checks everything, etc. define compiler functions by actually invoking the compiler in simple generated CMake projects.
The results of these steps are stored in cached variables, and these files are special, in which case they are protected by variables such as CMAKE_CXX_COMPILER_LOADED , CMAKE_CXX_INFORMATION_LOADED or CMAKE_CXX_COMPILER_WORKS , so as not to run with each subsequent CMake configuration step again.
Project configuration files: change the default values
There are several ways to change CMake defaults without touching the CMakeLists.txt project CMakeLists.txt .
-C <initial-cache> command line option
This can be used if you want to specify some predefined values (usually you provide using the -D ... option) across several projects over and over again. Like some ways to search for libraries on your computer or some presets used by your company.
CMakeCache.txt via e.g. cmake-gui
cmake-gui allows you to manually change the parameters of your project (edit all non-internal variables in CMakeCache.txt ) before you finally create the build environment.
CMAKE_TOOLCHAIN_FILE
It is mainly used for cross-compiling , but it can more broadly be described as setpoints for the compiler toolkit used.
PreLoad.cmake
More or less the same as the "initial cache" option (see above), but it is not provided through the command line parameter. It should only be in the same directory as your CMakeLists.txt project.
Note. It supports all CMake script commands, such as if() , but PreLoad.cmake has
- own range of variables (all that are not cached here do not appear in your main
CMakeLists.txt ) - restrictions that are already known (it works to the rest, so basically you can check
CMAKE_GENERATOR )
CMAKE_USER_MAKE_RULES_OVERRIDE , CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
This allows you to change the immutable default values after automatic detection using CMake.
Example : Extending valid CXX source file extensions with .c files
MakeRulesOverwrite.cmake
list(APPEND CMAKE_CXX_SOURCE_FILE_EXTENSIONS c)
Then you can invoke cmake with something like
> cmake -D CMAKE_USER_MAKE_RULES_OVERRIDE:PATH=..\MakeRulesOverwrite.cmake ..
CMAKE_PROJECT_ParserTest_INCLUDE
This is intended to "introduce custom code into the project assembly without changing its source" immediately after your project() command has been processed (and the assembly environment has been detected).
Toolchain.cmake: parsed several times
A toolchain file is read several times when defining a system, compiler, etc.
It's important to know:
It is read with every call to try_compile() . And since the try compile needs to create a valid executable, you might need - if you, for example, cross-compiling - before
If you modify the tool binding file, CMake will rerun compiler detection (as in the previous line). Which deeply helps to play with your compiler settings.
CMake readaptations: everything comes from the cache
And last, but not least, it is important to know that the above trace shows only the initial step. All consecutive project configurations will occupy almost everything, starting with cached variables and, therefore, will read much fewer files during reconfiguration.
References
Florian Dec 21 '16 at 21:32 2016-12-21 21:32
source share