docs/dev_guide/4_advanced_customization.md

   1 # Advanced customization
   2
   3 ## Including additionnals cmake files
   4
   5 Advanced tuning is possible using addionnals cmake files that are included
   6 automatically from some specifics locations. They are included in that order:
   7
   8 - Project CMake files normaly located in _<project-root-path>/conf.d/app-templates/cmake/cmake.d_
   9 - Home CMake files located in _$HOME/.config/app-templates/cmake.d_
  10 - System CMake files located in _/etc/app-templates/cmake.d_
  11
  12 CMake files has to be named using the following convention: `XX-common-*.cmake`
  13 or `XX-${PROJECT_NAME}-*.cmake`, where `XX` are numbers, `*` file name
  14 (ie. `99-common-my_customs.cmake`).
  15
  16 > **NOTE** You need to specify after numbers that indicate include order, to
  17 which project that file applies, if it applies to all project then use keyword
  18 `common`.
  19
  20 So, saying that you should be aware that every normal cmake variables used at
  21 project level could be overwrited by home or system located cmake files if
  22 variables got the same name. Exceptions are cached variables set using
  23 **CACHE** keyword:
  24
  25 Example:
  26
  27 ```cmake
  28 set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
  29 ```
  30
  31 ## Include customs templated scripts
  32
  33 As well as for additionnals cmake files you can include your own templated
  34 scripts that will be passed to cmake command `configure_file`.
  35
  36 Just create your own script to the following directories:
  37
  38 - Home location in _$HOME/.config/app-templates/scripts_
  39 - System location in _/etc/app-templates/scripts_
  40
  41 Scripts only needs to use the extension `.in` to be parsed and configured by
  42 CMake command.