docs/dev_guide/3_advanced_usage.md

   1 # Build a widget
   2
   3 ## config.xml.in file
   4
   5 To build a widget you need a _config.xml_ file describing what is your apps and
   6 how Application Framework would launch it. This repo provide a simple default
   7 file _config.xml.in_ that should work for simple application without
   8 interactions with others bindings.
   9
  10 It is recommanded that you use the sample one which is more complete. You can
  11 find it at the same location under the name _config.xml.in.sample_ (stunning
  12 isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it
  13 _config.xml.in_, then edit it to fit your needs.
  14
  15 > ***CAUTION*** : The default file is only meant to be use for a
  16 > simple widget app, more complicated ones which needed to export
  17 > their api, or ship several app in one widget need to use the provided
  18 > _config.xml.in.sample_ which had all new Application Framework
  19 > features explained and examples.
  20
  21 ## Using cmake template macros
  22
  23 To leverage all cmake templates features, you have to specify ***properties***
  24 on your targets. Some macros will not works without specifying which is the
  25 target type.
  26
  27 As the type is not always specified for some custom targets, like an ***HTML5***
  28 application, macros make the difference using ***LABELS*** property.
  29
  30 Choose between:
  31
  32 - **BINDING**: Shared library that be loaded by the AGL Application Framework
  33 - **BINDINGV2**: Shared library that be loaded by the AGL Application Framework.
  34  This has to be accompagnied with a JSON file named like the *${OUTPUT_NAME}-apidef* of
  35  the target that describe the API with OpenAPI syntax (e.g: *mybinding-apidef*).
  36  Or you can choose the name by setting the *CACHE* cmake variable *OPENAPI_DEF*
  37  (***CAUTION***: setting a CACHE variable is needed, or set a normal variable
  38  with the *PARENT_SCOPE* option to make it visible for the parent scope
  39  where the target is defined) JSON file will be used to generate header file
  40  using `afb-genskel` tool.
  41 - **HTDOCS**: Root directory of a web app. This target has to build its
  42  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  43 - **DATA**: Resources used by your application. This target has to build its
  44  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  45 - **EXECUTABLE**: Entry point of your application executed by the AGL
  46  Application Framework
  47
  48 Example:
  49
  50 ```cmake
  51 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
  52                 LABELS "HTDOCS"
  53                 OUTPUT_NAME dist.prod
  54         )
  55 ```
  56
  57 If your target output is not named as the ***TARGET_NAME***, you need to specify
  58 ***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro.
  59
  60 Use the ***populate_widget*** macro as latest statement of your target
  61 definition. Then at the end of your project definition you should use the macro
  62 ***build_widget*** that make an archive from the populated widget tree using the
  63 `wgtpkg-pack` Application Framework tools.
  64
  65 ## Macro reference
  66
  67 ### PROJECT_TARGET_ADD
  68
  69 Typical usage would be to add the target to your project using macro
  70 `PROJECT_TARGET_ADD` with the name of your target as parameter.
  71
  72 Example:
  73
  74 ```cmake
  75 PROJECT_TARGET_ADD(low-can-demo)
  76 ```
  77
  78 > ***NOTE***: This will make available the variable `${TARGET_NAME}`
  79 > set with the specificied name. This variable will change at the next call
  80 > to this macros.
  81
  82 ### project_subdirs_add
  83
  84 This macro will search in all subfolder any `CMakeLists.txt` file. If found then
  85 it will be added to your project. This could be use in an hybrid application by
  86 example where the binding lay in a sub directory.
  87
  88 Usage :
  89
  90 ```cmake
  91 project_subdirs_add()
  92 ```
  93
  94 You also can specify a globbing pattern as argument to filter which folders
  95 will be looked for.
  96
  97 To filter all directories that begin with a number followed by a dash the
  98 anything:
  99
 100 ```cmake
 101 project_subdirs_add("[0-9]-*")
 102 ```