ll-database-binding/conf.d/app-templates/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 globbing search to find source files
  10 isn't recommended now to handle project build especially in a multiuser
  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/cmake/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/cmake/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 accompagnied with a JSON file named like the *${OUTPUT_NAME}-apidef* of
  77  the target that describe the API with OpenAPI syntax (e.g: *mybinding-apidef*).
  78  Or you can choose the name by setting the *CACHE* cmake variable *OPENAPI_DEF*
  79  (***CAUTION***: setting a CACHE variable is needed, or set a normal variable
  80  with the *PARENT_SCOPE* option to make it visible for the parent scope
  81  where the target is defined) JSON file will be used to generate header file
  82  using `afb-genskel` tool.
  83 - **HTDOCS**: Root directory of a web app. This target has to build its
  84  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  85 - **DATA**: Resources used by your application. This target has to build its
  86  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  87 - **EXECUTABLE**: Entry point of your application executed by the AGL
  88  Application Framework
  89
  90 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
  91 > stand for **Application Framework Binding**.
  92
  93 ```cmake
  94 SET_TARGET_PROPERTIES(${TARGET_NAME}
  95         PREFIX "afb-"
  96         LABELS "BINDING"
  97         OUTPUT_NAME "file_output_name"
  98 )
  99 ```
 100
 101 > **NOTE**: You doesn't need to specify an **INSTALL** command for these
 102 > targets. This is already handle by template and will be installed in the
 103 > following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 104
 105 ## More details: Typical project architecture
 106
 107 A typical project architecture would be :
 108
 109 ```tree
 110 <project-root-path>
 111 │
 112 ├── conf.d/
 113 │   ├── autobuild/
 114 │   │   ├── agl
 115 │   │   │   └── autobuild
 116 │   │   ├── linux
 117 │   │   │   └── autobuild
 118 │   │   └── windows
 119 │   │       └── autobuild
 120 │   ├── app-templates/
 121 │   │   ├── README.md
 122 │   │   ├── autobuild/
 123 │   │   │   ├── agl
 124 │   │   │   │   └── autobuild.in
 125 │   │   │   ├── linux
 126 │   │   │   │   └── autobuild.in
 127 │   │   │   └── windows
 128 │   │   │       └── autobuild.in
 129 │   │   ├── cmake/
 130 │   │   │   ├── config.cmake.sample
 131 │   │   │   ├── export.map
 132 │   │   │   └── macros.cmake
 133 │   │   ├── deb/
 134 │   │   │   └── config.deb.in
 135 │   │   ├── rpm/
 136 │   │   │   └── config.spec.in
 137 │   │   └── wgt/
 138 │   │       ├── config.xml.in
 139 │   │       ├── config.xml.in.sample
 140 │   │       ├── icon-default.png
 141 │   │       ├── icon-html5.png
 142 │   │       ├── icon-native.png
 143 │   │       ├── icon-qml.png
 144 │   │       └── icon-service.png
 145 │   ├── packaging/
 146 │   │   ├── config.spec
 147 │   │   └── config.deb
 148 │   ├── cmake
 149 │   │   └── config.cmake
 150 │   └── wgt
 151 │      └── config.xml.in
 152 ├── <libs>
 153 ├── <target>
 154 │   └── <files>
 155 ├── <target>
 156 │   └── <file>
 157 └── <target>
 158     └── <files>
 159 ```
 160
 161 | # | Parent | Description |
 162 | - | -------| ----------- |
 163 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
 164 | conf.d | \<root-path\> | Holds needed files to build, install, debug, package an AGL app project |
 165 | 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 !|
 166 | autobuild | conf.d | Scripts generated from app-templates to build packages the same way for differents platforms.|
 167 | cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. |
 168 | 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). |
 169 | packaging | conf.d | Contains output files used to build packages. |
 170 | \<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. |
 171 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
 172
 173 ### Update app-templates submodule
 174
 175 You may have some news bug fixes or features available from app-templates
 176 repository that you want. To update your submodule proceed like the following:
 177
 178 ```bash
 179 git submodule update --remote
 180 git commit -s conf.d/app-templates
 181 ```
 182
 183 This will update the submodule to the HEAD of master branch repository.
 184
 185 You could just want to update at a specified repository tag or branch or commit
 186 , here are the method to do so:
 187
 188 ```bash
 189 cd conf.d/app-templates
 190 # Choose one of the following depending what you want
 191 git checkout <tag_name>
 192 git checkout --detach <branch_name>
 193 git checkout --detach <commit_id>
 194 # Then commit
 195 cd ../..
 196 git commit -s conf.d/app-templates
 197 ```
 198
 199 ### Build a widget
 200
 201 #### config.xml.in file
 202
 203 To build a widget you need a _config.xml_ file describing what is your apps and
 204 how Application Framework would launch it. This repo provide a simple default
 205 file _config.xml.in_ that should work for simple application without
 206 interactions with others bindings.
 207
 208 It is recommanded that you use the sample one which is more complete. You can
 209 find it at the same location under the name _config.xml.in.sample_ (stunning
 210 isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it
 211 _config.xml.in_, then edit it to fit your needs.
 212
 213 > ***CAUTION*** : The default file is only meant to be use for a
 214 > simple widget app, more complicated ones which needed to export
 215 > their api, or ship several app in one widget need to use the provided
 216 > _config.xml.in.sample_ which had all new Application Framework
 217 > features explained and examples.
 218
 219 #### Using cmake template macros
 220
 221 To leverage all cmake templates features, you have to specify ***properties***
 222 on your targets. Some macros will not works without specifying which is the
 223 target type.
 224
 225 As the type is not always specified for some custom targets, like an ***HTML5***
 226 application, macros make the difference using ***LABELS*** property.
 227
 228 Choose between:
 229
 230 - **BINDING**: Shared library that be loaded by the AGL Application Framework
 231 - **BINDINGV2**: Shared library that be loaded by the AGL Application Framework.
 232  This has to be accompagnied with a JSON file named like the *${OUTPUT_NAME}-apidef* of
 233  the target that describe the API with OpenAPI syntax (e.g: *mybinding-apidef*).
 234  Or you can choose the name by setting the *CACHE* cmake variable *OPENAPI_DEF*
 235  (***CAUTION***: setting a CACHE variable is needed, or set a normal variable
 236  with the *PARENT_SCOPE* option to make it visible for the parent scope
 237  where the target is defined) JSON file will be used to generate header file
 238  using `afb-genskel` tool.
 239 - **HTDOCS**: Root directory of a web app. This target has to build its
 240  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
 241 - **DATA**: Resources used by your application. This target has to build its
 242  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
 243 - **EXECUTABLE**: Entry point of your application executed by the AGL
 244  Application Framework
 245
 246 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
 247 > stand for **Application Framework Binding**.
 248
 249 Example:
 250
 251 ```cmake
 252 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 253                 LABELS "HTDOCS"
 254                 OUTPUT_NAME dist.prod
 255         )
 256 ```
 257
 258 > **NOTE**: You doesn't need to specify an **INSTALL** command for these
 259 > targets. This is already handle by template and will be installed in the
 260 > following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
 261
 262 ## Macro reference
 263
 264 ### PROJECT_TARGET_ADD
 265
 266 Typical usage would be to add the target to your project using macro
 267 `PROJECT_TARGET_ADD` with the name of your target as parameter.
 268
 269 Example:
 270
 271 ```cmake
 272 PROJECT_TARGET_ADD(low-can-demo)
 273 ```
 274
 275 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
 276 > set with the specificied name. This variable will change at the next call
 277 > to this macros.
 278
 279 ### project_subdirs_add
 280
 281 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
 282 it will be added to your project. This could be use in an hybrid application by
 283 example where the binding lay in a sub directory.
 284
 285 Usage :
 286
 287 ```cmake
 288 project_subdirs_add()
 289 ```
 290
 291 You also can specify a globbing pattern as argument to filter which folders
 292 will be looked for.
 293
 294 To filter all directories that begin with a number followed by a dash the
 295 anything:
 296
 297 ```cmake
 298 project_subdirs_add("[0-9]-*")
 299 ```
 300
 301 ## Advanced customization
 302
 303 ### Including additionnals cmake files
 304
 305 #### Machine and system custom cmake files
 306
 307 Advanced tuning is possible using addionnals cmake files that are included
 308 automatically from some specifics locations. They are included in that order:
 309
 310 - Project CMake files normaly located in _<project-root-path>/conf.d/app-templates/cmake/cmake.d_
 311 - Home CMake files located in _$HOME/.config/app-templates/cmake.d_
 312 - System CMake files located in _/etc/app-templates/cmake.d_
 313
 314 CMake files has to be named using the following convention: `XX-common*.cmake`
 315 or `XX-${PROJECT_NAME}*.cmake`, where `XX` are numbers, `*` file name
 316 (ie. `99-common-my_customs.cmake`).
 317
 318 > **NOTE** You need to specify after numbers that indicate include order, to
 319 which project that file applies, if it applies to all project then use keyword
 320 `common`.
 321
 322 So, saying that you should be aware that every normal cmake variables used at
 323 project level could be overwrited by home or system located cmake files if
 324 variables got the same name. Exceptions are cached variables set using
 325 **CACHE** keyword:
 326
 327 Example:
 328
 329 ```cmake
 330 set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
 331 ```
 332
 333 #### OS custom cmake files
 334
 335 This is meant to personalize the project depending on the OS your are using.
 336 At the end of config.cmake, common.cmake will include lot of cmake file to
 337 customize project build depending on your plateform. It will detect your OS
 338 deducing it from file _/etc/os-release_ now as default in almost all Linux
 339 distribution.
 340
 341 So you can use the value of field **ID_LIKE** or **ID** if the
 342 first one doesn't exists and add a cmake file for that distribution in your
 343 _conf.d/cmake/_ directory or relatively to your _app-templates_ submodule path
 344 _app-templates/../cmake/_
 345
 346 Those files has to be named use the following scheme _XX-${OSRELEASE}*.cmake_
 347 where _XX_ are numbers, ${OSRELEASE} the **ID_LIKE** or **ID** field from
 348 _/etc/os-release_ file.
 349
 350 ### Include customs templated scripts
 351
 352 As well as for additionnals cmake files you can include your own templated
 353 scripts that will be passed to cmake command `configure_file`.
 354
 355 Just create your own script to the following directories:
 356
 357 - Home location in _$HOME/.config/app-templates/scripts_
 358 - System location in _/etc/app-templates/scripts_
 359
 360 Scripts only needs to use the extension `.in` to be parsed and configured by
 361 CMake command.
 362
 363 ## Autobuild script usage
 364
 365 ### Generation
 366
 367 To be integrated in the Yocto build workflow you have to generate `autobuild`
 368 scripts using _autobuild_ target.
 369
 370 To generate those scripts proceeds:
 371
 372 ```bash
 373 mkdir -p build
 374 cd build
 375 cmake .. && make autobuild
 376 ```
 377
 378 You should see _conf.d/autobuild/agl/autobuild_ file now.
 379
 380 ### Available targets
 381
 382 Here are the available targets available from _autobuild_ scripts:
 383
 384 - **clean** : clean build directory from object file and targets results.
 385 - **distclean** : delete build directory
 386 - **configure** : generate project Makefile from CMakeLists.txt files.
 387 - **build** : compile all project targets.
 388 - **package** : build and output a wgt package.
 389
 390 You can specify variables that modify the behavior of compilation using
 391 the following variables:
 392
 393 - **CONFIGURE_ARGS** : Variable used at **configure** time.
 394 - **BUILD_ARGS** : Variable used at **build** time.
 395 - **DEST** : Directory where to output ***wgt*** file.
 396
 397 Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'")
 398
 399 Usage example:
 400
 401 ```bash
 402 ./conf.d/autobuild/wgt/autobuild package DEST=/tmp
 403 ```