From c1411047351d443f22f4ed31e3545b708681bcc1 Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Wed, 3 May 2017 10:47:33 +0200 Subject: Adding README with instruction and help Change-Id: Ic081b672ddff506f8b2a742c259f1333ff7184fa Signed-off-by: Romain Forlot --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..ebc3abf --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +AGL CMake template +================ + +Files used to build an application, or binding, project with the +AGL Application Framework. + +To build your AGL project using these templates, you have to install +them within your project and adjust compilation option in `config.cmake`. +For technical reasons, you also have to specify **cmake** target in +sub CMakeLists.txt installed. Make a globbing search to find source files +isn't recommended now to handle project build especially in a multiuser +project because CMake will not be aware of new or removed source files. + +You'll find simple usage example for different kind of target under the `examples` folder. +More advanced usage can be saw with the [CAN_signaling binding](https://github.com/iotbzh/CAN_signaling) which mix external libraries, +binding, and html5 hybrid demo application. + +Typical project architecture +---------------------------------- + +A typical project architecture would be : + +* \/ +* \/ +* \/packaging +* \/packaging/wgt +* \/packaging/wgt/etc +* \/\/ + +| # | Parent | Description | Files | +| - | -------| ----------- | ----- | +| \ | - | Path to your project | Hold master CMakeLists.txt and general files of your projects. | +| \ | \ | 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. | +| \ | \ | A sub component between: tool, binding, html5, html5-hybrid type. | ----- | +| packaging | \ | Contains folder by package type (rpms, deb, wgt...) | Directory for each packaging type. | +| wgt | packaging | Files used to build project widget that can be installed on an AGL target. | config.xml.in, icon.png.in files. | +| 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 | + +Installation +-------------- + +Use the `install.sh` script to help you install templates to your project. Here is the help for it : + +```bash +$ ./install.sh -h +The general script's help msg +Usage: ./install.sh [-b|--binding-path ] [-ha|--html5-app-path ] [-d|--(no-)debug] [-h|--help] + : Project root path + -d,--debug,--no-debug: Optional debug flag. (off by default) + -h,--help: Prints help +``` + +Usage +-------- + +Once installed, use them by customize depending on your project with file +`\/etc/config.cmake`. + +Specify manually your targets, you should look at samples provided in this repository to make yours. +Then when you are ready to build, using 'AGLBuild' that will wrap CMake build command: +./AGLBuild package + +Or with the classic way : +mkdir -p build && cd build +cmake .. && make + +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) +``` + +This will make available the variable `${TARGET_NAME}` set with the specificied name. + +### search_targets + +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 +search_targets() +``` + +### populate_widget + +Macro use to populate widget tree. To make this works you have to specify some propertiers to your target : + +- LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA* +- PREFIX : must be empty **""** when target is a *BINDING* else default prefix *lib* will be applied +- OUTPUT_NAME : Name of the output file generated, useful when generated file name is different from `${TARGET_NAME}` + +Always specify `populate_widget()` macro as the last statement, especially if you use ${TARGET_NAME} variable. Else variable will be set at wrong value with the **populate_** target name. + +Usage : + +```cmake +populate_widget() +``` + +### build_widget + +Use at project level, to gather all populated targets in the widget tree plus widget specifics files into a **WGT** archive. Generated under your `build` directory : + +Usage : + +```cmake +build_widget() +```` -- cgit 1.2.3-korg