Help/guide/tutorial/Miscellaneous Features.rst
Some features don't fit well or aren't important enough to receive attention in the main tutorial, but deserve mention. These exercises collect some of those features. They should be considered "bonuses".
There are many CMake features that are not covered by the tutorial, some of which are considered essential to the projects which use them. Others are in common use by packagers but see little discussion among software developers producing local builds.
This list is not an exhaustive discussion of what remains of CMake's capabilities. It may grow or shrink with time and relevance.
Exercise 1: Target Aliases ^^^^^^^^^^^^^^^^^^^^^^^^^^
This tutorial focuses on installing dependencies and consuming them from an install tree. It also recommends the use of package managers to facilitate this process. However, for a variety of reasons both historical and contemporary this is not always how CMake projects are consumed.
It is possible to vendor a dependency's source code entirely in a parent project
and consume it with :command:add_subdirectory. When performed, the target
names exposed are those used within the project, not those exported via
:command:install(EXPORT). The target names will not have the namespace string
that command prefixes to targets.
Some projects wish to support this workflow with an interface consistent with
the one presented to :command:find_package consumers. CMake supports this via
:command:add_library(ALIAS) and :command:add_executable(ALIAS).
.. code-block:: cmake
add_library(MyLib INTERFACE) add_library(MyProject::MyLib ALIAS MyLib)
Add a library alias for the MathFunctions library.
add_libraryTutorialProject/MathFunctions/CMakeLists.txtFor this step we will only be editing the TutorialProject project in the
Step11 folder. Complete TODO 1.
To build the project we first need configure and install SimpleTest.
Navigate to Help/guide/Step11/SimpleTest and run the appropriate commands.
.. code-block:: console
cmake --preset tutorial cmake --install build
Then navigate to Help/guide/Step11/TutorialProject and perform the usual build.
.. code-block:: console
cmake --preset tutorial cmake --build build
There should be no observable change in behavior from adding the alias.
We add a single line to the MathFunctions CML.
.. raw:: html
<details><summary>TODO 1 Click to show/hide answer</summary>.. literalinclude:: Complete/TutorialProject/MathFunctions/CMakeLists.txt :caption: TODO 1: TutorialProject/MathFunctions/CMakeLists.txt :name: TutorialProject/MathFunctions/CMakeLists.txt-alias :language: cmake :start-at: ALIAS :end-at: ALIAS
.. raw:: html
</details>Exercise 2: Generator Expressions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:manual:Generator expressions <cmake-generator-expressions(7)> are a
complicated domain-specific language supported in some contexts within CMake.
They are most easily understood as deferred-evaluation conditionals, they
express requirements where the inputs to determine the correct behavior are not
known during the CMake configuration stage.
.. note:: This is where generator expressions get their name, they are evaluated when the underlying build system is being generated.
Generator expressions were commonly used in combination with
:command:target_include_directories to express include directory requirements
across the build and install tree, but file sets have superseded this use case.
Their most common applications now are in multi-config generators and
intricate dependency injection systems.
.. code-block:: cmake
target_compile_definitions(MyApp PRIVATE "MYAPP_BUILD_CONFIG=$<CONFIG>")
Add a generator expression to SimpleTest that checks the build configuration
inside a compile definition.
target_compile_definitionscmake-generator-expressions(7)SimpleTest/CMakeLists.txtFor this step we will only be editing the SimpleTest project in the
Step11 folder. Complete TODO 2.
To build the project we first need configure and install SimpleTest.
Navigate to Help/guide/Step11/SimpleTest and run the appropriate commands.
.. code-block:: console
cmake --preset tutorial cmake --install build
Then navigate to Help/guide/Step11/TutorialProject and perform the usual build.
.. code-block:: console
cmake --preset tutorial cmake --build build
When running the TestMathFunctions binary directly, we should a message
naming the build configuration used to build the executable (not necessarily the
same as configuration used to configure SimpleTest). On single configuration
generators, the build configuration can be changed by setting
:variable:CMAKE_BUILD_TYPE.
We add a single line to the SimpleTest CML.
.. raw:: html
<details><summary>TODO 2 Click to show/hide answer</summary>.. literalinclude:: Complete/SimpleTest/CMakeLists.txt :caption: TODO 2: SimpleTest/CMakeLists.txt :name: SimpleTest/CMakeLists.txt-target_compile_definitions :language: cmake :start-at: target_compile_definitions :end-at: target_compile_definitions
.. raw:: html
</details>