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
|
<!--
SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
SPDX-License-Identifier: BSD-2-Clause
-->
# check-build -- check whether example programs can be built
The `check-build` tool can be used to build and test different
programs in a temporary build directory. The programs are listed in
a TOML configuration file, along with the commands to build and
test them.
## Configuration file structure
The file describing the subdirectories with the programs to be built has
the following structure:
### The "format" section
The `format` section contains a single table named `version` with two
keys, `major` and `minor`, both integers. The `major.minor` pair
specifies the version of the format specification for the `programs.toml`
file itself.
The only valid combination of values is `major = 0` and `minor = 1`.
### The "program" section
This table contains the definitions for the programs that `check-build`
should try to build and run. It may have one or more entries with
names corresponding to the names of the subdirectories where the files for
each program may be found.
#### The "program.NAME.prerequisites" section
This table currently only has a single valid key, `programs`: a list of
program names that will be looked for in the current execution search path.
If any of these prerequisites are not met, `check-build` will not
attempt to build the program, but it will report it as skipped, not failed.
This may be overridden by the `--force` command-line option
(or the `check_build.defs.Config.force` boolean variable): if it is
specified, then `check-build` will attempt to build and run the program
even if some of its prerequisites are not met.
#### The "program.NAME.commands" section
This table contains the lists of commands to be executed in order to
build and test the program. Each value is a list of commands to be
executed, and each command in its turn is a list of strings:
a program name and arguments to pass to it.
There are currently three valid keys in this table:
- `clean`: not used yet, since `check-build` always copies the program
files to a newly-created temporary directory, so there should be no
previously-existing build artifacts
- `build`: one or more commands to execute to build the program
- `test`: one or more commands to execute to make sure that the program
that was just built is operational and correct
## The `check-build` command-line tool
The most common way to use `check-build` is through the command-line tool:
run `check-build`, specify the path to the TOML configuration file using
the `-c` option, optionally pass the `-v` / `--verbose` flag. By default,
the `check-build` tool will try to build and test all the programs
defined in the configuration file; pass one or more program names on
the command line to only build and test those.
## Examples
Given the following contents of the `ztest/programs.toml` configuration file:
[format.version]
major = 0
minor = 1
[program.pkg-make]
executable = "ztest"
[program.pkg-make.commands]
clean = [["make", "clean"]]
build = [["make"]]
test = [["make", "test"]]
[program.cmake]
executable = "ztest"
[program.cmake.commands]
clean = [["make", "clean"]]
build = [["cmake", "."], ["make"]]
test = [["./ztest"]]
Build and test both programs:
check-build -c ztest/programs.toml
Only build and test the CMake version with some `check-build` diagnostic messages:
check-build -c ztest/programs.toml -v cmake
|
