X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=aa76f3731fb23874e52909f8821d824c424081ac;hb=f3e177c12b5f4e971240698090d2998d8727e04b;hp=65bebca037a5bc570933f0acd5be421598527108;hpb=b9a79a1e41d77ac41285500cb4353ef20955d6e1;p=apps%2Fapp-templates.git diff --git a/README.md b/README.md index 65bebca..aa76f37 100644 --- a/README.md +++ b/README.md @@ -12,59 +12,86 @@ 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 [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/ +│ ├── default/ +│ │ ├── 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.xml +│ │ ├── config.spec +│ │ └── 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 ------ -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 -r reference/etc reference/packaging -cp reference/AGLbuild +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templates conf.d/default ``` 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/default/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 ``` @@ -91,13 +118,30 @@ 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,19 +158,22 @@ 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. ### project_subdirs_add @@ -140,13 +187,21 @@ Usage : 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]-*") +``` + ### project_targets_populate 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,7 +210,7 @@ the **populate_** target name. Usage : ```cmake -populate_widget() +project_targets_populate() ``` ### project_package_build @@ -167,9 +222,9 @@ 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 +Will display the closing message configured in `config.cmake` file. Put it at the end of your project CMake file.