README.md

   1 AGL CMake template
   2 ==================
   3
   4 Files used to build an application, or binding, project with the
   5 AGL Application Framework.
   6
   7 To build your AGL project using these templates, you have to install
   8 them within your project and adjust compilation option in `config.cmake`.
   9 For technical reasons, you also have to specify **cmake** target in
  10 sub CMakeLists.txt installed. Make a globbing search to find source files
  11 isn't recommended now to handle project build especially in a multiuser
  12 project because CMake will not be aware of new or removed source files.
  13
  14 You'll find simple usage example for different kind of target under the
  15 `examples` folder. More advanced usage can be saw with the
  16 [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service)
  17 which mix external libraries, binding.
  18
  19 Typical project architecture
  20 ---------------------------------
  21
  22 A typical project architecture would be :
  23
  24 ```tree
  25 <project-root-path>
  26 │
  27 ├── conf.d/
  28 │   ├── app-templates/
  29 │   │   ├── README.md
  30 │   │   ├── autobuild/
  31 │   │   │   ├── agl
  32 │   │   │   │   └── autobuild.sh
  33 │   │   │   ├── linux
  34 │   │   │   │   └── autobuild.sh
  35 │   │   │   └── windows
  36 │   │   │       └── autobuild.bat
  37 │   │   ├── cmake/
  38 │   │   │   ├── config.cmake.sample
  39 │   │   │   ├── export.map
  40 │   │   │   └── macros.cmake
  41 │   │   ├── deb/
  42 │   │   │   └── config.deb.in
  43 │   │   ├── rpm/
  44 │   │   │   └── config.spec.in
  45 │   │   └── wgt/
  46 │   │       ├── config.xml.in
  47 │   │       ├── config.xml.in.sample
  48 │   │       ├── icon-default.png
  49 │   │       ├── icon-html5.png
  50 │   │       ├── icon-native.png
  51 │   │       ├── icon-qml.png
  52 │   │       └── icon-service.png
  53 │   ├── packaging/
  54 │   │   ├── config.spec
  55 │   │   └── config.deb
  56 │   ├── cmake
  57 │   │   └── config.cmake
  58 │   └── wgt
  59 │      └── config.xml.in
  60 ├── <libs>
  61 ├── <target>
  62 ├── <target>
  63 └── <target>
  64 ```
  65
  66 | # | Parent | Description |
  67 | - | -------| ----------- |
  68 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
  69 | conf.d | \<root-path\> | 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. |
  70 | app-templates | conf.d | Holds examples files and cmake macros used to build packages |
  71 | packaging | conf.d | Contains output files used to build packages. |
  72 | autobuild | conf.d | Scripts used to build packages the same way for differents platforms. |
  73 | \<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. |
  74 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
  75
  76 Usage
  77 ------
  78
  79 To use these templates files on your project just install the reference files using
  80 **git submodule** then use `config.cmake` file to configure your project specificities :
  81
  82 ```bash
  83 git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates
  84 ```
  85
  86 Specify manually your targets, you should look at samples provided in this
  87 repository to make yours. Then when you are ready to build, using `autobuild`
  88 that will wrap CMake build command:
  89
  90 ```bash
  91 ./conf.d/app-templates/autobuild/agl/autobuild.mk package
  92 ```
  93
  94 Or with the classic way :
  95
  96 ```bash
  97 mkdir -p build
  98 cd build
  99 cmake .. && make
 100 ```
 101
 102 ### Create a CMake target
 103
 104 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
 105 to include this target to your project, using it make available the cmake
 106 variable ***TARGET_NAME*** until the next ***PROJECT_TARGET_ADD*** is invoked
 107 with a new target name. Be aware that ***populate_widget*** macro will also use
 108 ***PROJECT_TARGET_ADD*** so ***TARGET_NAME*** will change after using
 109 ***populate_widget*** macro.
 110
 111 So, typical usage defining a target is:
 112
 113 ```cmake
 114 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
 115
 116 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
 117
 118 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties
 119 for macros usage
 120
 121 INSTALL(TARGETS ${TARGET_NAME}....
 122
 123 populate_widget() --> add target to widget tree depending upon target properties
 124 ```
 125
 126 ### Build a widget
 127
 128 #### config.xml.in file
 129
 130 To build a widget you need to configure file _config.xml_. This repo
 131 provide a simple default file _config.xml.in_ that will be configured using the
 132 variable set in _config.cmake_  file.
 133
 134 > ***CAUTION*** : The default file is only meant to be use for a
 135 > simple widget app, more complicated ones which needed to export
 136 > their api, or ship several app in one widget need to use the provided
 137 > _config.xml.in.sample_ which had all new Application Framework
 138 > features explained and examples.
 139
 140 #### Using cmake template macros
 141
 142 To leverage all macros features, you have to specify ***properties*** on your
 143 targets. Some macros will not works without specifying which is the target type.
 144
 145 As the type is not always specified for some custom targets, like an ***HTML5***
 146 application, macros make the difference using ***LABELS*** property.
 147
 148 Example:
 149
 150 ```cmake
 151 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 152                 LABELS "HTDOCS"
 153                 OUTPUT_NAME dist.prod
 154         )
 155 ```
 156
 157 If your target output is not named as the ***TARGET_NAME***, you need to specify
 158 ***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
 159
 160 Use the ***populate_widget*** macro as latest statement of your target
 161 definition. Then at the end of your project definition you should use the macro
 162 ***build_widget*** that make an archive from the populated widget tree using the
 163 `wgtpkg-pack` Application Framework tools.
 164
 165 Macro reference
 166 --------------------
 167
 168 ### PROJECT_TARGET_ADD
 169
 170 Typical usage would be to add the target to your project using macro
 171 `PROJECT_TARGET_ADD` with the name of your target as parameter.
 172
 173 Example:
 174
 175 ```cmake
 176 PROJECT_TARGET_ADD(low-can-demo)
 177 ```
 178
 179 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
 180 > set with the specificied name. This variable will change at the next call
 181 > to this macros.
 182
 183 ### project_subdirs_add
 184
 185 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
 186 it will be added to your project. This could be use in an hybrid application by
 187 example where the binding lay in a sub directory.
 188
 189 Usage :
 190
 191 ```cmake
 192 project_subdirs_add()
 193 ```
 194
 195 You also can specify a globbing pattern as argument to filter which folders
 196 will be looked for.
 197
 198 To filter all directories that begin with a number followed by a dash the
 199 anything:
 200
 201 ```cmake
 202 project_subdirs_add("[0-9]-*")
 203 ```
 204
 205 ### project_targets_populate
 206
 207 Macro use to populate widget tree. To make this works you have to specify some
 208 properties to your target :
 209
 210 * LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA*
 211 * PREFIX : must be empty **""** when target is a *BINDING* else default prefix
 212  *lib* will be applied
 213 * OUTPUT_NAME : Name of the output file generated, useful when generated file
 214  name is different from `${TARGET_NAME}`
 215
 216 Always specify  `populate_widget()` macro as the last statement, especially if
 217 you use ${TARGET_NAME} variable. Else variable will be set at wrong value with
 218 the **populate_** target name.
 219
 220 Usage :
 221
 222 ```cmake
 223 project_targets_populate()
 224 ```
 225
 226 ### project_package_build
 227
 228 Use at project level, to gather all populated targets in the widget tree plus
 229 widget specifics files into a **WGT** archive. Generated under your `build`
 230 directory :
 231
 232 Usage :
 233
 234 ```cmake
 235 project_package_build()
 236 ```
 237
 238 ### project_closing_message
 239
 240 Will display the closing message configured in `config.cmake` file. Put it at
 241 the end of your project CMake file.