docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/2_Configuring_AGL_CMake_Templates.md

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