docs/3_Developer_Guides/3_Using_the_CMAKE_Applications_Module /7_Advanced_Customization.md

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