docs/3_Developer_Guides/3_Using_the_CMAKE_Applications_Module /4_Configuring_AGL_CMake_Templates.md

   1 ---
   2 edit_link: ''
   3 title: Configuring AGL CMake Templates
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/cmake-apps-module/plain/docs/dev_guide/configuring-cmake.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 # Configuring AGL CMake Templates
  11
  12 Configuration consists of editing the `config.cmake` file for your
  13 specific project.
  14
  15 ## Creating Your `config.cmake` File
  16
  17 First, you need to create a `confd/cmake` file in your CMake project
  18 directory.
  19
  20 ```bash
  21 mkdir -p conf.d/cmake
  22 ```
  23
  24 Next, use one of the following commands to copy a `cmake.sample` file to
  25 your `config.cmake` file.
  26 The first command applies if you have the SDK installed, while the
  27 second command applies if you installed the modules on your native Linux system.
  28
  29 **NOTE:** The `OECORE_NATIVE_SYSROOT` variable is defined once you have
  30 a project folder, the AGL SDK source files, and the CMake modules installed.
  31
  32 ```bash
  33 mkdir -p conf.d/cmake
  34 # From the SDK sysroot >= RC2 of the 7.0.0 Guppy release
  35 cp ${OECORE_NATIVE_SYSROOT}/usr/share/doc/CMakeAfbTemplates/samples.d/config.cmake.sample conf.d/cmake/config.cmake
  36 # From a native installation
  37 cp /usr/share/doc/CMakeAfbTemplates/samples.d/config.cmake.sample conf.d/cmake/config.cmake
  38 ```
  39
  40 Once you have created your `config.cmake` file, you need to make the changes
  41 specific to your project.
  42
  43 ## Creating Your `CMakeLists.txt` File
  44
  45 To create this file, use the example in the **cmake module**.
  46 Use one of the following two commands to create your file.
  47 The first command applies if you have the SDK installed, while the
  48 second command applies if you installed the modules on your native Linux system.
  49
  50 **NOTE:** The `OECORE_NATIVE_SYSROOT` variable is defined once you have
  51 a project folder, the AGL SDK source files, and the CMake modules installed.
  52
  53 ```bash
  54 # From the SDK sysroot >= RC2 of the 7.0.0 Guppy release
  55 cp ${OECORE_NATIVE_SYSROOT}/usr/share/doc/CMakeAfbTemplates/samples.d/CMakeLists.txt.sample CMakeLists.txt
  56 # From a native installation
  57 cp /usr/share/doc/CMakeAfbTemplates/samples.d/CMakeLists.txt.sample CMakeLists.txt
  58 ```
  59
  60 ## Creating Your CMake Targets
  61
  62 Creating a CMake target is the result of editing your `CMakeLists.txt` file.
  63
  64 For each target that is part of your project, you need to use the
  65 ***PROJECT_TARGET_ADD*** statement.
  66 Using this statement includes the target in your project.
  67
  68 Using the ***PROJECT_TARGET_ADD*** statement makes the CMake ***TARGET_NAME***
  69 variable available until the next ***PROJECT_TARGET_ADD*** statement is
  70 encountered that uses a new target name.
  71
  72 Following is typical use within the `CMakeLists.txt` file to create a target:
  73
  74 ```cmake
  75 PROJECT_TARGET_ADD(target_name) --> Adds *target_name* to the project.
  76 *target_name* is a sub-folder in the CMake project.
  77
  78 add_executable/add_library(${TARGET_NAME}.... --> Defines the target sources.
  79
  80 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> Configures the target properties
  81 so they can be used by macros.
  82
  83 INSTALL(TARGETS ${TARGET_NAME}....
  84 ```
  85
  86 ## Target Properties
  87
  88 Target properties are used to determine the nature of the
  89 target and where the target is stored within the package being built.
  90
  91 Use the **LABELS** property to specify the target type that you want
  92 included in the widget package.
  93 You can choose the following target types:
  94
  95 Choose between:
  96
  97 - **BINDING**: A shared library loaded by the AGL Application Framework.
  98 - **BINDINGV2**: A shared library loaded by the AGL Application Framework.
  99   This library must be accompanied by a JSON file named similar to the
 100   *${OUTPUT_NAME}-apidef* of the target, which describes the API with OpenAPI
 101   syntax (e.g: *mybinding-apidef*).
 102   Alternatively, you can choose the name without the extension using the
 103   **set_openapi_filename** macro.
 104   If you use C++, you must set **PROJECT_LANGUAGES** through *CXX*.
 105 - **BINDINGV3**: A shared library loaded by the AGL Application Framework.
 106   This library must be accompanied by a JSON file named similar to the
 107   *${OUTPUT_NAME}-apidef* of the target, which describes the API with OpenAPI
 108   syntax (e.g: *mybinding-apidef*).
 109   Alternatively, you can choose the name without the extension using the
 110   **set_openapi_filename** macro.
 111   If you use C++, you must set **PROJECT_LANGUAGES** through *CXX*.
 112 - **PLUGIN**: A shared library meant to be used as a binding plugin, which
 113   would load the library as a plugin consequently extending its
 114   functionalities.
 115   You should name the binding using a special extension that you choose
 116   with `SUFFIX cmake target property`.
 117   If you do not use the special extension, it defaults to **.ctlso**.
 118 - **HTDOCS**: The root directory of a web application.
 119   This target has to build its directory and puts its files in the
 120   **${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}**.
 121 - **DATA**: Resources used by your application.
 122   This target has to build its directory and puts its files in the
 123   **${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}**.
 124 - **EXECUTABLE**: The entry point of your application executed by the AGL
 125   Application Framework.
 126 - **LIBRARY**: An external third-party library bundled with the binding.
 127   The library is bundled in this manner because the platform does not
 128   provide bundling.
 129 - **BINDING-CONFIG**: Any files used as configuration by your binding.
 130
 131 **TIP:** you should use the prefix _afb-_ (**Application Framework Binding**)
 132 with your *BINDING* targets.
 133
 134 Following is an example that uses the **BINDINGV3** property:
 135
 136 ```cmake
 137 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 138         PREFIX "afb-"
 139         LABELS "BINDINGV3"
 140         OUTPUT_NAME "file_output_name")
 141 ```
 142
 143 **CAUTION**: You do not need to specify an **INSTALL** command for these
 144 targets.
 145 Installation is performed by the template.
 146 Targets are installed in the **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 147 directory.