docs/dev_guide/4_advanced_customization.md

   1 # Advanced build customization
   2
   3 ## Including additionnals cmake files
   4
   5 ### Machine and system custom cmake files
   6
   7 Advanced tuning is possible using addionnals cmake files that are included
   8 automatically from some specifics locations. They are included in that order:
   9
  10 - Project CMake files normaly located in _<project-root-path>/conf.d/app-templates/cmake/cmake.d_
  11 - Home CMake files located in _$HOME/.config/app-templates/cmake.d_
  12 - System CMake files located in _/etc/app-templates/cmake.d_
  13
  14 CMake files has to be named using the following convention: `XX-common*.cmake`
  15 or `XX-${PROJECT_NAME}*.cmake`, where `XX` are numbers, `*` file name
  16 (ie. `99-common-my_customs.cmake`).
  17
  18 > **NOTE** You need to specify after numbers that indicate include order, to
  19 which project that file applies, if it applies to all project then use keyword
  20 `common`.
  21
  22 So, saying that you should be aware that every normal cmake variables used at
  23 project level could be overwrited by home or system located cmake files if
  24 variables got the same name. Exceptions are cached variables set using
  25 **CACHE** keyword:
  26
  27 Example:
  28
  29 ```cmake
  30 set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
  31 ```
  32
  33 ### OS custom cmake files
  34
  35 This is meant to personalize the project depending on the OS your are using.
  36 At the end of config.cmake, common.cmake will include lot of cmake file to
  37 customize project build depending on your plateform. It will detect your OS
  38 deducing it from file _/etc/os-release_ now as default in almost all Linux
  39 distribution.
  40
  41 So you can use the value of field **ID_LIKE** or **ID** if the
  42 first one doesn't exists and add a cmake file for that distribution in your
  43 _conf.d/cmake/_ directory or relatively to your _app-templates_ submodule path
  44 _app-templates/../cmake/_
  45
  46 Those files has to be named use the following scheme _XX-${OSRELEASE}*.cmake_
  47 where _XX_ are numbers, ${OSRELEASE} the **ID_LIKE** or **ID** field from
  48 _/etc/os-release_ file. You can also define default OS configuration file
  49 to use as fallback is none specific OS configuration is available using the
  50 scheme _XX-default*.cmake_. Then is you need by example a module that isn't
  51 named the same in one distro only, you only has to define a specific file to
  52 handle that case then for all the other case put the configuration in the
  53 default file.
  54
  55 ## Include customs templated scripts
  56
  57 As well as for additionnals cmake files you can include your own templated
  58 scripts that will be passed to cmake command `configure_file`.
  59
  60 Just create your own script to the following directories:
  61
  62 - Home location in _$HOME/.config/app-templates/scripts_
  63 - System location in _/etc/app-templates/scripts_
  64
  65 Scripts only needs to use the extension `.in` to be parsed and configured by
  66 CMake command.