docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md

   1 ---
   2 title: Advanced Customization
   3 ---
   4
   5 This section describes how you can include additional CMake files
   6 and custom template scripts.
   7
   8 ## Including Additional CMake Files
   9
  10 You can include machine and system custom CMake files and
  11 operating system custom CMake files.
  12
  13 ### Machine and System Custom CMake Files
  14
  15 Advanced configuration is possible by automatically including
  16 additional CMake files from specific locations.
  17 Following are the locations from which you can add CMake
  18 files.
  19 Inclusions occur in the order shown here:
  20
  21 - `<project-root-path>/conf.d/app-templates/cmake/cmake.d` - normally located CMake project files
  22 - `$HOME/.config/app-templates/cmake.d` - the home location
  23 - `/etc/app-templates/cmake.d` - the system location
  24
  25 The CMake files you include must be named using either of the following conventions:
  26
  27 - `XX-common*.cmake`
  28 - `XX-${PROJECT_NAME}*.cmake`
  29
  30 In both formats, `XX` are numbers and indicate the order in which the file
  31 is included.
  32 The `*` character represents the filename.
  33
  34 When naming the file, consider the projects in which the file needs to be
  35 included.
  36 If you want to include the file in all projects, use the keyword `common`.
  37 If you want to include the file in a specific project, use the `${PROJECT_NAME}`
  38 value.
  39
  40 For example, if you want a CMake file whose name is `my_custom_file`
  41 included first and you want it included in all projects, name the file
  42 `01-common-my_custom_file.cmake`.
  43 If you want the same file included in a single project defined by the
  44 `PROJECT_NAME` variable, and you want it included after all other files,
  45 name the file `99-${PROJECT_NAME}-my_custom_file.cmake`.
  46
  47 When you include CMake files that use CMake variables, the values override
  48 variables with the same name.
  49 The exception to this rule is if you use a cached variable.
  50 Following is an example:
  51
  52 ```cmake
  53 set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
  54 ```
  55
  56 In this example, the `VARIABLE_NAME` variable is defined as a cached
  57 variable by using the **CACHE** keyword.
  58 Consequently, `VARIABLE_NAME` does not get overridden as a result of
  59 including a CMake file that sets the same variable.
  60
  61 ### Operating System Custom CMake Files
  62
  63 Including custom CMake files based on the operating system
  64 lets you personalize a project depending on the operating system
  65 you are using.
  66
  67 At the end of the `config.cmake` file `common.cmake` includes
  68 CMake files to customize your project build depending on your platform.
  69 The operating system is detected by using `/etc/os-release`,
  70 which is the default method used in almost all Linux distributions.
  71 Consequently, you can use the value of field **ID_LIKE** to
  72 add a CMake file for that distribution.
  73 The file comes from your `conf.d/cmake/` directory or relatively
  74 from your `app-templates` submodule path `app-templates/../cmake/`.
  75
  76 **NOTE:** If the **ID_LIKE** field does not exist, you can use the
  77 **ID** field.
  78
  79 Files that you add must be named according to the following file naming
  80 convention:
  81
  82 - `XX-${OSRELEASE}*.cmake`
  83
  84 In the naming convention, `XX` represents numbers and is the order in which
  85 you want a file included.
  86 The ${OSRELEASE} value is taken from either the **ID_LIKE** or **ID** field
  87 of the `/etc/os-release` file.
  88
  89 You can also configure a CMake file to be included in cases where no
  90 specific operating system can be found.
  91 To do so, name your CMake file as follows:
  92
  93 - `XX-default*.cmake`
  94
  95 A good use case example for these two naming conventions is when you have
  96 a several Linux distributions and all but one can use the same module.
  97 For that case, name one CMake file using the `${OSRELEASE}` value and
  98 name the CMake file to be used with the other distributions using
  99 the `XX-default*.cmake` method.
 100
 101 ## Including Custom Template Scripts
 102
 103 You can include your own custom template scripts that are passed to the
 104 CMake command `configure_file`.
 105
 106 Just create your own script and place it in either of the following directories:
 107
 108 - `$HOME/.config/app-templates/scripts` - the home location
 109 - `/etc/app-templates/scripts` - the system location
 110
 111 Scripts only need to use the extension `.in` to be parsed and configured by
 112 CMake.