docs/3_Developer_Guides/3_Using_the_CMAKE_Applications_Module /6_Advanced_Usage.md

   1 ---
   2 edit_link: ''
   3 title: Advanced Usage
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/cmake-apps-module/plain/docs/dev_guide/advanced-usage.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 # Advanced Usage
  11
  12 This topic describes some advanced ways of using the CMake templates.
  13
  14 ## Building a Widget
  15
  16 To build a widget, you need a `config.xml` file that describes
  17 your application (widget) and how the Application Framework launches it.
  18 Your repository contains a simple default file named
  19 `config.xml.in` that should work for simple applications and should
  20 not require interactions with other bindings.
  21
  22 It is also recommended that you use the sample configuration
  23 file that you can find in the location.
  24 This file is named `config.xms.in.sample` and is more complete.
  25 Copy the sample file to your `conf.d/wgt` directory and name it
  26 `config.xml.in`.
  27 Once you have your copy, edit the file to fit your needs.
  28
  29 **CAUTION:** The default file is only meant to be used for a
  30 simple widget application.
  31 For more complicated applications that need to export
  32 their API, or ship several applications in one widget
  33 need to use the provided `config.xml.in.sample` file, which has
  34 all new Application Framework features explained and provides
  35 examples.
  36
  37 ## Using CMake Template Macros
  38
  39 To leverage all CMake template features, you must specify properties
  40 on your targets.
  41 Some macros do not work unless you specify the target type.
  42 If you do not specify a type (e.g. a custom target such as an
  43 HTML5 application), the macro uses the `LABELS` property to
  44 determine the target type.
  45
  46 The `LABELS` property can be set to the values shown in the
  47 [Target Properties](configuring-cmake.html#target-properties)
  48 Section.
  49
  50 Aside from those values, the following optional values can be
  51 assigned to the `LABELS` property.
  52 These values define the resource types that make up your test materials:
  53
  54 - **TEST-CONFIG**: JSON configuration files used by the `afb-test`
  55  binding.
  56  These files execute the tests.
  57 - **TEST-DATA**: Resources used to test your binding.
  58  Minimally, you need a test plan.
  59  You should also consider fixtures and any files required by your tests.
  60  These required files appear as part of a separate test widget.
  61 - **TEST-PLUGIN**: A shared library used as a binding plugin.
  62  A binding loads the library as a plugin to extend the binding's functionality.
  63  You should use a special file extension when you name the library
  64  by using the `SUFFIX` CMake target property.
  65  If you do not choose an extension, `.ctlso` is used by default.
  66 - **TEST-HTDOCS**: The root directory of a web application.
  67  This target has to build its directory and put its files in
  68  the `${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}` directory.
  69 - **TEST-EXECUTABLE**: The entry point of your application executed by the AGL
  70  Application Framework.
  71 - **TEST-LIBRARY**: An external third-party library bundled with the binding
  72  for its own purpose.
  73  The platform does not provide this library.
  74
  75 Following is a mapping between `LABELS` and directories where files reside in
  76 the widget:
  77
  78 - **EXECUTABLE** : \<wgtrootdir\>/bin
  79 - **BINDING-CONFIG** : \<wgtrootdir\>/etc
  80 - **BINDING** | **BINDINGV2** | **BINDINGV3** | **LIBRARY** : \<wgtrootdir\>/lib
  81 - **PLUGIN** : \<wgtrootdir\>/lib/plugins
  82 - **HTDOCS** : \<wgtrootdir\>/htdocs
  83 - **BINDING-DATA** : \<wgtrootdir\>/var
  84 - **DATA** : \<wgtrootdir\>/var
  85
  86 Following is a mapping between test-dedicated `LABELS` and directories where
  87 files reside in the widget:
  88
  89 - **TEST-EXECUTABLE** : \<wgtrootdir\>/bin
  90 - **TEST-CONFIG** : \<TESTwgtrootdir\>/etc
  91 - **TEST-PLUGIN** : \<wgtrootdir\>/lib/plugins
  92 - **TEST-HTDOCS** : \<wgtrootdir\>/htdocs
  93 - **TEST-DATA** : \<TESTwgtrootdir\>/var
  94
  95 **TIP:** Use the prefix `afb-` (Application Framework Binding)
  96 with your **BINDING** targets.
  97
  98 Following is an example that sets the `LABELS` and `OUTPUT_NAME` properties:
  99
 100 ```cmake
 101 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 102                 LABELS "HTDOCS"
 103                 OUTPUT_NAME dist.prod
 104         )
 105 ```
 106
 107 **NOTE**: You do not need to specify an **INSTALL** command for these
 108   targets.
 109   Installation is handled by the template and installs using the
 110   following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 111
 112   Also, if you want to set and use `rpath` with your target, you should use
 113   and set the target property `INSTALL_RPATH`.
 114
 115 ## Adding an External Third-Party Library
 116
 117 You can add an external third-party library that is built, linked,
 118 and shipped with the project.
 119 Or, you can link and ship the library only with the project.
 120
 121 ### Building, Linking, and Shipping an External Library with the Project
 122
 123 If you need to include an external library that is not shipped
 124 with the project, you can bundle the required library in the
 125 `lib` widget directory.
 126
 127 Templates includes facilities to help you work with external
 128 libraries.
 129 A standard method is to declare as many CMake ExternalProject
 130 modules as you need to match the number of needed libraries.
 131
 132 An ExternalProject module is a special CMake module that lets you define how
 133 to download, update, patch, configure, build, and install an external project.
 134 The project does not need to be a CMake project.
 135 Additionally, you can provide custom steps to account for special
 136 needs using ExternalProject step.
 137 See the CMake
 138 [ExternalProject documentation site](https://cmake.org/cmake/help/v3.5/module/ExternalProject.html?highlight=externalproject)
 139 for more information.
 140
 141 Following is an example that includes the `mxml` library for the
 142 [unicens2-binding](https://github.com/iotbzh/unicens2-binding)
 143 project:
 144
 145 ```cmake
 146 set(MXML external-mxml)
 147 set(MXML_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/mxml)
 148 ExternalProject_Add(${MXML}
 149     GIT_REPOSITORY https://github.com/michaelrsweet/mxml.git
 150     GIT_TAG release-2.10
 151     SOURCE_DIR ${MXML_SOURCE_DIR}
 152     CONFIGURE_COMMAND ./configure --build x86_64 --host aarch64
 153     BUILD_COMMAND make libmxml.so.1.5
 154     BUILD_IN_SOURCE 1
 155     INSTALL_COMMAND ""
 156 )
 157
 158 PROJECT_TARGET_ADD(mxml)
 159
 160 add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
 161
 162 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 163     LABELS LIBRARY
 164     IMPORTED_LOCATION ${MXML_SOURCE_DIR}/libmxml.so.1
 165     INTERFACE_INCLUDE_DIRECTORIES ${MXML_SOURCE_DIR}
 166 )
 167
 168 add_dependencies(${TARGET_NAME} ${MXML})
 169 ```
 170
 171 The example defines an external project that drives the building of the library.
 172 The example also defines a new CMake target whose type is **IMPORTED**.
 173 The **IMPORTED** target type indicates the target has yet to be built using
 174 CMake but is available at the location defined using the **IMPORTED_LOCATION**
 175 target property.
 176
 177 You might want to build the library as **SHARED** or **STATIC** depending on your needs
 178 and goals.
 179 Next, the example only has to modify the external project configure step and change
 180 the filename used by **IMPORTED** library target defined after external project.
 181
 182 The target's **LABELS** property is set to **LIBRARY** to ship it in the widget.
 183
 184 In this example, the Unicens project also needs header
 185 information from this library.
 186 Consequently, the **INTERFACE_INCLUDE_DIRECTORIES** target property
 187 is used.
 188 Setting that property when another target links to that imported target
 189 allows access to included directories.
 190
 191 Finally, the example binds the target to the external project
 192 by using a CMake dependency.
 193
 194 The target can now be linked and used like any other CMake target.
 195
 196 ### Link and Ship an External Library with the Project
 197
 198 If you already have a binary version of the library that you want to use and you
 199 cannot or do not want to build the library, you can use the **IMPORTED**
 200 library target.
 201
 202 To illustrate, consider the same example in the previous section.
 203 Following are the relevant modifications:
 204
 205 ```cmake
 206 PROJECT_TARGET_ADD(mxml)
 207
 208 add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
 209
 210 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 211     LABELS LIBRARY
 212     IMPORTED_LOCATION /path_to_library/libmxml.so.1
 213     INTERFACE_INCLUDE_DIRECTORIES /path_to_mxml/include/dir
 214 )
 215 ```
 216
 217 In the previous example, notice the changes to the
 218 `IMPORTED_LOCATION` and `INTERFACE_INCLUDE_DIRECTORIES` statements.
 219 These locate the binary version of the library.
 220
 221 Finally, you can link any other library or executable target with this imported
 222 library just as you would for any other target.
 223
 224 ## Macro Reference
 225
 226 Following are several macros that are useful for advanced CMake usage.
 227
 228 ### PROJECT_TARGET_ADD
 229
 230 This macro adds the target to your project.
 231 Following is a typical example that adds the target to your project.
 232 You need to provide the name of your target as the macro's parameter:
 233
 234 Example:
 235
 236 ```cmake
 237 PROJECT_TARGET_ADD(low-can-demo)
 238 ```
 239
 240 The macro makes the variable `${TARGET_NAME}` available and it is defined
 241 using the specified name (e.g. `low-can-demo`).
 242 The variable changes each time the `PROJECT_TARGET_ADD` macro is called.
 243
 244 ### project_subdirs_add
 245
 246 This macro searches within specified subfolders of the CMake project for
 247 any `CMakeLists.txt` file.
 248 If the file is found, it is added to your project.
 249 You can use this macro in a hybrid application (e.g. where the binding
 250 exists in a subfolder).
 251
 252 The following example searches within all subfolders:
 253
 254 Usage :
 255
 256 ```cmake
 257 project_subdirs_add()
 258 ```
 259
 260 You might want to restrict the subfolders being searched.
 261 If so, you can specify a
 262 [globbing](https://en.wikipedia.org/wiki/Glob_(programming)) pattern
 263 as the argument.
 264 Doing so effectively creates a search filter.
 265
 266 Following is an example that specifies all directories that begin
 267 with a number, are followed by the dash character, and then followed
 268 by any characters:
 269
 270 ```cmake
 271 project_subdirs_add("[0-9]-*")
 272 ```
 273
 274 ### set_openapi_filename
 275
 276 This macro is used with a **BINDINGV2** target and defines the
 277 binding definition filename.
 278 You can use it to also define a relative path to
 279 the current `CMakeLists.txt` file.
 280
 281 If you do not use this macro to specify the name of your definition file,
 282 the default one is used, which is `${OUTPUT_NAME}-apidef` and uses
 283 **OUTPUT_NAME** as the [target property].
 284
 285 **CAUTION** When specifying the binding definition filename,
 286 you must not use the file's extension as part of the name.
 287 Following is an example:
 288
 289 ```cmake
 290 set_openapi_filename('binding/mybinding_definition')
 291 ```
 292
 293 [target property]: https://cmake.org/cmake/help/v3.6/prop_tgt/OUTPUT_NAME.html "OUTPUT_NAME property documentation"
 294
 295 ### add_input_files
 296
 297 This macro creates a custom target dedicated for HTML5 and data resource files.
 298 The macro provides syntax and schema verification for different languages that
 299 include LUA, JSON and XML.
 300
 301 Alongside the macro are tools used to check files.
 302 You can configure the tools by setting the
 303 following variables:
 304
 305 - XML_CHECKER: Uses **xmllint** that is provided with major linux distributions.
 306 - LUA_CHECKER: Uses **luac** that is provided with major linux distributions.
 307 - JSON_CHECKER: Currently, not used by any tools.
 308
 309 Following is an example:
 310
 311 ```cmake
 312 add_input_file("${MY_FILES_LIST}")
 313 ```
 314
 315 **NOTE**: If an issue occurs during the "check" step of the macro,
 316 the build halts.