4 Files used to build an application, or binding, project with the
5 AGL Application Framework.
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.
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 [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service)
16 which mix external libraries, binding.
18 Typical project architecture
19 ---------------------------------
21 A typical project architecture would be :
31 │ │ │ │ └── autobuild.sh
33 │ │ │ │ └── autobuild.sh
35 │ │ │ └── autobuild.bat
37 │ │ │ ├── config.cmake.sample
39 │ │ │ └── macros.cmake
41 │ │ │ └── config.deb.in
43 │ │ │ └── config.spec.in
46 │ │ ├── config.xml.in.sample
47 │ │ ├── icon-default.png
48 │ │ ├── icon-html5.png
49 │ │ ├── icon-native.png
51 │ │ └── icon-service.png
65 | # | Parent | Description |
66 | - | -------| ----------- |
67 | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. |
68 | 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. |
69 | app-templates | conf.d | Holds examples files and cmake macros used to build packages |
70 | packaging | conf.d | Contains output files used to build packages. |
71 | autobuild | conf.d | Scripts used to build packages the same way for differents platforms. |
72 | \<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. |
73 | \<target\> | \<root-path\> | A target to build, typically library, executable, etc. |
78 To use these templates files on your project just install the reference files using **git submodule** then use `config.cmake` file to configure your project specificities :
81 git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templates conf.d/app-templates
84 Specify manually your targets, you should look at samples provided in this
85 repository to make yours. Then when you are ready to build, using `autobuild`
86 that will wrap CMake build command:
89 ./conf.d/app-templates/autobuild/agl/autobuild.mk package
92 Or with the classic way :
100 ### Create a CMake target
102 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
103 to include this target to your project, using it make available the cmake
104 variable ***TARGET_NAME*** until the next ***PROJECT_TARGET_ADD*** is invoked
105 with a new target name. Be aware that ***populate_widget*** macro will also use
106 ***PROJECT_TARGET_ADD*** so ***TARGET_NAME*** will change after using
107 ***populate_widget*** macro.
109 So, typical usage defining a target is:
112 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
114 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
116 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties for macros usage
118 INSTALL(TARGETS ${TARGET_NAME}....
120 populate_widget() --> add target to widget tree depending upon target properties
125 #### config.xml.in file
127 To build a widget you need to configure file _config.xml_. This repo
128 provide a simple default file _config.xml.in_ that will be configured using the
129 variable set in _config.cmake_ file.
131 > ***CAUTION*** : The default file is only meant to be use for a
132 > simple widget app, more complicated ones which needed to export
133 > their api, or ship several app in one widget need to use the provided
134 > _config.xml.in.sample_ which had all new Application Framework
135 > features explained and examples.
137 #### Using cmake template macros
139 To leverage all macros features, you have to specify ***properties*** on your
140 targets. Some macros will not works without specifying which is the target type.
142 As the type is not always specified for some custom targets, like an ***HTML5***
143 application, macros make the difference using ***LABELS*** property.
148 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
150 OUTPUT_NAME dist.prod
154 If your target output is not named as the ***TARGET_NAME***, you need to specify
155 ***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
157 Use the ***populate_widget*** macro as latest statement of your target
158 definition. Then at the end of your project definition you should use the macro
159 ***build_widget*** that make an archive from the populated widget tree using the
160 `wgtpkg-pack` Application Framework tools.
165 ### PROJECT_TARGET_ADD
167 Typical usage would be to add the target to your project using macro
168 `PROJECT_TARGET_ADD` with the name of your target as parameter.
173 PROJECT_TARGET_ADD(low-can-demo)
176 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
177 > set with the specificied name. This variable will change at the next call
180 ### project_subdirs_add
182 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
183 it will be added to your project. This could be use in an hybrid application by
184 example where the binding lay in a sub directory.
189 project_subdirs_add()
192 You also can specify a globbing pattern as argument to filter which folders will be looked for.
194 To filter all directories that begin with a number followed by a dash the anything:
197 project_subdirs_add("[0-9]-*")
200 ### project_targets_populate
202 Macro use to populate widget tree. To make this works you have to specify some properties to your target :
204 * LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA*
205 * PREFIX : must be empty **""** when target is a *BINDING* else default prefix *lib* will be applied
206 * OUTPUT_NAME : Name of the output file generated, useful when generated file name is different from `${TARGET_NAME}`
208 Always specify `populate_widget()` macro as the last statement, especially if
209 you use ${TARGET_NAME} variable. Else variable will be set at wrong value with
210 the **populate_** target name.
215 project_targets_populate()
218 ### project_package_build
220 Use at project level, to gather all populated targets in the widget tree plus
221 widget specifics files into a **WGT** archive. Generated under your `build`
227 project_package_build()
230 ### project_closing_message
232 Will display the closing message configured in `config.cmake` file. Put it at the end of your project CMake file.