X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=d4dc1ef65626162d8b4ad2e0fbe31471cd5c19a0;hb=2de0f6ce0d934bad9a80908bbc4a93a837f20eeb;hp=ebc3abf7f43a339d3618cdefedf230ec7669e05c;hpb=c1411047351d443f22f4ed31e3545b708681bcc1;p=staging%2Fxdg-launcher.git diff --git a/README.md b/README.md index ebc3abf..d4dc1ef 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ AGL CMake template -================ +================== Files used to build an application, or binding, project with the AGL Application Framework. @@ -8,94 +8,179 @@ 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. +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 -* \/\/ +```tree + +│ +├── conf.d/ +│ ├── default/ +│ │ ├── cmake/ +│ │ │ ├── config.cmake.sample +│ │ │ ├── export.map +│ │ │ └── macros.cmake +│ │ ├── deb/ +│ │ │ └── config.deb.in +│ │ ├── rpm/ +│ │ │ └── config.spec.in +│ │ └── wgt/ +│ │ ├── config.xml.in +│ │ └── icon.png +│ ├── packaging/ +│ │ ├── config.xml +│ │ ├── config.spec +│ │ ├── icon.png +│ │ └── config.deb +│ ├── autobuild/ +│ │ ├── agl +│ │ │ └── autobuild.sh +│ │ ├── linux +│ │ │ └── autobuild.sh +│ │ └── windows +│ │ └── autobuild.bat +│ ├── README.md +│ └── config.cmake +├── +├── +├── +└── +``` -| # | 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 | \ | 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. | +| default | conf.d | Holds examples files and cmake macros used to build packages | +| packaging | conf.d | Contains output files used to build packages. | +| autobuild | conf.d | Scripts used to build packages the same way for differents platforms. | | \ | \ | 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. | + +Usage +------ -Installation --------------- +Install the reference files to the root path of your project, then once +installed, customize your project with file `\/etc/config.cmake`. -Use the `install.sh` script to help you install templates to your project. Here is the help for it : +Typically, to copy files use a command like: ```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 +cp -r reference/etc reference/packaging +cp reference/AGLbuild ``` -Usage --------- +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: -Once installed, use them by customize depending on your project with file -`\/etc/config.cmake`. +```bash +./build.sh package +``` -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 +AGLbuild is not mandatory to build your project by will be used by `bitbake` +tool when building application from a Yocto workflow that use this entry point +to get its widget file. -Or with the classic way : +Or with the classic way : + +```bash mkdir -p build && cd build cmake .. && make +``` + +### Create a CMake target + +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. Be aware that ***populate_widget*** macro will also use +***PROJECT_TARGET_ADD*** so ***TARGET_NAME*** will change after using +***populate_widget*** macro. + +So, typical usage defining a target is: + +```cmake +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 +``` + +### Build a widget using provided macros + +To leverage all macros 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 target, like an ***HTML5*** +application, macros make the difference using ***LABELS*** property. + +```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: +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. +This will make available the variable `${TARGET_NAME}` set with the specificied +name. -### search_targets +### 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. +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 : +Usage : ```cmake -search_targets() +project_subdirs_add() ``` -### populate_widget +### project_targets_populate -Macro use to populate widget tree. To make this works you have to specify some propertiers to your target : +Macro use to populate widget tree. To make this works you have to specify some properties 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. +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 : @@ -103,12 +188,18 @@ Usage : populate_widget() ``` -### build_widget +### project_package_build -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 : +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() -```` +``` + +### project_closing_message + +Will display the closing message configured in `config.cmake` file. Put it at the end of your project CMake file.