X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=6dce651ea858f8a37d9e90592910a1008a58d324;hb=802e2ca717e0a569bfe770dab6ff20588c78663a;hp=ebc3abf7f43a339d3618cdefedf230ec7669e05c;hpb=c1411047351d443f22f4ed31e3545b708681bcc1;p=staging%2Fxdg-launcher.git diff --git a/README.md b/README.md index ebc3abf..6dce651 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -AGL CMake template -================ +# AGL CMake template Files used to build an application, or binding, project with the AGL Application Framework. @@ -8,107 +7,272 @@ 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 +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. +You'll find usage samples here: -Typical project architecture ----------------------------------- +- [helloworld-service](https://github.com/iotbzh/helloworld-service) +- [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service) +- [high-level-viwi-service](https://github.com/iotbzh/high-level-viwi-service) +- [audio-binding](https://github.com/iotbzh/audio-binding) +- [unicens2-binding](https://github.com/iotbzh/unicens2-binding) + +## Typical project architecture A typical project architecture would be : -* \/ -* \/ -* \/packaging -* \/packaging/wgt -* \/packaging/wgt/etc -* \/\/ +```tree + +│ +├── conf.d/ +│ ├── autobuild/ +│ │ ├── agl +│ │ │ └── autobuild +│ │ ├── linux +│ │ │ └── autobuild +│ │ └── windows +│ │ └── autobuild +│ ├── app-templates/ +│ │ ├── README.md +│ │ ├── autobuild/ +│ │ │ ├── agl +│ │ │ │ └── autobuild.in +│ │ │ ├── linux +│ │ │ │ └── autobuild.in +│ │ │ └── windows +│ │ │ └── autobuild.in +│ │ ├── cmake/ +│ │ │ ├── config.cmake.sample +│ │ │ ├── export.map +│ │ │ └── macros.cmake +│ │ ├── deb/ +│ │ │ └── config.deb.in +│ │ ├── rpm/ +│ │ │ └── config.spec.in +│ │ └── wgt/ +│ │ ├── config.xml.in +│ │ ├── config.xml.in.sample +│ │ ├── icon-default.png +│ │ ├── icon-html5.png +│ │ ├── icon-native.png +│ │ ├── icon-qml.png +│ │ └── icon-service.png +│ ├── packaging/ +│ │ ├── config.spec +│ │ └── config.deb +│ ├── cmake +│ │ └── config.cmake +│ └── wgt +│ └── config.xml.in +├── +├── +│ └── +├── +│ └── +└── + └── +``` -| # | Parent | Description | Files | -| - | -------| ----------- | ----- | -| \ | - | Path to your project | Hold master CMakeLists.txt and general files of your projects. | +| # | Parent | Description | +| - | -------| ----------- | +| \ | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. | +| conf.d | \ | Holds needed files to build, install, debug, package an AGL app project | +| app-templates | conf.d | 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. SHOULD NOT BE MODIFIED MANUALLY !| +| autobuild | conf.d | Scripts generated from app-templates to build packages the same way for differents platforms.| +| cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. | +| wgt | conf.d | Contains at least config.xml.in template file modified from the sample provided in app-templates submodule for the needs of project (See config.xml.in.sample file for more details). | +| packaging | conf.d | Contains output files used to build packages. | | \ | \ | 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 | +| \ | \ | A target to build, typically library, executable, etc. | -Installation --------------- +## Usage -Use the `install.sh` script to help you install templates to your project. Here is the help for it : +### Initialization + +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 : ```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 +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates conf.d/app-templates +mkdir conf.d/cmake +cp conf.d/app-templates/cmake/config.cmake.sample conf.d/cmake/config.cmake ``` -Usage --------- +Edit the copied config.cmake file to fit your needs. -Once installed, use them by customize depending on your project with file -`\/etc/config.cmake`. +### Update app-templates submodule -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 +You may have some news bug fixes or features available from app-templates +repository that you want. To update your submodule proceed like the following: -Or with the classic way : -mkdir -p build && cd build -cmake .. && make +```bash +git submodule update --remote +git commit -s conf.d/app-templates +``` -Macro reference --------------------- +This will update the submodule to the HEAD of master branch repository. -### PROJECT_TARGET_ADD +You could just want to update at a specified repository tag or branch or commit +, here are the method to do so: -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: +```bash +cd conf.d/app-templates +# Choose one of the following depending what you want +git checkout +git checkout --detach +git checkout --detach +# Then commit +cd ../.. +git commit -s conf.d/app-templates +``` + +### Create CMake targets + +For each target part of your project, you need to use ***PROJECT_TARGET_ADD*** +to include this target to your project. + +Using it, make available the cmake variable ***TARGET_NAME*** until the next +***PROJECT_TARGET_ADD*** is invoked with a new target name. + +So, typical usage defining a target is: ```cmake -PROJECT_TARGET_ADD(low-can-demo) +PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project + +add_executable/add_library(${TARGET_NAME}.... --> defining your target sources + +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties +for macros usage + +INSTALL(TARGETS ${TARGET_NAME}.... + +populate_widget() --> add target to widget tree depending upon target properties ``` -This will make available the variable `${TARGET_NAME}` set with the specificied name. +### 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. -### search_targets +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. -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. +> ***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. -Usage : +#### 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. + +Example: ```cmake -search_targets() +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES + LABELS "HTDOCS" + OUTPUT_NAME dist.prod + ) ``` -### populate_widget +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. -Macro use to populate widget tree. To make this works you have to specify some propertiers to your target : +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. -- 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}` +## Macro reference -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. +### PROJECT_TARGET_ADD -Usage : +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 -populate_widget() +PROJECT_TARGET_ADD(low-can-demo) ``` -### build_widget +> ***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 -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 : +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 -build_widget() -```` +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]-*") +``` + +## Autobuild script usage + +### Generation + +To be integrated in the Yocto build workflow you have to generate `autobuild` +scripts using _autobuild_ target. + +To generate those scripts proceeds: + +```bash +mkdir -p build +cd build +cmake .. && make autobuild +``` + +You should see _conf.d/autobuild/agl/autobuild_ file now. + +### Available targets + +Here are the available targets available from _autobuild_ scripts: + +- **clean** : clean build directory from object file and targets results. +- **distclean** : delete build directory +- **configure** : generate project Makefile from CMakeLists.txt files. +- **build** : compile all project targets. +- **package** : build and output a wgt package. + +You can specify variables that modify the behavior of compilation using +the following variables: + +- **CONFIGURE_ARGS** : Variable used at **configure** time. +- **BUILD_ARGS** : Variable used at **build** time. +- **DEST** : Directory where to output ***wgt*** file. + +Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'") + +Usage example: + +```bash +./conf.d/autobuild/wgt/autobuild package DEST=/tmp +``` \ No newline at end of file