summaryrefslogtreecommitdiffstats
path: root/docs/dev_guide/autobuild.md
blob: b5df6ee4230fffc69fbe3ca312ecde53af601078 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# 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 object file and target results from the build directory.
- **distclean**: Deletes the build directory.
- **configure**: Generates the project Makefile from the `CMakeLists.txt` files.
- **build**: Compiles all project targets.
- **package**: Builds a widget (**wgt**) package.
- **package-test**: Builds the test **wgt** package and the normal **wgt** package.
- **install**: Installs the project into your filesystem.

Specifying the following variables lets you modify compilation behavior:

- **CLEAN_ARGS**: Variable used at **clean** time.
- **DISTCLEAN_ARGS**: Variable used at **distclean** time.
- **CONFIGURE_ARGS**: Variable used at **configure** time.
- **BUILD_ARGS**: Variable used at **build** time.
- **DEST**: Directory in which to place the created ***wgt*** file.
  The default directory is the build root directory.

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
```