diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 165 |
1 files changed, 101 insertions, 64 deletions
@@ -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,13 +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 : @@ -25,15 +26,22 @@ A typical project architecture would be : <project-root-path> │ ├── 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 @@ -59,54 +67,73 @@ A typical project architecture would be : │ └── config.xml.in ├── <libs> ├── <target> +│ └── <files> ├── <target> +│ └── <file> └── <target> + └── <files> ``` | # | Parent | Description | | - | -------| ----------- | | \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. | -| conf.d | \<root-path\> | 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 | \<root-path\> | 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. | | \<libs\> | \<root-path\> | 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. | | \<target\> | \<root-path\> | 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 : ```bash -git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.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 <tag_name> +git checkout --detach <branch_name> +git checkout --detach <commit_id> +# 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: @@ -127,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 @@ -139,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. @@ -162,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 @@ -202,40 +235,44 @@ anything: 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.
\ No newline at end of file +Usage example: + +```bash +./conf.d/autobuild/wgt/autobuild package DEST=/tmp +```
\ No newline at end of file |