summaryrefslogtreecommitdiffstats
path: root/docs/dev_guide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/dev_guide')
-rwxr-xr-xdocs/dev_guide/0-cmake-overview.md9
-rwxr-xr-xdocs/dev_guide/1-installing-cmake.md122
-rwxr-xr-xdocs/dev_guide/2-configuring-cmake.md138
-rw-r--r--docs/dev_guide/2_project_architecture.md50
-rwxr-xr-xdocs/dev_guide/3-project-architecture.md76
-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