docs/3_Developer_Guides/5_Using_CMAKE_Applications_Module/5_Autobuild.md

   1 ---
   2 title: Autobuild
   3 ---
   4
   5 Applications based on the AGL framework should have a
   6 full build and packaging solution that is independent of the
   7 [Yocto Project](https://www.yoctoproject.org) workflow.
   8
   9 You can create a script named **autobuild** to control applications
  10 build operations.
  11 AGL provides a BitBake class file (`aglwgt.bbclass`) that calls the
  12 **autobuild** script for all operations.
  13 The class file is located at the top level of the application repository.
  14
  15 You can write the **autobuild** script using any of the following languages:
  16
  17 * Makefile
  18 * Bash
  19 * Python
  20
  21 The script executes directly after applying a `chmod()` command.
  22 The caller, which can be the `aglwgt.bbclass`, a Jenkins job, or an actual person,
  23 must make the **autobuild** executable before calling it.
  24 To facilitate direct execution, you need to start the script with a
  25 [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) sequence:
  26
  27 * '#!/usr/bin/make -f' for Makefile format
  28 * '#!/usr/bin/bash' for Bash format
  29
  30 The calling convention is similar to the convention used in `make`.
  31 To pass arguments, use environment variables.
  32
  33 **NOTE:** For Bash, an evaluation of the arguments
  34 sets the environment variables correctly.
  35
  36 The following format shows the generic call:
  37
  38 ```bash
  39 autobuild/agl/autobuild <command> [ARG1="value1" [ARG2="value2" ... ]]
  40 ```
  41
  42 The **autobuild** script can be invoked from any directory
  43 with all paths considered to be relative to the
  44 script's location.
  45 For makefile scripts, this is the usual behavior.
  46 For Bash scripts, a `cd $(dirname $0)` command must be run at
  47 the beginning of the script.
  48
  49 At build time, the following calls must be made in the following order:
  50
  51 1. Initialize the build environment (e.g if the application uses
  52    `cmake` the configure step runs CMake).
  53
  54     ```bash
  55     autobuild/agl/autobuild configure CONFIGURE_ARGS="..."
  56     ```
  57
  58 2. Build the application (i.e. compile, link binaries, assembles javascript,
  59    and so forth).
  60
  61     ```bash
  62     autobuild/agl/autobuild build BUILD_ARGS="...."
  63     ```
  64
  65 3. Create the widget package(s) in the specified destination path
  66    prepared by the caller.
  67
  68     ```bash
  69     autobuild/agl/autobuild package PACKAGE_ARGS="..." DEST=<path-for-resulting-wgt-files>
  70     ```
  71
  72 4. Create the test widget package(s) in the specified destination path
  73    prepared by the caller.
  74
  75     ```bash
  76     autobuild/agl/autobuild package-test PACKAGE_ARGS="..." DEST=<path-for-resulting-wgt-files>
  77     ```
  78
  79 5. Clean the built files by removing the result of the **autobuild** build.
  80
  81     ```bash
  82     autobuild/agl/autobuild clean CLEAN_ARGS="..."
  83     ```
  84
  85 6. Clean everything by removing the result of the **autobuild** build
  86    and the **autobuild** configure.
  87
  88     ```bash
  89     autobuild/agl/autobuild distclean DISTCLEAN_ARGS="..."
  90     ```
  91
  92 ## Integrating **autobuild** into the Yocto Project Workflow
  93
  94 If you want to integrate the **autobuild** script into the Yocto Project
  95 workflow, you need to generate the script.
  96 To generate the script, use the `autobuild` target.
  97
  98 The following commands create the **autobuild** script in the
  99 `autobuild/agl` directory:
 100
 101 ```bash
 102 mkdir -p build
 103 cd build
 104 cmake .. && make autobuild
 105 ```
 106
 107 ## Available Targets
 108
 109 Following are the targets available from the **autobuild** script:
 110
 111 - **clean**: Removes all the object files and target results generated by Makefile.
 112 - **clean-{release,debug,coverage,test}**: Removes all the object files and target results generated by Makefile for the specified build type.
 113 - **clean-all**: Deletes the build directories for all build types.
 114 - **distclean**: Deletes the build directories for all build types.
 115 - **configure**: Generates the project Makefile from the `CMakeLists.txt` files for the release build type.
 116 - **configure-{release,debug,coverage,test}**: Generates the project Makefile from the `CMakeLists.txt` files for the specified build type.
 117 - **build**: Compiles all project targets for the release build type.
 118 - **build-{release,debug,coverage,test}**: Compiles all project targets for the specified build type.
 119 - **build-all**: Compiles all project targets for all specified build types.
 120 - **package**: Builds the widget (**wgt**) package for the release build type.
 121 - **package-{release,debug,coverage}**: Builds the widget (**wgt**) package for the specified build type.
 122 - **package-test**: Builds the test **wgt** package.
 123 - **package-all**: Builds the widget (**wgt**) packages for all build types.
 124 - **install**: Installs the project into your filesystem.
 125
 126 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.
 127
 128 Specifying the following variables lets you modify compilation behavior:
 129
 130 - **CLEAN_ARGS**: Variable used at **clean** time.
 131 - **CONFIGURE_ARGS**: Variable used at **configure** time.
 132 - **BUILD_ARGS**: Variable used at **build** time.
 133 - **BUILD_DIR**: Build directory for release type build.
 134   The default value is a "build" directory in the root of the project.
 135 - **BUILD_DIR_DEBUG**: Build directory for debug type build.
 136   The default value is a "build-debug" directory in the root of the project.
 137 - **BUILD_DIR_TEST**: Build directory for test type build.
 138   The default value is a "build-test" directory in the root of the project.
 139 - **BUILD_DIR_COVERAGE**: Build directory for coverage type build.
 140   The default value is a "build-coverage" directory in the root of the project.
 141 - **DEST**: Directory in which to place the created ***wgt*** file(s).
 142   The default directory is the build root directory.
 143
 144 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.
 145
 146 When you provide a variable, use the CMake format (i.e.
 147 BUILD_ARGS="-DC_FLAGS='-g -O2'").
 148 Following is an example:
 149
 150 ```bash
 151 ./autobuild/agl/autobuild package DEST=/tmp
 152 ```