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 ## Typical project architecture
  22
  23 A typical project architecture would be :
  24
  25 ```tree
  26 <project-root-path>
  27 │
  28 ├── conf.d/
  29 │   ├── autobuild/
  30 │   │   ├── agl
  31 │   │   │   └── autobuild
  32 │   │   ├── linux
  33 │   │   │   └── autobuild
  34 │   │   └── windows
  35 │   │       └── autobuild
  36 │   ├── app-templates/
  37 │   │   ├── README.md
  38 │   │   ├── autobuild/
  39 │   │   │   ├── agl
  40 │   │   │   │   └── autobuild.in
  41 │   │   │   ├── linux
  42 │   │   │   │   └── autobuild.in
  43 │   │   │   └── windows
  44 │   │   │       └── autobuild.in
  45 │   │   ├── cmake/
  46 │   │   │   ├── config.cmake.sample
  47 │   │   │   ├── export.map
  48 │   │   │   └── macros.cmake
  49 │   │   ├── deb/
  50 │   │   │   └── config.deb.in
  51 │   │   ├── rpm/
  52 │   │   │   └── config.spec.in
  53 │   │   └── wgt/
  54 │   │       ├── config.xml.in
  55 │   │       ├── config.xml.in.sample
  56 │   │       ├── icon-default.png
  57 │   │       ├── icon-html5.png
  58 │   │       ├── icon-native.png
  59 │   │       ├── icon-qml.png
  60 │   │       └── icon-service.png
  61 │   ├── packaging/
  62 │   │   ├── config.spec
  63 │   │   └── config.deb
  64 │   ├── cmake
  65 │   │   └── config.cmake
  66 │   └── wgt
  67 │      └── config.xml.in
  68 ├── <libs>
  69 ├── <target>
  70 │   └── <files>
  71 ├── <target>
  72 │   └── <file>
  73 └── <target>
  74     └── <files>
  75 ```
  76
  77 | # | Parent | Description |
  78 | - | -------| ----------- |
  79 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
  80 | conf.d | \<root-path\> | Holds needed files to build, install, debug, package an AGL app project |
  81 | 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 !|
  82 | autobuild | conf.d | Scripts generated from app-templates to build packages the same way for differents platforms.|
  83 | cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. |
  84 | 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). |
  85 | packaging | conf.d | Contains output files used to build packages. |
  86 | \<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. |
  87 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
  88
  89 ## Usage
  90
  91 ### Initialization
  92
  93 To use these templates files on your project just install the reference files using
  94 **git submodule** then use `config.cmake` file to configure your project specificities :
  95
  96 ```bash
  97 git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates conf.d/app-templates
  98 mkdir conf.d/cmake
  99 cp conf.d/app-templates/cmake/config.cmake.sample conf.d/cmake/config.cmake
 100 ```
 101
 102 Edit the copied config.cmake file to fit your needs.
 103
 104 ### Update app-templates submodule
 105
 106 You may have some news bug fixes or features available from app-templates
 107 repository that you want. To update your submodule proceed like the following:
 108
 109 ```bash
 110 git submodule update --remote
 111 git commit -s conf.d/app-templates
 112 ```
 113
 114 This will update the submodule to the HEAD of master branch repository.
 115
 116 You could just want to update at a specified repository tag or branch or commit
 117 , here are the method to do so:
 118
 119 ```bash
 120 cd conf.d/app-templates
 121 # Choose one of the following depending what you want
 122 git checkout <tag_name>
 123 git checkout --detach <branch_name>
 124 git checkout --detach <commit_id>
 125 # Then commit
 126 cd ../..
 127 git commit -s conf.d/app-templates
 128 ```
 129
 130 ### Create  CMake targets
 131
 132 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
 133 to include this target to your project.
 134
 135 Using it, make available the cmake variable ***TARGET_NAME*** until the next
 136 ***PROJECT_TARGET_ADD*** is invoked with a new target name.
 137
 138 So, typical usage defining a target is:
 139
 140 ```cmake
 141 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
 142
 143 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
 144
 145 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties
 146 for macros usage
 147
 148 INSTALL(TARGETS ${TARGET_NAME}....
 149
 150 populate_widget() --> add target to widget tree depending upon target properties
 151 ```
 152
 153 ### Build a widget
 154
 155 #### config.xml.in file
 156
 157 To build a widget you need a _config.xml_ file describing what is your apps and
 158 how Application Framework would launch it. This repo provide a simple default
 159 file _config.xml.in_ that should work for simple application without
 160 interactions with others bindings.
 161
 162 It is recommanded that you use the sample one which is more complete. You can
 163 find it at the same location under the name _config.xml.in.sample_ (stunning
 164 isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it
 165 _config.xml.in_, then edit it to fit your needs.
 166
 167 > ***CAUTION*** : The default file is only meant to be use for a
 168 > simple widget app, more complicated ones which needed to export
 169 > their api, or ship several app in one widget need to use the provided
 170 > _config.xml.in.sample_ which had all new Application Framework
 171 > features explained and examples.
 172
 173 #### Using cmake template macros
 174
 175 To leverage all cmake templates features, you have to specify ***properties***
 176 on your targets. Some macros will not works without specifying which is the
 177 target type.
 178
 179 As the type is not always specified for some custom targets, like an ***HTML5***
 180 application, macros make the difference using ***LABELS*** property.
 181
 182 Example:
 183
 184 ```cmake
 185 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 186                 LABELS "HTDOCS"
 187                 OUTPUT_NAME dist.prod
 188         )
 189 ```
 190
 191 If your target output is not named as the ***TARGET_NAME***, you need to specify
 192 ***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
 193
 194 Use the ***populate_widget*** macro as latest statement of your target
 195 definition. Then at the end of your project definition you should use the macro
 196 ***build_widget*** that make an archive from the populated widget tree using the
 197 `wgtpkg-pack` Application Framework tools.
 198
 199 ## Macro reference
 200
 201 ### PROJECT_TARGET_ADD
 202
 203 Typical usage would be to add the target to your project using macro
 204 `PROJECT_TARGET_ADD` with the name of your target as parameter.
 205
 206 Example:
 207
 208 ```cmake
 209 PROJECT_TARGET_ADD(low-can-demo)
 210 ```
 211
 212 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
 213 > set with the specificied name. This variable will change at the next call
 214 > to this macros.
 215
 216 ### project_subdirs_add
 217
 218 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
 219 it will be added to your project. This could be use in an hybrid application by
 220 example where the binding lay in a sub directory.
 221
 222 Usage :
 223
 224 ```cmake
 225 project_subdirs_add()
 226 ```
 227
 228 You also can specify a globbing pattern as argument to filter which folders
 229 will be looked for.
 230
 231 To filter all directories that begin with a number followed by a dash the
 232 anything:
 233
 234 ```cmake
 235 project_subdirs_add("[0-9]-*")
 236 ```
 237
 238 ## Autobuild script usage
 239
 240 ### Generation
 241
 242 To be integrated in the Yocto build workflow you have to generate `autobuild`
 243 scripts using _autobuild_ target.
 244
 245 To generate those scripts proceeds:
 246
 247 ```bash
 248 mkdir -p build
 249 cd build
 250 cmake .. && make autobuild
 251 ```
 252
 253 You should see _conf.d/autobuild/agl/autobuild_ file now.
 254
 255 ### Available targets
 256
 257 Here are the available targets available from _autobuild_ scripts:
 258
 259 - **clean** : clean build directory from object file and targets results.
 260 - **distclean** : delete build directory
 261 - **configure** : generate project Makefile from CMakeLists.txt files.
 262 - **build** : compile all project targets.
 263 - **package** : build and output a wgt package.
 264
 265 You can specify variables that modify the behavior of compilation using
 266 the following variables:
 267
 268 - **CONFIGURE_ARGS** : Variable used at **configure** time.
 269 - **BUILD_ARGS** : Variable used at **build** time.
 270 - **DEST** : Directory where to output ***wgt*** file.
 271
 272 Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'")
 273
 274 Usage example:
 275
 276 ```bash
 277 ./conf.d/autobuild/wgt/autobuild package DEST=/tmp
 278 ```