X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=README.md;h=6dce651ea858f8a37d9e90592910a1008a58d324;hb=802e2ca717e0a569bfe770dab6ff20588c78663a;hp=f49c9cdf077dd4f30da5f078d12fdb48aa3a9a27;hpb=5a83e479e50eff90f1d98bd74a9f933a6340e3f6;p=staging%2Fxdg-launcher.git diff --git a/README.md b/README.md index f49c9cd..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. @@ -11,12 +10,15 @@ 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 [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service) -which mix external libraries, binding. +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 : @@ -24,15 +26,22 @@ A typical project architecture would be : │ ├── conf.d/ +│ ├── autobuild/ +│ │ ├── agl +│ │ │ └── autobuild +│ │ ├── linux +│ │ │ └── autobuild +│ │ └── windows +│ │ └── autobuild │ ├── app-templates/ │ │ ├── README.md │ │ ├── autobuild/ │ │ │ ├── agl -│ │ │ │ └── autobuild.sh +│ │ │ │ └── autobuild.in │ │ │ ├── linux -│ │ │ │ └── autobuild.sh +│ │ │ │ └── autobuild.in │ │ │ └── windows -│ │ │ └── autobuild.bat +│ │ │ └── autobuild.in │ │ ├── cmake/ │ │ │ ├── config.cmake.sample │ │ │ ├── export.map @@ -58,53 +67,73 @@ A typical project architecture would be : │ └── config.xml.in ├── ├── +│ └── ├── +│ └── └── + └── ``` | # | 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 | +| 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. | -| 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 target to build, typically library, executable, etc. | -Usage ------- +## Usage + +### 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 : +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 -git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templates conf.d/app-templates +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 ``` -Specify manually your targets, you should look at samples provided in this -repository to make yours. Then when you are ready to build, using `autobuild` -that will wrap CMake build command: +Edit the copied config.cmake file to fit your needs. + +### Update app-templates submodule + +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: ```bash -./conf.d/app-templates/autobuild/agl/autobuild.mk package +git submodule update --remote +git commit -s conf.d/app-templates ``` -Or with the classic way : +This will update the submodule to the HEAD of master branch repository. + +You could just want to update at a specified repository tag or branch or commit +, here are the method to do so: ```bash -mkdir -p build -cd build -cmake .. && make +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 a CMake target +### 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. Be aware that ***populate_widget*** macro will also use -***PROJECT_TARGET_ADD*** so ***TARGET_NAME*** will change after using -***populate_widget*** macro. +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: @@ -113,7 +142,8 @@ 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}.... @@ -124,9 +154,15 @@ populate_widget() --> add target to widget tree depending upon target properties #### 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. +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. + +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. > ***CAUTION*** : The default file is only meant to be use for a > simple widget app, more complicated ones which needed to export @@ -136,8 +172,9 @@ variable set in _config.cmake_ file. #### 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. +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. @@ -159,8 +196,7 @@ 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 --------------------- +## Macro reference ### PROJECT_TARGET_ADD @@ -189,44 +225,54 @@ Usage : project_subdirs_add() ``` -You also can specify a globbing pattern as argument to filter which folders will be looked for. +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: +To filter all directories that begin with a number followed by a dash the +anything: ```cmake project_subdirs_add("[0-9]-*") ``` -### project_targets_populate +## Autobuild script usage -Macro use to populate widget tree. To make this works you have to specify some properties to your target : +### Generation -* 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}` +To be integrated in the Yocto build workflow you have to generate `autobuild` +scripts using _autobuild_ target. -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 : +To generate those scripts proceeds: -```cmake -project_targets_populate() +```bash +mkdir -p build +cd build +cmake .. && make autobuild ``` -### project_package_build +You should see _conf.d/autobuild/agl/autobuild_ file now. -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 : +### Available targets -Usage : +Here are the available targets available from _autobuild_ scripts: -```cmake -project_package_build() -``` +- **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. -### project_closing_message +Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'") -Will display the closing message configured in `config.cmake` file. Put it at the end of your project CMake file. +Usage example: + +```bash +./conf.d/autobuild/wgt/autobuild package DEST=/tmp +``` \ No newline at end of file