From dcaa92ffd4b9c90476e9dca391b85fe441df6bf1 Mon Sep 17 00:00:00 2001 From: Shankho Boron Ghosh Date: Mon, 30 Nov 2020 04:31:25 +0530 Subject: Added Using CMAKE Applications Module in Developer Guides Revised and added Using CMAKE Applications Module as a part of Developer Guides. Bug-AGL: [SPEC-3633] Signed-off-by: Shankho Boron Ghosh Change-Id: I2cf8e06d3f4c43e748476eaddcb950417f5f0eba --- .../4_Advanced_Customization.md | 112 +++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md (limited to 'docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md') diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md new file mode 100644 index 0000000..2b5963c --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md @@ -0,0 +1,112 @@ +--- +title: Advanced Customization +--- + +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: + +- `/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*.cmake` +- `XX-${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: + +```cmake +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. -- cgit 1.2.3-korg