diff options
author | Jan-Simon Möller <jsmoeller@linuxfoundation.org> | 2022-01-26 12:25:31 +0100 |
---|---|---|
committer | Jan-Simon Moeller <jsmoeller@linuxfoundation.org> | 2022-02-02 11:50:02 +0000 |
commit | 8160b5cdc8547277f3f31ee1e41524754d5d987d (patch) | |
tree | 6ebbcfa9802c82de6b552733ef53d411247e1cdd /docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module | |
parent | 835363f430c5dee0b53b7c415572cdfdcc02ad18 (diff) |
Update to documentation before Marlinmarlin_12.92.0marlin/12.92.012.92.0
This is mostly a cleanup before the Magic Marlin Release.
We do have the Application Framework chapter rewrite pending.
Bug-AGL: SPEC-4236
Signed-off-by: Jan-Simon Möller <jsmoeller@linuxfoundation.org>
Change-Id: I7e1f39667b4db417497b1d0c84065c173fa18439
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/27097
Diffstat (limited to 'docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module')
6 files changed, 0 insertions, 835 deletions
diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/1_Project_Architecture.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/1_Project_Architecture.md deleted file mode 100644 index 0602ea1..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/1_Project_Architecture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Project Architecture ---- - -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/ | conf.d/ | Contains output files used to build packages. -| cmake/ | conf.d/ | Minimally contains the config.cmake file, which is modified from the sample provided in the app-templates submodule. -| wgt/ | conf.d/ | 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.
\ No newline at end of file diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/2_Configuring_AGL_CMake_Templates.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/2_Configuring_AGL_CMake_Templates.md deleted file mode 100644 index a4570ee..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/2_Configuring_AGL_CMake_Templates.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Configuring AGL 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 -``` - -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 -``` - -## 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.
\ No newline at end of file diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/3_Advanced_Usage.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/3_Advanced_Usage.md deleted file mode 100644 index 13edf32..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/3_Advanced_Usage.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: Advanced Usage ---- - -This topic describes some advanced ways of using the CMake templates. - -## Building a Widget - -To build a widget, you need a `config.xml` file that describes -your application (widget) and how the Application Framework launches it. -Your repository contains a simple default file named -`config.xml.in` that should work for simple applications and should -not require interactions with other bindings. - -It is also recommended that you use the sample configuration -file that you can find in the location. -This file is named `config.xms.in.sample` and is more complete. -Copy the sample file to your `conf.d/wgt` directory and name it -`config.xml.in`. -Once you have your copy, edit the file to fit your needs. - -**CAUTION:** The default file is only meant to be used for a -simple widget application. -For more complicated applications that need to export -their API, or ship several applications in one widget -need to use the provided `config.xml.in.sample` file, which has -all new Application Framework features explained and provides -examples. - -## Using CMake Template Macros - -To leverage all CMake template features, you must specify properties -on your targets. -Some macros do not work unless you specify the target type. -If you do not specify a type (e.g. a custom target such as an -HTML5 application), the macro uses the `LABELS` property to -determine the target type. - -Aside from those values, the following optional values can be -assigned to the `LABELS` property. -These values define the resource types that make up your test materials: - -- **TEST-CONFIG**: JSON configuration files used by the `afb-test` - binding. - These files execute the tests. -- **TEST-DATA**: Resources used to test your binding. - Minimally, you need a test plan. - You should also consider fixtures and any files required by your tests. - These required files appear as part of a separate test widget. -- **TEST-PLUGIN**: A shared library used as a binding plugin. - A binding loads the library as a plugin to extend the binding's functionality. - You should use a special file extension when you name the library - by using the `SUFFIX` CMake target property. - If you do not choose an extension, `.ctlso` is used by default. -- **TEST-HTDOCS**: The root directory of a web application. - This target has to build its directory and put its files in - the `${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}` directory. -- **TEST-EXECUTABLE**: The entry point of your application executed by the AGL - Application Framework. -- **TEST-LIBRARY**: An external third-party library bundled with the binding - for its own purpose. - The platform does not provide this library. - -Following is a mapping between `LABELS` and directories where files reside in -the widget: - -- **EXECUTABLE** : `<wgtrootdir>/bin` -- **BINDING-CONFIG** : `<wgtrootdir>/etc` -- **BINDING** | **BINDINGV2** | **BINDINGV3** | **LIBRARY** : `<wgtrootdir>/lib` -- **PLUGIN** : `<wgtrootdir>/lib/plugins` -- **HTDOCS** : `<wgtrootdir>/htdocs` -- **BINDING-DATA** : `<wgtrootdir>/var` -- **DATA** : `<wgtrootdir>/var` - -Following is a mapping between test-dedicated `LABELS` and directories where -files reside in the widget: - -- **TEST-EXECUTABLE** : `<wgtrootdir>/bin` -- **TEST-CONFIG** : `<TESTwgtrootdir`>/etc` -- **TEST-PLUGIN** : `<wgtrootdir>/lib/plugins` -- **TEST-HTDOCS** : `<wgtrootdir>/htdocs` -- **TEST-DATA** : `<TESTwgtrootdir>/var` - -**TIP:** Use the prefix `afb-` (Application Framework Binding) -with your **BINDING** targets. - -Following is an example that sets the `LABELS` and `OUTPUT_NAME` properties: - -```cmake -SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES - LABELS "HTDOCS" - OUTPUT_NAME dist.prod - ) -``` - -**NOTE**: You do not need to specify an **INSTALL** command for these - targets. - Installation is handled by the template and installs using the - following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}** - - Also, if you want to set and use `rpath` with your target, you should use - and set the target property `INSTALL_RPATH`. - -## Adding an External Third-Party Library - -You can add an external third-party library that is built, linked, -and shipped with the project. -Or, you can link and ship the library only with the project. - -### Building, Linking, and Shipping an External Library with the Project - -If you need to include an external library that is not shipped -with the project, you can bundle the required library in the -`lib` widget directory. - -Templates includes facilities to help you work with external -libraries. -A standard method is to declare as many CMake ExternalProject -modules as you need to match the number of needed libraries. - -An ExternalProject module is a special CMake module that lets you define how -to download, update, patch, configure, build, and install an external project. -The project does not need to be a CMake project. -Additionally, you can provide custom steps to account for special -needs using ExternalProject step. -See the CMake -[ExternalProject documentation site](https://cmake.org/cmake/help/v3.5/module/ExternalProject.html?highlight=externalproject) -for more information. - -Following is an example that includes the `mxml` library for the -[unicens2-binding](https://github.com/iotbzh/unicens2-binding) -project: - -```cmake -set(MXML external-mxml) -set(MXML_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/mxml) -ExternalProject_Add(${MXML} - GIT_REPOSITORY https://github.com/michaelrsweet/mxml.git - GIT_TAG release-2.10 - SOURCE_DIR ${MXML_SOURCE_DIR} - CONFIGURE_COMMAND ./configure --build x86_64 --host aarch64 - BUILD_COMMAND make libmxml.so.1.5 - BUILD_IN_SOURCE 1 - INSTALL_COMMAND "" -) - -PROJECT_TARGET_ADD(mxml) - -add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL) - -SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES - LABELS LIBRARY - IMPORTED_LOCATION ${MXML_SOURCE_DIR}/libmxml.so.1 - INTERFACE_INCLUDE_DIRECTORIES ${MXML_SOURCE_DIR} -) - -add_dependencies(${TARGET_NAME} ${MXML}) -``` - -The example defines an external project that drives the building of the library. -The example also defines a new CMake target whose type is **IMPORTED**. -The **IMPORTED** target type indicates the target has yet to be built using -CMake but is available at the location defined using the **IMPORTED_LOCATION** -target property. - -You might want to build the library as **SHARED** or **STATIC** depending on your needs -and goals. -Next, the example only has to modify the external project configure step and change -the filename used by **IMPORTED** library target defined after external project. - -The target's **LABELS** property is set to **LIBRARY** to ship it in the widget. - -In this example, the Unicens project also needs header -information from this library. -Consequently, the **INTERFACE_INCLUDE_DIRECTORIES** target property -is used. -Setting that property when another target links to that imported target -allows access to included directories. - -Finally, the example binds the target to the external project -by using a CMake dependency. - -The target can now be linked and used like any other CMake target. - -### Link and Ship an External Library with the Project - -If you already have a binary version of the library that you want to use and you -cannot or do not want to build the library, you can use the **IMPORTED** -library target. - -To illustrate, consider the same example in the previous section. -Following are the relevant modifications: - -```cmake -PROJECT_TARGET_ADD(mxml) - -add_library(${TARGET_NAME} SHARED IMPORTED GLOBAL) - -SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES - LABELS LIBRARY - IMPORTED_LOCATION /path_to_library/libmxml.so.1 - INTERFACE_INCLUDE_DIRECTORIES /path_to_mxml/include/dir -) -``` - -In the previous example, notice the changes to the -`IMPORTED_LOCATION` and `INTERFACE_INCLUDE_DIRECTORIES` statements. -These locate the binary version of the library. - -Finally, you can link any other library or executable target with this imported -library just as you would for any other target. - -## Macro Reference - -Following are several macros that are useful for advanced CMake usage. - -### PROJECT_TARGET_ADD - -This macro adds the target to your project. -Following is a typical example that adds the target to your project. -You need to provide the name of your target as the macro's parameter: - -Example: - -```cmake -PROJECT_TARGET_ADD(low-can-demo) -``` - -The macro makes the variable `${TARGET_NAME}` available and it is defined -using the specified name (e.g. `low-can-demo`). -The variable changes each time the `PROJECT_TARGET_ADD` macro is called. - -### project_subdirs_add - -This macro searches within specified subfolders of the CMake project for -any `CMakeLists.txt` file. -If the file is found, it is added to your project. -You can use this macro in a hybrid application (e.g. where the binding -exists in a subfolder). - -The following example searches within all subfolders: - -Usage : - -```cmake -project_subdirs_add() -``` - -You might want to restrict the subfolders being searched. -If so, you can specify a -[globbing](https://en.wikipedia.org/wiki/Glob_(programming)) pattern -as the argument. -Doing so effectively creates a search filter. - -Following is an example that specifies all directories that begin -with a number, are followed by the dash character, and then followed -by any characters: - -```cmake -project_subdirs_add("[0-9]-*") -``` - -### set_openapi_filename - -This macro is used with a **BINDINGV2** target and defines the -binding definition filename. -You can use it to also define a relative path to -the current `CMakeLists.txt` file. - -If you do not use this macro to specify the name of your definition file, -the default one is used, which is `${OUTPUT_NAME}-apidef` and uses -**OUTPUT_NAME** as the [target property]. - -**CAUTION** When specifying the binding definition filename, -you must not use the file's extension as part of the name. -Following is an example: - -```cmake -set_openapi_filename('binding/mybinding_definition') -``` - -[target property]: https://cmake.org/cmake/help/v3.6/prop_tgt/OUTPUT_NAME.html "OUTPUT_NAME property documentation" - -### add_input_files - -This macro creates a custom target dedicated for HTML5 and data resource files. -The macro provides syntax and schema verification for different languages that -include LUA, JSON and XML. - -Alongside the macro are tools used to check files. -You can configure the tools by setting the -following variables: - -- XML_CHECKER: Uses **xmllint** that is provided with major linux distributions. -- LUA_CHECKER: Uses **luac** that is provided with major linux distributions. -- JSON_CHECKER: Currently, not used by any tools. - -Following is an example: - -```cmake -add_input_file("${MY_FILES_LIST}") -``` - -**NOTE**: If an issue occurs during the "check" step of the macro, -the build halts.
\ No newline at end of file diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md deleted file mode 100644 index 2b5963c..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Advanced Customization ---- - -This section describes how you can include additional CMake files -and custom template scripts. - -## Including Additional CMake Files - -You can include machine and system custom CMake files and -operating system custom CMake files. - -### Machine and System Custom CMake Files - -Advanced configuration is possible by automatically including -additional CMake files from specific locations. -Following are the locations from which you can add CMake -files. -Inclusions occur in the order shown here: - -- `<project-root-path>/conf.d/app-templates/cmake/cmake.d` - normally located CMake project files -- `$HOME/.config/app-templates/cmake.d` - the home location -- `/etc/app-templates/cmake.d` - the system location - -The CMake files you include must be named using either of the following conventions: - -- `XX-common*.cmake` -- `XX-${PROJECT_NAME}*.cmake` - -In both formats, `XX` are numbers and indicate the order in which the file -is included. -The `*` character represents the filename. - -When naming the file, consider the projects in which the file needs to be -included. -If you want to include the file in all projects, use the keyword `common`. -If you want to include the file in a specific project, use the `${PROJECT_NAME}` -value. - -For example, if you want a CMake file whose name is `my_custom_file` -included first and you want it included in all projects, name the file -`01-common-my_custom_file.cmake`. -If you want the same file included in a single project defined by the -`PROJECT_NAME` variable, and you want it included after all other files, -name the file `99-${PROJECT_NAME}-my_custom_file.cmake`. - -When you include CMake files that use CMake variables, the values override -variables with the same name. -The exception to this rule is if you use a cached variable. -Following is an example: - -```cmake -set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring') -``` - -In this example, the `VARIABLE_NAME` variable is defined as a cached -variable by using the **CACHE** keyword. -Consequently, `VARIABLE_NAME` does not get overridden as a result of -including a CMake file that sets the same variable. - -### Operating System Custom CMake Files - -Including custom CMake files based on the operating system -lets you personalize a project depending on the operating system -you are using. - -At the end of the `config.cmake` file `common.cmake` includes -CMake files to customize your project build depending on your platform. -The operating system is detected by using `/etc/os-release`, -which is the default method used in almost all Linux distributions. -Consequently, you can use the value of field **ID_LIKE** to -add a CMake file for that distribution. -The file comes from your `conf.d/cmake/` directory or relatively -from your `app-templates` submodule path `app-templates/../cmake/`. - -**NOTE:** If the **ID_LIKE** field does not exist, you can use the -**ID** field. - -Files that you add must be named according to the following file naming -convention: - -- `XX-${OSRELEASE}*.cmake` - -In the naming convention, `XX` represents numbers and is the order in which -you want a file included. -The ${OSRELEASE} value is taken from either the **ID_LIKE** or **ID** field -of the `/etc/os-release` file. - -You can also configure a CMake file to be included in cases where no -specific operating system can be found. -To do so, name your CMake file as follows: - -- `XX-default*.cmake` - -A good use case example for these two naming conventions is when you have -a several Linux distributions and all but one can use the same module. -For that case, name one CMake file using the `${OSRELEASE}` value and -name the CMake file to be used with the other distributions using -the `XX-default*.cmake` method. - -## Including Custom Template Scripts - -You can include your own custom template scripts that are passed to the -CMake command `configure_file`. - -Just create your own script and place it in either of the following directories: - -- `$HOME/.config/app-templates/scripts` - the home location -- `/etc/app-templates/scripts` - the system location - -Scripts only need to use the extension `.in` to be parsed and configured by -CMake. diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/5_Autobuild.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/5_Autobuild.md deleted file mode 100644 index c32a6da..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/5_Autobuild.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Autobuild ---- - -Applications based on the AGL framework should have a -full build and packaging solution that is independent of the -[Yocto Project](https://www.yoctoproject.org) workflow. - -You can create a script named **autobuild** to control applications -build operations. -AGL provides a BitBake class file (`aglwgt.bbclass`) that calls the -**autobuild** script for all operations. -The class file is located at the top level of the application repository. - -You can write the **autobuild** script using any of the following languages: - -* Makefile -* Bash -* Python - -The script executes directly after applying a `chmod()` command. -The caller, which can be the `aglwgt.bbclass`, a Jenkins job, or an actual person, -must make the **autobuild** executable before calling it. -To facilitate direct execution, you need to start the script with a -[shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) sequence: - -* '#!/usr/bin/make -f' for Makefile format -* '#!/usr/bin/bash' for Bash format - -The calling convention is similar to the convention used in `make`. -To pass arguments, use environment variables. - -**NOTE:** For Bash, an evaluation of the arguments -sets the environment variables correctly. - -The following format shows the generic call: - -```bash -autobuild/agl/autobuild <command> [ARG1="value1" [ARG2="value2" ... ]] -``` - -The **autobuild** script can be invoked from any directory -with all paths considered to be relative to the -script's location. -For makefile scripts, this is the usual behavior. -For Bash scripts, a `cd $(dirname $0)` command must be run at -the beginning of the script. - -At build time, the following calls must be made in the following order: - -1. Initialize the build environment (e.g if the application uses - `cmake` the configure step runs CMake). - - ```bash - autobuild/agl/autobuild configure CONFIGURE_ARGS="..." - ``` - -2. Build the application (i.e. compile, link binaries, assembles javascript, - and so forth). - - ```bash - autobuild/agl/autobuild build BUILD_ARGS="...." - ``` - -3. Create the widget package(s) in the specified destination path - prepared by the caller. - - ```bash - autobuild/agl/autobuild package PACKAGE_ARGS="..." DEST=<path-for-resulting-wgt-files> - ``` - -4. Create the test widget package(s) in the specified destination path - prepared by the caller. - - ```bash - autobuild/agl/autobuild package-test PACKAGE_ARGS="..." DEST=<path-for-resulting-wgt-files> - ``` - -5. Clean the built files by removing the result of the **autobuild** build. - - ```bash - autobuild/agl/autobuild clean CLEAN_ARGS="..." - ``` - -6. Clean everything by removing the result of the **autobuild** build - and the **autobuild** configure. - - ```bash - autobuild/agl/autobuild distclean DISTCLEAN_ARGS="..." - ``` - -## Integrating **autobuild** into the Yocto Project Workflow - -If you want to integrate the **autobuild** script into the Yocto Project -workflow, you need to generate the script. -To generate the script, use the `autobuild` target. - -The following commands create the **autobuild** script in the -`autobuild/agl` directory: - -```bash -mkdir -p build -cd build -cmake .. && make autobuild -``` - -## Available Targets - -Following are the targets available from the **autobuild** script: - -- **clean**: Removes all the object files and target results generated by Makefile. -- **clean-{release,debug,coverage,test}**: Removes all the object files and target results generated by Makefile for the specified build type. -- **clean-all**: Deletes the build directories for all build types. -- **distclean**: Deletes the build directories for all build types. -- **configure**: Generates the project Makefile from the `CMakeLists.txt` files for the release build type. -- **configure-{release,debug,coverage,test}**: Generates the project Makefile from the `CMakeLists.txt` files for the specified build type. -- **build**: Compiles all project targets for the release build type. -- **build-{release,debug,coverage,test}**: Compiles all project targets for the specified build type. -- **build-all**: Compiles all project targets for all specified build types. -- **package**: Builds the widget (**wgt**) package for the release build type. -- **package-{release,debug,coverage}**: Builds the widget (**wgt**) package for the specified build type. -- **package-test**: Builds the test **wgt** package. -- **package-all**: Builds the widget (**wgt**) packages for all build types. -- **install**: Installs the project into your filesystem. - -Note that `aglwgt.bbclass` only will use the **package-{coverage,test}** targets (and thus the **build-{coverage,test}**, etc. targets) for service bindings by default, so **autobuild** scripts for applications may omit support for those. - -Specifying the following variables lets you modify compilation behavior: - -- **CLEAN_ARGS**: Variable used at **clean** time. -- **CONFIGURE_ARGS**: Variable used at **configure** time. -- **BUILD_ARGS**: Variable used at **build** time. -- **BUILD_DIR**: Build directory for release type build. - The default value is a "build" directory in the root of the project. -- **BUILD_DIR_DEBUG**: Build directory for debug type build. - The default value is a "build-debug" directory in the root of the project. -- **BUILD_DIR_TEST**: Build directory for test type build. - The default value is a "build-test" directory in the root of the project. -- **BUILD_DIR_COVERAGE**: Build directory for coverage type build. - The default value is a "build-coverage" directory in the root of the project. -- **DEST**: Directory in which to place the created ***wgt*** file(s). - The default directory is the build root directory. - -Note that the values of **BUILD_DIR_{DEBUG,TEST,COVERAGE}** are defined based on the value of **BUILD_DIR**, so this needs to be kept in mind if over-riding it and building those other widget types. - -When you provide a variable, use the CMake format (i.e. -BUILD_ARGS="-DC_FLAGS='-g -O2'"). -Following is an example: - -```bash -./autobuild/agl/autobuild package DEST=/tmp -``` diff --git a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/6_Using_CMake_Templates_from_Bitbake_Recipes.md b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/6_Using_CMake_Templates_from_Bitbake_Recipes.md deleted file mode 100644 index 26bf869..0000000 --- a/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/6_Using_CMake_Templates_from_Bitbake_Recipes.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: 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 -``` - -The following links provide more examples of recipes that use the -CMake templates: - -* [agl-service-helloworld](https://gerrit.automotivelinux.org/gerrit/admin/repos/apps/agl-service-helloworld) -* [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)
\ No newline at end of file |