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 `examples` folder.
  15 More advanced usage can be saw with the [CAN_signaling binding](https://github.com/iotbzh/CAN_signaling)
  16 which mix external libraries, binding, and html5 hybrid demo application.
  17
  18 Typical project architecture
  19 -----------------------------
  20
  21 A typical project architecture would be :
  22
  23 ```tree
  24 <project-root-path>
  25 │
  26 ├── conf.d/
  27 │   ├── default/
  28 │   │   ├── cmake/
  29 │   │   │   ├── config.cmake.sample
  30 │   │   │   ├── export.map
  31 │   │   │   └── macros.cmake
  32 │   │   ├── deb/
  33 │   │   │   └── config.deb.in
  34 │   │   ├── rpm/
  35 │   │   │   └── config.spec.in
  36 │   │   └── wgt/
  37 │   │       ├── config.xml.in
  38 │   │       └── icon.png
  39 │   ├── packaging/
  40 │   │   ├── config.xml
  41 │   │   ├── config.spec
  42 │   │   ├── icon.png
  43 │   │   └── config.deb
  44 │   ├── autobuild/
  45 │   │   ├── agl
  46 │   │   │   └── autobuild.sh
  47 │   │   ├── linux
  48 │   │   │   └── autobuild.sh
  49 │   │   └── windows
  50 │   │       └── autobuild.bat
  51 │   ├── README.md
  52 │   └── config.cmake
  53 ├── <libs>
  54 ├── <target>
  55 ├── <target>
  56 └── <target>
  57 ```
  58
  59 | # | Parent | Description |
  60 | - | -------| ----------- |
  61 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
  62 | 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. |
  63 | default | conf.d | Holds examples files and cmake macros used to build packages |
  64 | packaging | conf.d | Contains output files used to build packages. |
  65 | autobuild | conf.d | Scripts used to build packages the same way for differents platforms. |
  66 | \<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. |
  67 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
  68
  69 Usage
  70 ------
  71
  72 Install the reference files to the root path of your project, then once
  73 installed, customize your project with file `\<root-path\>/etc/config.cmake`.
  74
  75 Typically, to copy files use a command like:
  76
  77 ```bash
  78 cp -r reference/etc reference/packaging <root-path-to-your-project>
  79 cp reference/AGLbuild <root-path-to-your-project>
  80 ```
  81
  82 Specify manually your targets, you should look at samples provided in this
  83 repository to make yours. Then when you are ready to build, using `AGLbuild`
  84 that will wrap CMake build command:
  85
  86 ```bash
  87 ./build.sh package
  88 ```
  89
  90 AGLbuild is not mandatory to build your project by will be used by `bitbake`
  91 tool when building application from a Yocto workflow that use this entry point
  92 to get its widget file.
  93
  94 Or with the classic way :
  95
  96 ```bash
  97 mkdir -p build && cd build
  98 cmake .. && make
  99 ```
 100
 101 ### Create a CMake target
 102
 103 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
 104 to include this target to your project, using it make available the cmake
 105 variable ***TARGET_NAME*** until the next ***PROJECT_TARGET_ADD*** is invoked
 106 with a new target name. Be aware that ***populate_widget*** macro will also use
 107 ***PROJECT_TARGET_ADD*** so ***TARGET_NAME*** will change after using
 108 ***populate_widget*** macro.
 109
 110 So, typical usage defining a target is:
 111
 112 ```cmake
 113 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
 114
 115 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
 116
 117 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties for macros usage
 118
 119 INSTALL(TARGETS ${TARGET_NAME}....
 120
 121 populate_widget() --> add target to widget tree depending upon target properties
 122 ```
 123
 124 ### Build a widget using provided macros
 125
 126 To leverage all macros features, you have to specify ***properties*** on your
 127 targets. Some macros will not works without specifying which is the target type.
 128 As the type is not always specified for some custom target, like an ***HTML5***
 129 application, macros make the difference using ***LABELS*** property.
 130
 131 ```cmake
 132 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
 133                 LABELS "HTDOCS"
 134                 OUTPUT_NAME dist.prod
 135         )
 136 ```
 137
 138 If your target output is not named as the ***TARGET_NAME***, you need to specify
 139 ***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
 140
 141 Use the ***populate_widget*** macro as latest statement of your target
 142 definition. Then at the end of your project definition you should use the macro
 143 ***build_widget*** that make an archive from the populated widget tree using the
 144 `wgtpkg-pack` Application Framework tools.
 145
 146 Macro reference
 147 ----------------
 148
 149 ### PROJECT_TARGET_ADD
 150
 151 Typical usage would be to add the target to your project using macro
 152 `PROJECT_TARGET_ADD` with the name of your target as parameter. Example:
 153
 154 ```cmake
 155 PROJECT_TARGET_ADD(low-can-demo)
 156 ```
 157
 158 This will make available the variable `${TARGET_NAME}` set with the specificied
 159 name.
 160
 161 ### project_subdirs_add
 162
 163 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
 164 it will be added to your project. This could be use in an hybrid application by
 165 example where the binding lay in a sub directory.
 166
 167 Usage :
 168
 169 ```cmake
 170 project_subdirs_add()
 171 ```
 172
 173 ### project_targets_populate
 174
 175 Macro use to populate widget tree. To make this works you have to specify some properties to your target :
 176
 177 - LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA*
 178 - PREFIX : must be empty **""** when target is a *BINDING* else default prefix *lib* will be applied
 179 - OUTPUT_NAME : Name of the output file generated, useful when generated file name is different from `${TARGET_NAME}`
 180
 181 Always specify  `populate_widget()` macro as the last statement, especially if
 182 you use ${TARGET_NAME} variable. Else variable will be set at wrong value with
 183 the **populate_** target name.
 184
 185 Usage :
 186
 187 ```cmake
 188 populate_widget()
 189 ```
 190
 191 ### project_package_build
 192
 193 Use at project level, to gather all populated targets in the widget tree plus
 194 widget specifics files into a **WGT** archive. Generated under your `build`
 195 directory :
 196
 197 Usage :
 198
 199 ```cmake
 200 build_widget()
 201 ```
 202
 203 ### project_closing_message
 204
 205 Will display the closing message configured in `config.cmake` file. Put it at the end of your project CMake file.