diff options
Diffstat (limited to 'docs/dev_guide')
| -rwxr-xr-x | docs/dev_guide/0-cmake-overview.md | 9 | ||||
| -rwxr-xr-x | docs/dev_guide/1-installing-cmake.md | 122 | ||||
| -rwxr-xr-x | docs/dev_guide/2-configuring-cmake.md | 138 | ||||
| -rw-r--r-- | docs/dev_guide/2_project_architecture.md | 50 | ||||
| -rwxr-xr-x | docs/dev_guide/3-project-architecture.md | 76 | ||||
| -rwxr-xr-x[-rw-r--r--] | docs/dev_guide/4-advanced-usage.md (renamed from docs/dev_guide/3_advanced_usage.md) | 0 | ||||
| -rwxr-xr-x[-rw-r--r--] | docs/dev_guide/5-advanced-customization.md (renamed from docs/dev_guide/4_advanced_customization.md) | 0 | ||||
| -rwxr-xr-x[-rw-r--r--] | docs/dev_guide/6-autobuild.md (renamed from docs/dev_guide/5_autobuild.md) | 0 |
8 files changed, 345 insertions, 50 deletions
diff --git a/docs/dev_guide/0-cmake-overview.md b/docs/dev_guide/0-cmake-overview.md new file mode 100755 index 0000000..ca76728 --- /dev/null +++ b/docs/dev_guide/0-cmake-overview.md @@ -0,0 +1,9 @@ +# Overview + +The CMake AGL Framework Template Module +helps to build applications or bindings for the +AGL Application Framework. +You can use the template module to easily build a widget and its related +test widget for running on top the AGL Application Framework. + + diff --git a/docs/dev_guide/1-installing-cmake.md b/docs/dev_guide/1-installing-cmake.md new file mode 100755 index 0000000..5de16cd --- /dev/null +++ b/docs/dev_guide/1-installing-cmake.md @@ -0,0 +1,122 @@ +# Installing CMake Templates + +You can install CMake templates on your native Linux system. + +In order to use the templates, you need to install them as +a CMake module. +On your native Linux system, use your distribution's package manager. +See the +"[Prerequisites](../host-configuration/docs/2-download-packages.html)" +section for how to install packages using your distribution's package +manager. +Be sure to use the following with you install the packages: + +```bash +export DISTRO="xUbuntu_16.10" +export REVISION=Master +``` + +**NOTE:** In order to use the CMake templates, you must be using the +AGL Guppy release. +You cannot use prior releases. + +## Installing on Debian or Ubuntu + +Use the following command to install AGL's CMake Application Module +on a native Debian or Ubuntu system: + +```bash +sudo apt-get install agl-cmake-apps-module-bin +``` + +## Installing on OpenSUSE + +Use the following command to install AGL's CMake Application Module +on a native OpenSUSE system: + +```bash +sudo zypper install agl-cmake-apps-module +``` + +## Installing on Fedora + +Use the following command to install AGL's CMake Application Module +on a native Fedora system: + +```bash +sudo dnf install agl-cmake-apps-module +``` + +# Using CMake Templates in a Cross-Compilation Environment + +Beginning with the `Grumpy Guppy`, version 7, the CMakeAfbTemplates CMake module +is installed by default in the SDKs supplied by AGL. +Consequently, you do not need to take steps to install the modules. + +Following are links to the latest SDKs on the AGL master branch: + +* [dra7xx-evm](https://download.automotivelinux.org/AGL/snapshots/master/latest/dra7xx-evm/deploy/sdk/) +* [dragonboard-410c](https://download.automotivelinux.org/AGL/snapshots/master/latest/dragonboard-410c/deploy/sdk/) +* [intel-corei7-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/intel-corei7-64/deploy/sdk/) +* [m3ulcb-nogfx](https://download.automotivelinux.org/AGL/snapshots/master/latest/m3ulcb-nogfx/deploy/sdk/) +* [qemux86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/sdk/) +* [raspberrypi3](https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/sdk/) + +# Using CMake Templates from BitBake Recipes + +If you have developed an application and you want to include it in an AGL image, +you must add a BitBake recipe in one of the following layers: + +* [meta-agl](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/AGL/meta-agl): + meta-agl layer (core AGL) +* [meta-agl-cluster-demo](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/AGL/meta-agl-cluster-demo): + cluster demo specific recipes and configuration +* [meta-agl-demo](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/AGL/meta-agl-demo): + meta-agl-demo layer (demo/staging/"one-shot") +* [meta-agl-devel](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/AGL/meta-agl-devel): + meta-agl-devel (Development and Community BSPs) +* [meta-agl-extra](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/AGL/meta-agl-extra): + meta-agl-extra (additional/optional components for AGL) + +Once you have the recipe in place, edit it to include the following +line to cause the `aglwgt` class to be inherited: + +```bb +inherit aglwgt +``` + +Following is an example that uses the HVAC application recipe (i.e. `hvac.bb`), which +builds the HVAC application: + +```bb +SUMMARY = "HVAC Service Binding" +DESCRIPTION = "AGL HVAC Service Binding" +HOMEPAGE = "https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-hvac" +SECTION = "apps" + +LICENSE = "Apache-2.0" +LIC_FILES_CHKSUM = "file://LICENSE;md5=ae6497158920d9524cf208c09cc4c984" + +SRC_URI = "gitsm://gerrit.automotivelinux.org/gerrit/apps/agl-service-hvac;protocol=https;branch=${AGL_BRANCH}" +SRCREV = "${AGL_APP_REVISION}" + +PV = "1.0+git${SRCPV}" +S = "${WORKDIR}/git" + +DEPENDS = "json-c" +RDEPENDS_${PN} += "agl-service-identity-agent" + +inherit cmake aglwgt pkgconfig +``` + +---- + +# Additional Examples + +The following links provide further examples of recipes that use the +CMake templates: + +* [helloworld-service](https://github.com/iotbzh/helloworld-service) +* [agl-service-audio-4a](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-audio-4a) +* [agl-service-unicens](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-unicens) +* [4a-hal-unicens](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/4a-hal-unicens) diff --git a/docs/dev_guide/2-configuring-cmake.md b/docs/dev_guide/2-configuring-cmake.md new file mode 100755 index 0000000..12842ac --- /dev/null +++ b/docs/dev_guide/2-configuring-cmake.md @@ -0,0 +1,138 @@ +# Configuring CMake Templates + +Configuration consists of editing the `config.cmake` file for your +specific project. + +## Creating Your `config.cmake` File + +First, you need to create a `confd/cmake` file in your CMake project +directory. + +```bash +mkdir -p conf.d/cmake +``` + +Next, use one of the following commands to copy a `cmake.sample` file to +your `config.cmake` file. +The first command applies if you have the SDK installed, while the +second command applies if you installed the modules on your native Linux system. + +**NOTE:** The `OECORE_NATIVE_SYSROOT` variable is defined once you have +a project folder, the AGL SDK source files, and the CMake modules installed. + +```bash +mkdir -p conf.d/cmake +# From the SDK sysroot >= RC2 of the 7.0.0 Guppy release +cp ${OECORE_NATIVE_SYSROOT}/usr/share/doc/CMakeAfbTemplates/samples.d/config.cmake.sample conf.d/cmake/config.cmake +# From a native installation +cp /usr/share/doc/CMakeAfbTemplates/samples.d/config.cmake.sample conf.d/cmake/config.cmake +``` + +Once you have created your `config.cmake` file, you need to make the changes +specific to your project. + +## Creating Your `CMakeLists.txt` File + +To create this file, use the example in the **cmake module**. +Use one of the following two commands to create your file. +The first command applies if you have the SDK installed, while the +second command applies if you installed the modules on your native Linux system. + +**NOTE:** The `OECORE_NATIVE_SYSROOT` variable is defined once you have +a project folder, the AGL SDK source files, and the CMake modules installed. + +```bash +# From the SDK sysroot >= RC2 of the 7.0.0 Guppy release +cp ${OECORE_NATIVE_SYSROOT}/usr/share/doc/CMakeAfbTemplates/samples.d/CMakeLists.txt.sample CMakeLists.txt +# From a native installation +cp /usr/share/doc/CMakeAfbTemplates/samples.d/CMakeLists.txt.sample CMakeLists.txt +``` + +## Creating Your CMake Targets + +Creating a CMake target is the result of editing your `CMakeLists.txt` file. + +For each target that is part of your project, you need to use the +***PROJECT_TARGET_ADD*** statement. +Using this statement includes the target in your project. + +Using the ***PROJECT_TARGET_ADD*** statement makes the CMake ***TARGET_NAME*** +variable available until the next ***PROJECT_TARGET_ADD*** statement is +encountered that uses a new target name. + +Following is typical use within the `CMakeLists.txt` file to create a target: + +```cmake +PROJECT_TARGET_ADD(target_name) --> Adds *target_name* to the project. +*target_name* is a sub-folder in the CMake project. + +add_executable/add_library(${TARGET_NAME}.... --> Defines the target sources. + +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> Configures the target properties +so they can be used by macros. + +INSTALL(TARGETS ${TARGET_NAME}.... +``` + +## Target Properties + +Target properties are used to determine the nature of the +target and where the target is stored within the package being built. + +Use the **LABELS** property to specify the target type that you want +included in the widget package. +You can choose the following target types: + +Choose between: + +- **BINDING**: A shared library loaded by the AGL Application Framework. +- **BINDINGV2**: A shared library loaded by the AGL Application Framework. + This library must be accompanied by a JSON file named similar to the + *${OUTPUT_NAME}-apidef* of the target, which describes the API with OpenAPI + syntax (e.g: *mybinding-apidef*). + Alternatively, you can choose the name without the extension using the + **set_openapi_filename** macro. + If you use C++, you must set **PROJECT_LANGUAGES** through *CXX*. +- **BINDINGV3**: A shared library loaded by the AGL Application Framework. + This library must be accompanied by a JSON file named similar to the + *${OUTPUT_NAME}-apidef* of the target, which describes the API with OpenAPI + syntax (e.g: *mybinding-apidef*). + Alternatively, you can choose the name without the extension using the + **set_openapi_filename** macro. + If you use C++, you must set **PROJECT_LANGUAGES** through *CXX*. +- **PLUGIN**: A shared library meant to be used as a binding plugin, which + would load the library as a plugin consequently extending its + functionalities. + You should name the binding using a special extension that you choose + with `SUFFIX cmake target property`. + If you do not use the special extension, it defaults to **.ctlso**. +- **HTDOCS**: The root directory of a web application. + This target has to build its directory and puts its files in the + **${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}**. +- **DATA**: Resources used by your application. + This target has to build its directory and puts its files in the + **${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}**. +- **EXECUTABLE**: The entry point of your application executed by the AGL + Application Framework. +- **LIBRARY**: An external third-party library bundled with the binding. + The library is bundled in this manner because the platform does not + provide bundling. +- **BINDING-CONFIG**: Any files used as configuration by your binding. + +**TIP:** you should use the prefix _afb-_ (**Application Framework Binding**) +with your *BINDING* targets. + +Following is an example that uses the **BINDINGV3** property: + +```cmake +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES + PREFIX "afb-" + LABELS "BINDINGV3" + OUTPUT_NAME "file_output_name") +``` + +**CAUTION**: You do not need to specify an **INSTALL** command for these +targets. +Installation is performed by the template. +Targets are installed in the **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}** +directory. diff --git a/docs/dev_guide/2_project_architecture.md b/docs/dev_guide/2_project_architecture.md deleted file mode 100644 index 9e5503f..0000000 --- a/docs/dev_guide/2_project_architecture.md +++ /dev/null @@ -1,50 +0,0 @@ -# Project architecture - -A typical project architecture would be : - -```tree -<project-root-path> -│ -├── autobuild/ -│ ├── agl -│ │ └── autobuild -│ ├── linux -│ │ └── autobuild -│ └── windows -│ └── autobuild -├── conf.d/ -│ ├── packaging/ -│ │ ├── rpm -│ │ │ └── package.spec -│ │ └── deb -│ │ ├── package.dsc -│ │ ├── debian.package.install -│ │ ├── debian.changelog -│ │ ├── debian.compat -│ │ ├── debian.control -│ │ └── debian.rules -│ ├── cmake -│ │ ├── 00-debian-osconfig.cmake -│ │ ├── 00-suse-osconfig.cmake -│ │ ├── 01-default-osconfig.cmake -│ │ └── config.cmake -│ └── wgt -│ ├── icon.png -│ └── config.xml.in -├── <target> -│ └── <files> -├── <target> -│ └── <file> -└── <target> - └── <files> -``` - -| # | Parent | Description | -| - | -------| ----------- | -| \<root-path\> | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. | -| autobuild | \<root-path\> | Scripts generated from app-templates to build packages the same way for differents platforms.| -| conf.d | \<root-path\> | Holds needed files to build, install, debug, package an AGL app project | -| cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. | -| packaging | conf.d | Contains output files used to build packages. | -| wgt | conf.d | Contains config.xml.in, and optionnaly test-config.xml.in template files modified from the sample provided in cmake module for the needs of project (See config.xml.in.sample and test-config.xml.in.sample file for more details). | -| \<target\> | \<root-path\> | A target to build, typically library, executable, etc. | diff --git a/docs/dev_guide/3-project-architecture.md b/docs/dev_guide/3-project-architecture.md new file mode 100755 index 0000000..aefaca3 --- /dev/null +++ b/docs/dev_guide/3-project-architecture.md @@ -0,0 +1,76 @@ +# Project architecture + +CMake projects follow a typical file hierarchy. +The following tree structure represents a typical CMake project +directory structure: + +```tree +<project-root-path> +| +├── CMakeLists.txt +│ +├── autobuild/ +│ ├── agl +│ │ └── autobuild +│ ├── linux +│ │ └── autobuild +│ └── windows +│ └── autobuild +├── conf.d/ +│ ├── packaging/ +│ │ ├── rpm +│ │ │ └── package.spec +│ │ └── deb +│ │ ├── package.dsc +│ │ ├── debian.package.install +│ │ ├── debian.changelog +│ │ ├── debian.compat +│ │ ├── debian.control +│ │ └── debian.rules +│ ├── cmake +│ │ ├── 00-debian-osconfig.cmake +│ │ ├── 00-suse-osconfig.cmake +│ │ ├── 01-default-osconfig.cmake +│ │ └── config.cmake +│ └── wgt +│ ├── icon.png +│ └── config.xml.in +├── <target> +│ └── <files> +├── <target> +│ └── <file> +└── <target> + └── <files> +``` + +| File or Directory | Parent | Description | +|----|----|----| +| *root_path* | n/a | CMake project root path. Holds the master CMakeLists.txt file and all general project files. +| CMakeLists.txt | The master CMakeLists.txt file. +| autobuild/ | *root_path* | Scripts generated from app-templates to build packages the same way for differents platforms. +| conf.d/ | *root_path* | Holds needed files to build, install, debug, and package an AGL application project. +| packaging/ | confd/ | Contains output files used to build packages. +| cmake/ | confd/ | Minimally contains the config.cmake file, which is modified from the sample provided in the app-templates submodule. +| wgt/ | confd/ | Contains config.xml.in and optionaly the test-config.xml.in template files that are modified from the sample provided with the CMake module for the needs of the project. For more details, see the config.xml.in.sample and test-config.xml.in.sample files. +| *target* | *root_path* | A target to build, which is typically a library or executable. + +When building projects using CMake, the build process automatically detects +the `CMakeLists.txt` and `*.cmake` files. +To help with this process, the `PROJECT_SRC_DIR_PATTERN` variable +is used for recursive pattern searching from the CMake project's +*root_path* downward. +Each sub-folder below *root_path* in the project is searched and included +during compilation. +The directories matching the pattern `PROJECT_SRC_DIR_PATTERN` variable +are scanned. + +**NOTE:** The `PROJECT_SRC_DIR_PATTERN` variable defaults to "*". + +When the `CMakeLists.txt` file is found, the directory in which it is found +is automatically added to the CMake project. + +Similarly, when a file whose extension is `.cmake` is found, the directory in +which that file resides is also added to the CMake project. + + + diff --git a/docs/dev_guide/3_advanced_usage.md b/docs/dev_guide/4-advanced-usage.md index 3e0ace1..3e0ace1 100644..100755 --- a/docs/dev_guide/3_advanced_usage.md +++ b/docs/dev_guide/4-advanced-usage.md diff --git a/docs/dev_guide/4_advanced_customization.md b/docs/dev_guide/5-advanced-customization.md index 30c704e..30c704e 100644..100755 --- a/docs/dev_guide/4_advanced_customization.md +++ b/docs/dev_guide/5-advanced-customization.md diff --git a/docs/dev_guide/5_autobuild.md b/docs/dev_guide/6-autobuild.md index 6977e09..6977e09 100644..100755 --- a/docs/dev_guide/5_autobuild.md +++ b/docs/dev_guide/6-autobuild.md |