README.md

   1 # AGL CMake template
   2
   3 Files used to build an application, or binding, project with the
   4 AGL Application Framework.
   5
   6 To build your AGL project using these templates, you have to install
   7 them within your project and adjust compilation option in `config.cmake`.
   8 For technical reasons, you also have to specify **cmake** target in
   9 sub CMakeLists.txt installed. Make a global search to find source files
  10 isn't recommended now to handle project build especially in a multi-users
  11 project because CMake will not be aware of new or removed source files.
  12
  13 You'll find usage samples here:
  14
  15 - [helloworld-service](https://github.com/iotbzh/helloworld-service)
  16 - [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service)
  17 - [high-level-viwi-service](https://github.com/iotbzh/high-level-viwi-service)
  18 - [audio-binding](https://github.com/iotbzh/audio-binding)
  19 - [unicens2-binding](https://github.com/iotbzh/unicens2-binding)
  20
  21 ## Quickstart
  22
  23 ### Initialization
  24
  25 To use these templates files on your project just install the reference files using
  26 **git submodule** then use `config.cmake` file to configure your project specificities :
  27
  28 ```bash
  29 git submodule add https://gerrit.automotivelinux.org/gerrit/p/apps/app-templates.git conf.d/app-templates
  30 mkdir conf.d/cmake
  31 cp conf.d/app-templates/samples.d/config.cmake.sample conf.d/cmake/config.cmake
  32 ```
  33
  34 Edit the copied config.cmake file to fit your needs.
  35
  36 Now, create your top CMakeLists.txt file which include `config.cmake` file.
  37
  38 An example is available in **app-templates** submodule that you can copy and
  39 use:
  40
  41 ```bash
  42 cp conf.d/app-templates/samples.d/CMakeLists.txt.sample CMakeLists.txt
  43 ```
  44
  45 ### Create your CMake targets
  46
  47 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
  48 to include this target to your project.
  49
  50 Using it, make available the cmake variable ***TARGET_NAME*** until the next
  51 ***PROJECT_TARGET_ADD*** is invoked with a new target name.
  52
  53 So, typical usage defining a target is:
  54
  55 ```cmake
  56 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
  57
  58 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
  59
  60 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties
  61 for macros usage
  62 ```
  63
  64 ### Targets PROPERTIES
  65
  66 You should set properties on your targets that will be used to package your
  67 apps in a widget file that could be installed on an AGL system.
  68
  69 Specify what is the type of your targets that you want to be included in the
  70 widget package with the property **LABELS**:
  71
  72 Choose between:
  73
  74 - **BINDING**: Shared library that be loaded by the AGL Application Framework
  75 - **BINDINGV2**: Shared library that be loaded by the AGL Application Framework
  76  This has to be accompanied with a JSON file named like the
  77  *${OUTPUT_NAME}-apidef* of the target that describe the API with OpenAPI
  78  syntax (e.g: *mybinding-apidef*).
  79  Or Alternatively, you can choose the name, without the extension, using macro
  80  **set_openapi_filename**. If you use C++, you have to set
  81  **PROJECT_LANGUAGES** with *CXX*.
  82 - **PLUGIN**: Shared library meant to be used as a binding plugin. Binding
  83  would load it as a plugin to extend its functionalities. It should be named
  84  with a special extension that you choose with SUFFIX cmake target property or
  85  it'd be **.ctlso** by default.
  86 - **HTDOCS**: Root directory of a web app. This target has to build its
  87  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  88 - **DATA**: Resources used by your application. This target has to build its
  89  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  90 - **EXECUTABLE**: Entry point of your application executed by the AGL
  91  Application Framework
  92 - **LIBRARY**: An external 3rd party library bundled with the binding for its
  93  own purpose because platform doesn't provide it.
  94
  95 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
  96 > stand for **Application Framework Binding**.
  97
  98 ```cmake
  99 SET_TARGET_PROPERTIES(${TARGET_NAME}
 100         PREFIX "afb-"
 101         LABELS "BINDINGV2"
 102         OUTPUT_NAME "file_output_name"
 103 )
 104 ```
 105
 106 > **NOTE**: You doesn't need to specify an **INSTALL** command for these
 107 > targets. This is already handle by template and will be installed in the
 108 > following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 109
 110 ## More details: Typical project architecture
 111
 112 A typical project architecture would be :
 113
 114 ```tree
 115 <project-root-path>
 116 │
 117 ├── conf.d/
 118 │   ├── autobuild/
 119 │   │   ├── agl
 120 │   │   │   └── autobuild
 121 │   │   ├── linux
 122 │   │   │   └── autobuild
 123 │   │   └── windows
 124 │   │       └── autobuild
 125 │   ├── app-templates/
 126 │   │   ├── README.md
 127 │   │   ├── cmake/
 128 │   │   │   ├── export.map
 129 │   │   │   └── macros.cmake
 130 │   │   ├── samples.d/
 131 │   │   │   ├── CMakeLists.txt.sample
 132 │   │   │   ├── config.cmake.sample
 133 │   │   │   ├── config.xml.in.sample
 134 │   │   │   └── xds-config.env.sample
 135 │   │   ├── template.d/
 136 │   │   │   ├── autobuild/
 137 │   │   │   │   ├── agl
 138 │   │   │   │   │   └── autobuild.in
 139 │   │   │   │   ├── linux
 140 │   │   │   │   │   └── autobuild.in
 141 │   │   │   │   └── windows
 142 │   │   │   │       └── autobuild.in
 143 │   │   │   ├── config.xml.in
 144 │   │   │   ├── deb-config.dsc.in
 145 │   │   │   ├── deb-config.install.in
 146 │   │   │   ├── debian.changelog.in
 147 │   │   │   ├── debian.compat.in
 148 │   │   │   ├── debian.rules.in
 149 │   │   │   ├── gdb-on-target.ini.in
 150 │   │   │   ├── install-wgt-on-target.sh.in
 151 │   │   │   ├── start-on-target.sh.in
 152 │   │   │   ├── rpm-config.spec.in
 153 │   │   │   └── xds-project-target.conf.in
 154 │   │   └── wgt/
 155 │   │       ├── icon-default.png
 156 │   │       ├── icon-html5.png
 157 │   │       ├── icon-native.png
 158 │   │       ├── icon-qml.png
 159 │   │       └── icon-service.png
 160 │   ├── packaging/
 161 │   │   ├── config.spec
 162 │   │   └── config.deb
 163 │   ├── cmake
 164 │   │   └── config.cmake
 165 │   └── wgt
 166 │      └── config.xml.in
 167 ├── <libs>
 168 ├── <target>
 169 │   └── <files>
 170 ├── <target>
 171 │   └── <file>
 172 └── <target>
 173     └── <files>
 174 ```
 175
 176 | # | Parent | Description |
 177 | - | -------| ----------- |
 178 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
 179 | conf.d | \<root-path\> | Holds needed files to build, install, debug, package an AGL app project |
 180 | app-templates | conf.d | Git submodule to app-templates AGL repository which provides CMake helpers macros library, and build scripts. config.cmake is a copy of config.cmake.sample configured for the projects. SHOULD NOT BE MODIFIED MANUALLY !|
 181 | autobuild | conf.d | Scripts generated from app-templates to build packages the same way for various platforms.|
 182 | cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. |
 183 | wgt | conf.d | Contains at least config.xml.in template file modified from the sample provided in app-templates submodule for the needs of project (See config.xml.in.sample file for more details). |
 184 | packaging | conf.d | Contains output files used to build packages. |
 185 | \<libs\> | \<root-path\> | External dependencies libraries. This isn't to be used to include header file but build and link statically specifics libraries. | Library sources files. Can be a decompressed library archive file or project fork. |
 186 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
 187
 188 ### Update app-templates submodule
 189
 190 You may have some news bug fixes or features available from app-templates
 191 repository that you want. To update your submodule proceed like the following:
 192
 193 ```bash
 194 git submodule update --remote
 195 git commit -s conf.d/app-templates
 196 ```
 197
 198 This will update the submodule to the HEAD of master branch repository.
 199
 200 You could just want to update at a specified repository tag or branch or commit
 201 , here are the method to do so:
 202
 203 ```bash
 204 cd conf.d/app-templates
 205 # Choose one of the following depending what you want
 206 git checkout <tag_name>
 207 git checkout --detach <branch_name>
 208 git checkout --detach <commit_id>
 209 # Then commit
 210 cd ../..
 211 git commit -s conf.d/app-templates
 212 ```
 213
 214 ### Build a widget
 215
 216 #### config.xml.in file
 217
 218 To build a widget you need a _config.xml_ file describing what is your apps and
 219 how Application Framework would launch it. This repo provide a simple default
 220 file _config.xml.in_ that should work for simple application without
 221 interactions with others bindings.
 222
 223 It is recommended that you use the sample one which is more complete. You can
 224 find it at the same location under the name _config.xml.in.sample_ (stunning
 225 isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it
 226 _config.xml.in_, then edit it to fit your needs.
 227
 228 > ***CAUTION*** : The default file is only meant to be use for a
 229 > simple widget app, more complicated ones which needed to export
 230 > their api, or ship several app in one widget need to use the provided
 231 > _config.xml.in.sample_ which had all new Application Framework
 232 > features explained and examples.
 233
 234 #### Using cmake template macros
 235
 236 To leverage all cmake templates features, you have to specify ***properties***
 237 on your targets. Some macros will not works without specifying which is the
 238 target type.
 239
 240 As the type is not always specified for some custom targets, like an ***HTML5***
 241 application, macros make the difference using ***LABELS*** property.
 242
 243 Choose between:
 244
 245 - **BINDING**: Shared library that be loaded by the AGL Application Framework
 246 - **BINDINGV2**: Shared library that be loaded by the AGL Application Framework
 247  This has to be accompagnied with a JSON file named like the
 248  *${OUTPUT_NAME}-apidef* of the target that describe the API with OpenAPI
 249  syntax (e.g: *mybinding-apidef*).
 250  Or Alternatively, you can choose the name, without the extension, using macro
 251  **set_openapi_filename**. If you use C++, you have to set
 252  **PROJECT_LANGUAGES** with *CXX*.
 253 - **PLUGIN**: Shared library meant to be used as a binding plugin. Binding
 254  would load it as a plugin to extend its functionnalities. It should be named
 255  with a special extension that you choose with SUFFIX cmake target property or
 256  it'd be **.ctlso** by default.
 257 - **HTDOCS**: Root directory of a web app. This target has to build its
 258  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
 259 - **DATA**: Resources used by your application. This target has to build its
 260  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
 261 - **EXECUTABLE**: Entry point of your application executed by the AGL
 262  Application Framework
 263 - **LIBRARY**: An external 3rd party library bundled with the binding for its
 264  own purpose because platform doesn't provide it.
 265
 266 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
 267 > stand for **Application Framework Binding**.
 268
 269 Example:
 270
 271 ```cmake
 272 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 273                 LABELS "HTDOCS"
 274                 OUTPUT_NAME dist.prod
 275         )
 276 ```
 277
 278 > **NOTE**: You doesn't need to specify an **INSTALL** command for these
 279 > targets. This is already handle by template and will be installed in the
 280 > following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 281
 282 > **NOTE**: if you want to set and use `rpath` with your target you should use
 283 > and set the target property `INSTALL_RPATH`.
 284
 285 ## Add external 3rd party library
 286
 287 ### Build, link and ship external library with the project
 288
 289 You could need to include an external library that isn't shipped in the
 290 platform. Then you have to bundle the required library in the `lib` widget
 291 directory.
 292
 293 Templates includes some facilities to help you to do so. Classic way to do so
 294 is to declare as many CMake ExternalProject as library you need.
 295
 296 An ExternalProject is a special CMake module that let you define how to:
 297 download, update, patch, configure, build and install an external project. It
 298 doesn't have to be a CMake project and custom step could be added for special
 299 needs using ExternalProject step. More informations on CMake [ExternalProject
 300 documentation site](https://cmake.org/cmake/help/v3.5/module/ExternalProject.html?highlight=externalproject).
 301
 302 Example to include `mxml` library for [unicens2-binding](https://github.com/iotbzh/unicens2-binding)
 303 project:
 304
 305 ```cmake
 306 set(MXML external-mxml)
 307 set(MXML_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/mxml)
 308 ExternalProject_Add(${MXML}
 309     GIT_REPOSITORY https://github.com/michaelrsweet/mxml.git
 310     GIT_TAG release-2.10
 311     SOURCE_DIR ${MXML_SOURCE_DIR}
 312     CONFIGURE_COMMAND ./configure --build x86_64 --host aarch64
 313     BUILD_COMMAND make libmxml.so.1.5
 314     BUILD_IN_SOURCE 1
 315     INSTALL_COMMAND ""
 316 )
 317
 318 PROJECT_TARGET_ADD(mxml)
 319
 320 add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
 321
 322 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 323     LABELS LIBRARY
 324     IMPORTED_LOCATION ${MXML_SOURCE_DIR}/libmxml.so.1
 325     INTERFACE_INCLUDE_DIRECTORIES ${MXML_SOURCE_DIR}
 326 )
 327
 328 add_dependencies(${TARGET_NAME} ${MXML})
 329 ```
 330
 331 Here we define an external project that drive the build of the library then we
 332 define new CMake target of type **IMPORTED**. Meaning that this target hasn't
 333 been built using CMake but is available at the location defined in the target
 334 property *IMPORTED_LOCATION*.
 335
 336 You could want to build the library as *SHARED* or *STATIC* depending on your needs
 337 and goals. Then you only have to modify the external project configure step and change
 338 filename used by **IMPORTED** library target defined after external project.
 339
 340 Then target *LABELS* property is set to **LIBRARY** to ship it in the widget.
 341
 342 Unicens project also need some header from this library, so we use the target
 343 property *INTERFACE_INCLUDE_DIRECTORIES*. Setting that when another target link
 344 to that imported target, it can access to the include directories.
 345
 346 We bound the target to the external project using a CMake dependency at last.
 347
 348 Then this target could be use like any other CMake target and be linked etc.
 349
 350 ### Only link and ship external library with the project
 351
 352 If you already have a binary version of the library that you want to use and you
 353 can't or don't want to build the library then you only have to add an **IMPORTED**
 354 library target.
 355
 356 So, taking the above example, `mxml` library inclusion would be:
 357
 358 ```cmake
 359 PROJECT_TARGET_ADD(mxml)
 360
 361 add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
 362
 363 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 364     LABELS LIBRARY
 365     IMPORTED_LOCATION /path/to/library/libmxml.so.1
 366     INTERFACE_INCLUDE_DIRECTORIES /path/to/mxml/include/dir
 367 )
 368 ```
 369
 370 Finally, you can link any other lib or executable target with this imported
 371 library like any other target.
 372
 373 #### Macro reference
 374
 375 ##### PROJECT_TARGET_ADD
 376
 377 Typical usage would be to add the target to your project using macro
 378 `PROJECT_TARGET_ADD` with the name of your target as parameter.
 379
 380 Example:
 381
 382 ```cmake
 383 PROJECT_TARGET_ADD(low-can-demo)
 384 ```
 385
 386 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
 387 > set with the specificied name. This variable will change at the next call
 388 > to this macros.
 389
 390 ##### project_subdirs_add
 391
 392 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
 393 it will be added to your project. This could be use in an hybrid application by
 394 example where the binding lay in a sub directory.
 395
 396 Usage :
 397
 398 ```cmake
 399 project_subdirs_add()
 400 ```
 401
 402 You also can specify a globbing pattern as argument to filter which folders
 403 will be looked for.
 404
 405 To filter all directories that begin with a number followed by a dash the
 406 anything:
 407
 408 ```cmake
 409 project_subdirs_add("[0-9]-*")
 410 ```
 411
 412 ### set_openapi_filename
 413
 414 Used with a target labelized **BINDINGV2** to define the file name, and
 415 possibly a relative path with the current *CMakeLists.txt*.
 416
 417 If you don't use that macro to specify the name of your definition file
 418 then the default one will be used, *${OUTPUT_NAME}-apidef* with
 419 **OUTPUT_NAME** as the [target property].
 420
 421 > **CAUTION** you must only specify the name **WITHOUT** the extension.
 422
 423 ```cmake
 424 set_openapi_filename('binding/mybinding_definition')
 425 ```
 426
 427 [target property]: https://cmake.org/cmake/help/v3.6/prop_tgt/OUTPUT_NAME.html "OUTPUT_NAME property documentation"
 428
 429 ### add_input_files
 430
 431 Create custom target dedicated for HTML5 and data resource files. This macro
 432 provides syntax and schema verification for various languages which are
 433 about now: LUA, JSON and XML.
 434
 435 You could change the tools used to check files with the following variables:
 436
 437 - XML_CHECKER: set to use **xmllint** provided with major linux distribution.
 438 - LUA_CHECKER: set to use **luac** provided with major linux distribution.
 439 - JSON_CHECKER: no tools found at the moment.
 440
 441 ```cmake
 442 add_input_file("${MY_FILES_LIST}")
 443 ```
 444
 445 > **NOTE**: an issue at the check step on a file will stop at the build step.
 446
 447 ## Advanced build customization
 448
 449 ### Including additional cmake files
 450
 451 #### Machine and system custom cmake files
 452
 453 Advanced tuning is possible using additional cmake files that are included
 454 automatically from some specifics locations. They are included in that order:
 455
 456 - Project CMake files normally located in _<project-root-path>/conf.d/app-templates/cmake/cmake.d_
 457 - Home CMake files located in _$HOME/.config/app-templates/cmake.d_
 458 - System CMake files located in _/etc/app-templates/cmake.d_
 459
 460 CMake files has to be named using the following convention: `XX-common*.cmake`
 461 or `XX-${PROJECT_NAME}*.cmake`, where `XX` are numbers, `*` file name
 462 (ie. `99-common-my_customs.cmake`).
 463
 464 > **NOTE** You need to specify after numbers that indicate include order, to
 465 which project that file applies, if it applies to all project then use keyword
 466 `common`.
 467
 468 So, saying that you should be aware that every normal cmake variables used at
 469 project level could be overwritten by home or system located cmake files if
 470 variables got the same name. Exceptions are cached variables set using
 471 **CACHE** keyword:
 472
 473 Example:
 474
 475 ```cmake
 476 set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
 477 ```
 478
 479 #### OS custom cmake files
 480
 481 This is meant to personalize the project depending on the OS your are using.
 482 At the end of config.cmake, common.cmake will include lot of cmake file to
 483 customize project build depending on your platform. It will detect your OS
 484 deducing it from file _/etc/os-release_ now as default in almost all Linux
 485 distribution.
 486
 487 So you can use the value of field **ID_LIKE** or **ID** if the
 488 first one doesn't exists and add a cmake file for that distribution in your
 489 _conf.d/cmake/_ directory or relatively to your _app-templates_ submodule path
 490 _app-templates/../cmake/_
 491
 492 Those files has to be named use the following scheme _XX-${OSRELEASE}*.cmake_
 493 where _XX_ are numbers, ${OSRELEASE} the **ID_LIKE** or **ID** field from
 494 _/etc/os-release_ file. You can also define default OS configuration file
 495 to use as fallback is none specific OS configuration is available using the
 496 scheme _XX-default*.cmake_. Then is you need by example a module that isn't
 497 named the same in one distro only, you only has to define a specific file to
 498 handle that case then for all the other case put the configuration in the
 499 default file.
 500
 501 ### Include customs templated scripts
 502
 503 As well as for additional cmake files you can include your own templated
 504 scripts that will be passed to cmake command `configure_file`.
 505
 506 Just create your own script to the following directories:
 507
 508 - Home location in _$HOME/.config/app-templates/scripts_
 509 - System location in _/etc/app-templates/scripts_
 510
 511 Scripts only needs to use the extension `.in` to be parsed and configured by
 512 CMake command.
 513
 514 ## Autobuild script usage
 515
 516 ### Generation
 517
 518 To be integrated in the Yocto build workflow you have to generate `autobuild`
 519 scripts using _autobuild_ target.
 520
 521 To generate those scripts proceeds:
 522
 523 ```bash
 524 mkdir -p build
 525 cd build
 526 cmake .. && make autobuild
 527 ```
 528
 529 You should see _conf.d/autobuild/agl/autobuild_ file now.
 530
 531 ### Available targets
 532
 533 Here are the available targets available from _autobuild_ scripts:
 534
 535 - **clean** : clean build directory from object file and targets results.
 536 - **distclean** : delete build directory
 537 - **configure** : generate project Makefile from CMakeLists.txt files.
 538 - **build** : compile all project targets.
 539 - **package** : build and output a wgt package.
 540
 541 You can specify variables that modify the behavior of compilation using
 542 the following variables:
 543
 544 - **CONFIGURE_ARGS** : Variable used at **configure** time.
 545 - **BUILD_ARGS** : Variable used at **build** time.
 546 - **DEST** : Directory where to output ***wgt*** file.
 547
 548 Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'")
 549
 550 Usage example:
 551
 552 ```bash
 553 ./conf.d/autobuild/wgt/autobuild package DEST=/tmp
 554 ```