From b1bb356be470cfc10a0d9457166ad21af0bd3f19 Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Tue, 4 Jul 2017 19:00:40 +0200 Subject: Update doc & use gitbook to enhance doc generation Change-Id: If42c916f7664ea67b818a21b8f50c66c41e11f89 Signed-off-by: Romain Forlot --- docs/dev_guide/3_advanced_usage.md | 92 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/dev_guide/3_advanced_usage.md (limited to 'docs/dev_guide/3_advanced_usage.md') diff --git a/docs/dev_guide/3_advanced_usage.md b/docs/dev_guide/3_advanced_usage.md new file mode 100644 index 0000000..8994b41 --- /dev/null +++ b/docs/dev_guide/3_advanced_usage.md @@ -0,0 +1,92 @@ +# Build a widget + +## config.xml.in file + +To build a widget you need a _config.xml_ file describing what is your apps and +how Application Framework would launch it. This repo provide a simple default +file _config.xml.in_ that should work for simple application without +interactions with others bindings. + +It is recommanded that you use the sample one which is more complete. You can +find it at the same location under the name _config.xml.in.sample_ (stunning +isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it +_config.xml.in_, then edit it to fit your needs. + +> ***CAUTION*** : The default file is only meant to be use for a +> simple widget app, more complicated ones which needed to export +> their api, or ship several app in one widget need to use the provided +> _config.xml.in.sample_ which had all new Application Framework +> features explained and examples. + +## Using cmake template macros + +To leverage all cmake templates features, you have to specify ***properties*** +on your targets. Some macros will not works without specifying which is the +target type. + +As the type is not always specified for some custom targets, like an ***HTML5*** +application, macros make the difference using ***LABELS*** property. + +Choose between: + +- **BINDING**: Shared library that be loaded by the AGL Application Framework +- **HTDOCS**: Root directory of a web app +- **DATA**: Resources used by your application +- **EXECUTABLE**: Entry point of your application executed by the AGL + Application Framework + +Example: + +```cmake +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES + LABELS "HTDOCS" + OUTPUT_NAME dist.prod + ) +``` + +If your target output is not named as the ***TARGET_NAME***, you need to specify +***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro. + +Use the ***populate_widget*** macro as latest statement of your target +definition. Then at the end of your project definition you should use the macro +***build_widget*** that make an archive from the populated widget tree using the +`wgtpkg-pack` Application Framework tools. + +## Macro reference + +### PROJECT_TARGET_ADD + +Typical usage would be to add the target to your project using macro +`PROJECT_TARGET_ADD` with the name of your target as parameter. + +Example: + +```cmake +PROJECT_TARGET_ADD(low-can-demo) +``` + +> ***NOTE***: This will make available the variable `${TARGET_NAME}` +> set with the specificied name. This variable will change at the next call +> to this macros. + +### project_subdirs_add + +This macro will search in all subfolder any `CMakeLists.txt` file. If found then +it will be added to your project. This could be use in an hybrid application by +example where the binding lay in a sub directory. + +Usage : + +```cmake +project_subdirs_add() +``` + +You also can specify a globbing pattern as argument to filter which folders +will be looked for. + +To filter all directories that begin with a number followed by a dash the +anything: + +```cmake +project_subdirs_add("[0-9]-*") +``` -- cgit 1.2.3-korg