1 files changed, 307 insertions, 0 deletions
diff --git a/docs/dev_guide/advanced-usage.md b/docs/dev_guide/advanced-usage.md
new file mode 100755
index 0000000..79f7fe3
--- /dev/null
+++ b/docs/dev_guide/advanced-usage.md
@@ -0,0 +1,307 @@
+# Advanced Usage
+
+This topic describes some advanced ways of using the CMake templates.
+
+## Building a Widget
+
+To build a widget, you need a `config.xml` file that describes
+your application (widget) and how the Application Framework launches it.
+Your repository contains a simple default file named
+`config.xml.in` that should work for simple applications and should
+not require interactions with other bindings.
+
+It is also recommended that you use the sample configuration
+file that you can find in the location.
+This file is named `config.xms.in.sample` and is more complete.
+Copy the sample file to your `conf.d/wgt` directory and name it
+`config.xml.in`.
+Once you have your copy, edit the file to fit your needs.
+
+**CAUTION:** The default file is only meant to be used for a
+simple widget application.
+For more complicated applications that need to export
+their API, or ship several applications in one widget
+need to use the provided `config.xml.in.sample` file, which has
+all new Application Framework features explained and provides
+examples.
+
+## Using CMake Template Macros
+
+To leverage all CMake template features, you must specify properties
+on your targets.
+Some macros do not work unless you specify the target type.
+If you do not specify a type (e.g. a custom target such as an
+HTML5 application), the macro uses the `LABELS` property to
+determine the target type.
+
+The `LABELS` property can be set to the values shown in the
+[Target Properties](configuring-cmake.html#target-properties)
+Section.
+
+Aside from those values, the following optional values can be
+assigned to the `LABELS` property.
+These values define the resource types that make up your test materials:
+
+- **TEST-CONFIG**: JSON configuration files used by the `afb-test`
+ binding.
+ These files execute the tests.
+- **TEST-DATA**: Resources used to test your binding.
+ Minimally, you need a test plan.
+ You should also consider fixtures and any files required by your tests.
+ These required files appear as part of a separate test widget.
+- **TEST-PLUGIN**: A shared library used as a binding plugin.
+ A binding loads the library as a plugin to extend the binding's functionality.
+ You should use a special file extension when you name the library
+ by using the `SUFFIX` CMake target property.
+ If you do not choose an extension, `.ctlso` is used by default.
+- **TEST-HTDOCS**: The root directory of a web application.
+ This target has to build its directory and put its files in
+ the `${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}` directory.
+- **TEST-EXECUTABLE**: The entry point of your application executed by the AGL
+ Application Framework.
+- **TEST-LIBRARY**: An external third-party library bundled with the binding
+ for its own purpose.
+ The platform does not provide this library.
+
+Following is a mapping between `LABELS` and directories where files reside in
+the widget:
+
+- **EXECUTABLE** : \<wgtrootdir\>/bin
+- **BINDING-CONFIG** : \<wgtrootdir\>/etc
+- **BINDING** | **BINDINGV2** | **BINDINGV3** | **LIBRARY** : \<wgtrootdir\>/lib
+- **PLUGIN** : \<wgtrootdir\>/lib/plugins
+- **HTDOCS** : \<wgtrootdir\>/htdocs
+- **BINDING-DATA** : \<wgtrootdir\>/var
+- **DATA** : \<wgtrootdir\>/var
+
+Following is a mapping between test-dedicated `LABELS` and directories where
+files reside in the widget:
+
+- **TEST-EXECUTABLE** : \<wgtrootdir\>/bin
+- **TEST-CONFIG** : \<TESTwgtrootdir\>/etc
+- **TEST-PLUGIN** : \<wgtrootdir\>/lib/plugins
+- **TEST-HTDOCS** : \<wgtrootdir\>/htdocs
+- **TEST-DATA** : \<TESTwgtrootdir\>/var
+
+**TIP:** Use the prefix `afb-` (Application Framework Binding)
+with your **BINDING** targets.
+
+Following is an example that sets the `LABELS` and `OUTPUT_NAME` properties:
+
+```cmake
+SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+		LABELS "HTDOCS"
+		OUTPUT_NAME dist.prod
+	)
+```
+
+**NOTE**: You do not need to specify an **INSTALL** command for these
+  targets.
+  Installation is handled by the template and installs using the
+  following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**
+
+  Also, if you want to set and use `rpath` with your target, you should use
+  and set the target property `INSTALL_RPATH`.
+
+## Adding an External Third-Party Library
+
+You can add an external third-party library that is built, linked,
+and shipped with the project.
+Or, you can link and ship the library only with the project.
+
+### Building, Linking, and Shipping an External Library with the Project
+
+If you need to include an external library that is not shipped
+with the project, you can bundle the required library in the
+`lib` widget directory.
+
+Templates includes facilities to help you work with external
+libraries.
+A standard method is to declare as many CMake ExternalProject
+modules as you need to match the number of needed libraries.
+
+An ExternalProject module is a special CMake module that lets you define how
+to download, update, patch, configure, build, and install an external project.
+The project does not need to be a CMake project.
+Additionally, you can provide custom steps to account for special
+needs using ExternalProject step.
+See the CMake
+[ExternalProject documentation site](https://cmake.org/cmake/help/v3.5/module/ExternalProject.html?highlight=externalproject)
+for more information.
+
+Following is an example that includes the `mxml` library for the
+[unicens2-binding](https://github.com/iotbzh/unicens2-binding)
+project:
+
+```cmake
+set(MXML external-mxml)
+set(MXML_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/mxml)
+ExternalProject_Add(${MXML}
+    GIT_REPOSITORY https://github.com/michaelrsweet/mxml.git
+    GIT_TAG release-2.10
+    SOURCE_DIR ${MXML_SOURCE_DIR}
+    CONFIGURE_COMMAND ./configure --build x86_64 --host aarch64
+    BUILD_COMMAND make libmxml.so.1.5
+    BUILD_IN_SOURCE 1
+    INSTALL_COMMAND ""
+)
+
+PROJECT_TARGET_ADD(mxml)
+
+add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
+
+SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+    LABELS LIBRARY
+    IMPORTED_LOCATION ${MXML_SOURCE_DIR}/libmxml.so.1
+    INTERFACE_INCLUDE_DIRECTORIES ${MXML_SOURCE_DIR}
+)
+
+add_dependencies(${TARGET_NAME} ${MXML})
+```
+
+The example defines an external project that drives the building of the library.
+The example also defines a new CMake target whose type is **IMPORTED**.
+The **IMPORTED** target type indicates the target has yet to be built using
+CMake but is available at the location defined using the **IMPORTED_LOCATION**
+target property.
+
+You might want to build the library as **SHARED** or **STATIC** depending on your needs
+and goals.
+Next, the example only has to modify the external project configure step and change
+the filename used by **IMPORTED** library target defined after external project.
+
+The target's **LABELS** property is set to **LIBRARY** to ship it in the widget.
+
+In this example, the Unicens project also needs header
+information from this library.
+Consequently, the **INTERFACE_INCLUDE_DIRECTORIES** target property
+is used.
+Setting that property when another target links to that imported target
+allows access to included directories.
+
+Finally, the example binds the target to the external project
+by using a CMake dependency.
+
+The target can now be linked and used like any other CMake target.
+
+### Link and Ship an External Library with the Project
+
+If you already have a binary version of the library that you want to use and you
+cannot or do not want to build the library, you can use the **IMPORTED**
+library target.
+
+To illustrate, consider the same example in the previous section.
+Following are the relevant modifications:
+
+```cmake
+PROJECT_TARGET_ADD(mxml)
+
+add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL)
+
+SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES
+    LABELS LIBRARY
+    IMPORTED_LOCATION /path_to_library/libmxml.so.1
+    INTERFACE_INCLUDE_DIRECTORIES /path_to_mxml/include/dir
+)
+```
+
+In the previous example, notice the changes to the
+`IMPORTED_LOCATION` and `INTERFACE_INCLUDE_DIRECTORIES` statements.
+These locate the binary version of the library.
+
+Finally, you can link any other library or executable target with this imported
+library just as you would for any other target.
+
+## Macro Reference
+
+Following are several macros that are useful for advanced CMake usage.
+
+### PROJECT_TARGET_ADD
+
+This macro adds the target to your project.
+Following is a typical example that adds the target to your project.
+You need to provide the name of your target as the macro's parameter:
+
+Example:
+
+```cmake
+PROJECT_TARGET_ADD(low-can-demo)
+```
+
+The macro makes the variable `${TARGET_NAME}` available and it is defined
+using the specified name (e.g. `low-can-demo`).
+The variable changes each time the `PROJECT_TARGET_ADD` macro is called.
+
+### project_subdirs_add
+
+This macro searches within specified subfolders of the CMake project for
+any `CMakeLists.txt` file.
+If the file is found, it is added to your project.
+You can use this macro in a hybrid application (e.g. where the binding
+exists in a subfolder).
+
+The following example searches within all subfolders:
+
+Usage :
+
+```cmake
+project_subdirs_add()
+```
+
+You might want to restrict the subfolders being searched.
+If so, you can specify a
+[globbing](https://en.wikipedia.org/wiki/Glob_(programming)) pattern
+as the argument.
+Doing so effectively creates a search filter.
+
+Following is an example that specifies all directories that begin
+with a number, are followed by the dash character, and then followed
+by any characters:
+
+```cmake
+project_subdirs_add("[0-9]-*")
+```
+
+### set_openapi_filename
+
+This macro is used with a **BINDINGV2** target and defines the
+binding definition filename.
+You can use it to also define a relative path to
+the current `CMakeLists.txt` file.
+
+If you do not use this macro to specify the name of your definition file,
+the default one is used, which is `${OUTPUT_NAME}-apidef` and uses
+**OUTPUT_NAME** as the [target property].
+
+**CAUTION** When specifying the binding definition filename,
+you must not use the file's extension as part of the name.
+Following is an example:
+
+```cmake
+set_openapi_filename('binding/mybinding_definition')
+```
+
+[target property]: https://cmake.org/cmake/help/v3.6/prop_tgt/OUTPUT_NAME.html "OUTPUT_NAME property documentation"
+
+### add_input_files
+
+This macro creates a custom target dedicated for HTML5 and data resource files.
+The macro provides syntax and schema verification for different languages that
+include LUA, JSON and XML.
+
+Alongside the macro are tools used to check files.
+You can configure the tools by setting the
+following variables:
+
+- XML_CHECKER: Uses **xmllint** that is provided with major linux distributions.
+- LUA_CHECKER: Uses **luac** that is provided with major linux distributions.
+- JSON_CHECKER: Currently, not used by any tools.
+
+Following is an example:
+
+```cmake
+add_input_file("${MY_FILES_LIST}")
+```
+
+**NOTE**: If an issue occurs during the "check" step of the macro,
+the build halts.