X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=b28b90a21f6de1a1f759fc629226b84e8d1fc29a;hb=a8103b6f53a89fcbaeea225ab1a4d6624b242176;hp=0c0462d26dfc08a362a784fa0a5ac5e63e309506;hpb=73db33eea16f50935f321f7bf5201a1ffde09003;p=staging%2Fxdg-launcher.git diff --git a/README.md b/README.md index 0c0462d..b28b90a 100644 --- a/README.md +++ b/README.md @@ -11,60 +11,91 @@ 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. +You'll find simple usage example for different kind of target under the +`examples` folder. More advanced usage can be saw with the +[low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service) +which mix external libraries, binding. Typical project architecture ------------------------------ +--------------------------------- A typical project architecture would be : -* \/ -* \/ -* \/packaging -* \/packaging/wgt -* \/packaging/wgt/etc -* \/\/ +```tree + +│ +├── conf.d/ +│ ├── app-templates/ +│ │ ├── README.md +│ │ ├── autobuild/ +│ │ │ ├── agl +│ │ │ │ └── autobuild.sh +│ │ │ ├── linux +│ │ │ │ └── autobuild.sh +│ │ │ └── windows +│ │ │ └── autobuild.bat +│ │ ├── 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 | \ | 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. | +| app-templates | 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 ------ -Install the reference files to the root path of your project, then once -installed, customize your project with file `\/etc/config.cmake`. - -Typically, to copy files use a command like: +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 -cp reference/etc reference/packaging -cp reference/AGLbuild +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates ``` 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` +repository to make yours. Then when you are ready to build, using `autobuild` that will wrap CMake build command: ```bash -./AGLbuild package +./conf.d/app-templates/autobuild/agl/autobuild.mk 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 : ```bash -mkdir -p build && cd build +mkdir -p build +cd build cmake .. && make ``` @@ -84,20 +115,38 @@ 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 +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 +### Build a widget + +#### config.xml.in file + +To build a widget you need to configure file _config.xml_. This repo +provide a simple default file _config.xml.in_ that will be configured using the +variable set in _config.cmake_ file. + +> ***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. + +#### Using cmake template 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*** + +As the type is not always specified for some custom targets, like an ***HTML5*** application, macros make the difference using ***LABELS*** property. +Example: + ```cmake SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES LABELS "HTDOCS" @@ -114,21 +163,24 @@ definition. Then at the end of your project definition you should use the macro `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: +`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. +> ***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. -### 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 @@ -137,16 +189,29 @@ example where the binding lay in a sub directory. Usage : ```cmake -search_targets() +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]-*") ``` -### populate_widget +### project_targets_populate -Macro use to populate widget tree. To make this works you have to specify some properties 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}` +* 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 @@ -155,10 +220,10 @@ the **populate_** target name. Usage : ```cmake -populate_widget() +project_targets_populate() ``` -### 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` @@ -167,5 +232,10 @@ directory : Usage : ```cmake -build_widget() +project_package_build() ``` + +### project_closing_message + +Will display the closing message configured in `config.cmake` file. Put it at +the end of your project CMake file. \ No newline at end of file