Advanced Customization
Beyond the configurations described in the Configuring CMake Templates section, you can provide some advanced configurations.
This section describes how you can include additional CMake files and custom template scripts.
Including Additional CMake Files
You can include machine and system custom CMake files and operating system custom CMake files.
Machine and System Custom CMake Files
Advanced configuration is possible by automatically including additional CMake files from specific locations. Following are the locations from which you can add CMake files. Inclusions occur in the order shown here:
-
<project-root-path>/conf.d/app-templates/cmake/cmake.d- normally located CMake project files -
$HOME/.config/app-templates/cmake.d- the home location -
/etc/app-templates/cmake.d- the system location
The CMake files you include must be named using either of the following conventions:
XX-common*.cmakeXX-${PROJECT_NAME}*.cmake
In both formats, XX are numbers and indicate the order in which the file
is included.
The * character represents the filename.
When naming the file, consider the projects in which the file needs to be
included.
If you want to include the file in all projects, use the keyword common.
If you want to include the file in a specific project, use the ${PROJECT_NAME}
value.
For example, if you want a CMake file whose name is my_custom_file
included first and you want it included in all projects, name the file
01-common-my_custom_file.cmake.
If you want the same file included in a single project defined by the
PROJECT_NAME variable, and you want it included after all other files,
name the file 99-${PROJECT_NAME}-my_custom_file.cmake.
When you include CMake files that use CMake variables, the values override variables with the same name. The exception to this rule is if you use a cached variable. Following is an example:
set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
In this example, the VARIABLE_NAME variable is defined as a cached
variable by using the CACHE keyword.
Consequently, VARIABLE_NAME does not get overridden as a result of
including a CMake file that sets the same variable.
Operating System Custom CMake Files
Including custom CMake files based on the operating system lets you personalize a project depending on the operating system you are using.
At the end of the config.cmake file common.cmake includes
CMake files to customize your project build depending on your platform.
The operating system is detected by using /etc/os-release,
which is the default method used in almost all Linux distributions.
Consequently, you can use the value of field ID_LIKE to
add a CMake file for that distribution.
The file comes from your conf.d/cmake/ directory or relatively
from your app-templates submodule path app-templates/../cmake/.
NOTE: If the ID_LIKE field does not exist, you can use the ID field.
Files that you add must be named according to the following file naming convention:
XX-${OSRELEASE}*.cmake
In the naming convention, XX represents numbers and is the order in which
you want a file included.
The ${OSRELEASE} value is taken from either the ID_LIKE or ID field
of the /etc/os-release file.
You can also configure a CMake file to be included in cases where no specific operating system can be found. To do so, name your CMake file as follows:
XX-default*.cmake
A good use case example for these two naming conventions is when you have
a several Linux distributions and all but one can use the same module.
For that case, name one CMake file using the ${OSRELEASE} value and
name the CMake file to be used with the other distributions using
the XX-default*.cmake method.
Including Custom Template Scripts
You can include your own custom template scripts that are passed to the
CMake command configure_file.
Just create your own script and place it in either of the following directories:
-
$HOME/.config/app-templates/scripts- the home location -
/etc/app-templates/scripts- the system location
Scripts only need to use the extension .in to be parsed and configured by
CMake.