diff options
6 files changed, 835 insertions, 0 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 new file mode 100644 index 0000000..0602ea1 --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/1_Project_Architecture.md @@ -0,0 +1,74 @@ +--- +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 new file mode 100644 index 0000000..a4570ee --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/2_Configuring_AGL_CMake_Templates.md @@ -0,0 +1,136 @@ +--- +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 new file mode 100644 index 0000000..13edf32 --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/3_Advanced_Usage.md @@ -0,0 +1,305 @@ +--- +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 new file mode 100644 index 0000000..2b5963c --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/4_Advanced_Customization.md @@ -0,0 +1,112 @@ +--- +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 new file mode 100644 index 0000000..c32a6da --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/5_Autobuild.md @@ -0,0 +1,152 @@ +--- +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 new file mode 100644 index 0000000..26bf869 --- /dev/null +++ b/docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/6_Using_CMake_Templates_from_Bitbake_Recipes.md @@ -0,0 +1,56 @@ +--- +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 |