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