261 lines
8.8 KiB
Markdown
261 lines
8.8 KiB
Markdown
abuild
|
|
======
|
|
|
|
This utility is a great tool to check whether your coreboot tree
|
|
compiles for one or all targets. It compiles the 'default' build for a
|
|
mainboard. This is roughly equivalent to removing the .config file,
|
|
running `make menuconfig`, selecting the manufacturer and mainboard,
|
|
then saving the config without making any other changes.
|
|
|
|
It is run on all patches submitted via gerrit as part of the process.
|
|
Before submitting a patch, it is a very good idea to run abuild first
|
|
to make sure your patch compiles cleanly for all.
|
|
|
|
Note that abuild is a tool to do a simple build test, and binaries it
|
|
produces may well not boot if flashed to a system.
|
|
|
|
### Basic usage
|
|
|
|
abuild needs to be run from the coreboot directory. If you cd into the
|
|
coreboot/util/abuild directory and try to run it from there, it will
|
|
not run correctly.
|
|
|
|
If you invoke abuild with no parameters, it will build all boards
|
|
automatically.
|
|
|
|
You can also specify a single board to build with the -t option. For
|
|
example, to build the Lenovo X230 target, run:
|
|
|
|
```bash
|
|
$ util/abuild/abuild -t lenovo/x230
|
|
```
|
|
|
|
### Where builds and logs are stored
|
|
|
|
The resulting images and logs are stored in directory coreboot-builds/
|
|
under your current directory. This can be overridden with --outdir:
|
|
|
|
```bash
|
|
$ util/abuild/abuild --outdir /mnt/portable/coreboot-builds
|
|
```
|
|
|
|
This is useful if you want to divert the build to an external hard
|
|
drive, e.g. to keep the solid-state drive holding the coreboot tree
|
|
young.
|
|
|
|
(We will still refer to this directory as "coreboot-builds" below.)
|
|
|
|
After running the X230 build above, the build log will be in
|
|
coreboot-builds/LENOVO_X230/make.log.
|
|
|
|
For an overview of what passed and what failed, look at
|
|
coreboot-builds/passing_boards and coreboot-builds/failing_boards.
|
|
**These logs are overwritten with each abuild run.** Save them elsewhere
|
|
if you feel a need to reference the results later.
|
|
|
|
### Payloads
|
|
|
|
You can also specify a payload directory with -p:
|
|
|
|
```bash
|
|
mkdir payloads
|
|
cp /somewhere/filo.elf payloads
|
|
```
|
|
|
|
Then add a file payloads/payload.sh which prints the name of the
|
|
payload to use (and takes the mainboard as a parameter) such as:
|
|
|
|
```bash
|
|
echo "`dirname $0`/build/filo.elf"
|
|
```
|
|
|
|
Then you can build an image with payload by specifying:
|
|
|
|
```bash
|
|
util/abuild/abuild -t lenovo/x230 -p ./payloads
|
|
```
|
|
|
|
You can also tell abuild not to use a payload:
|
|
|
|
```bash
|
|
util/abuild/abuild -t lenovo/x230 -p none
|
|
```
|
|
|
|
### Build non-default configurations
|
|
|
|
Sometimes you do need to build test a custom, non-default configuration.
|
|
This can be accomplished by placing a config file in configs/.
|
|
|
|
First, clean your slate with `make distclean` or `rm .config`.
|
|
|
|
Then run `make menuconfig`, select the manufacturer and mainboard, and
|
|
configure the options you need to test building for.
|
|
|
|
Then save a minimal config file omitting options that did not change
|
|
from default:
|
|
|
|
```bash
|
|
make savedefconfig
|
|
```
|
|
|
|
This file is saved as `defconfig` and can be edited further.
|
|
|
|
Now this file can be saved in configs/ which will form the basis of a
|
|
custom configuration included in an abuild. However, it needs to be
|
|
named in a specific way for abuild to pick it up:
|
|
|
|
```
|
|
config.<board>_<suffix>
|
|
```
|
|
|
|
<board> is effectively the BOARD\_xxx Kconfig option without "BOARD\_".
|
|
<suffix> is a free form description of the configuration being built.
|
|
|
|
For example, a config for ASUS P8Z77-M PRO that tests building with MRC
|
|
raminit code (as opposed to the default native raminit) would be named
|
|
`config.asus_p8z77_m_pro_mrc_bin` and contains:
|
|
|
|
```
|
|
CONFIG_VENDOR_ASUS=y
|
|
CONFIG_BOARD_ASUS_P8Z77_M_PRO=y
|
|
# CONFIG_USE_NATIVE_RAMINIT is not set
|
|
CONFIG_CPU_MICROCODE_CBFS_NONE=y
|
|
# CONFIG_BOOTBLOCK_CONSOLE is not set
|
|
# CONFIG_POSTCAR_CONSOLE is not set
|
|
```
|
|
|
|
For what we are trying to do, not setting USE_NATIVE_RAMINIT is the
|
|
important part. The other three optional changes are meant to speed
|
|
things up. All these options can be selected during `make menuconfig`.
|
|
|
|
Path to MRC binary blob remains default and thus not included here.
|
|
|
|
Custom configurations can also be put in a file and applied to an entire
|
|
abuild run using -K. Assume for example you are not interested in
|
|
the postcar stage at all and just want it to shut up, you can create
|
|
a file named `myconfig` with this line:
|
|
|
|
```
|
|
# CONFIG_POSTCAR_CONSOLE is not set
|
|
```
|
|
|
|
and run `abuild -K myconfig` to build everything with a silent postcar
|
|
stage.
|
|
|
|
### Selectively build certain targets only (also config file naming caveats)
|
|
|
|
The P8Z77-M PRO example above would fail for P8Z77-M, because the
|
|
config file name is ambiguous. `abuild` would pick up this config when
|
|
building for P8Z77-M, but fails when it sees that this config isn't
|
|
meant for P8Z77-M (but for P8Z77-M PRO). To avoid this error, you have
|
|
to skip this config using --skip_set:
|
|
|
|
```bash
|
|
util/abuild/abuild --skip_set BOARD_ASUS_P8Z77_M_PRO
|
|
```
|
|
|
|
To complete the test, run abuild again specifically for this board
|
|
variant (see next section).
|
|
|
|
You can skip building other targets based on other Kconfigs. To skip
|
|
building targets without a Kconfig set, use --skip_unset:
|
|
|
|
```bash
|
|
util/abuild/abuild --skip_unset USE_NATIVE_RAMINIT
|
|
```
|
|
This example skips building configs not using (Sandy/Ivy Bridge) native
|
|
RAM init.
|
|
|
|
### Additional Examples
|
|
|
|
Many boards have multiple variants. You can build for a specific
|
|
variant of a board:
|
|
|
|
```bash
|
|
util/abuild/abuild -t asus/p8x7x-series -b p8z77-m_pro -p none
|
|
```
|
|
|
|
Many of the boards need files from the 'blobs' repository, which will
|
|
be initialized by the -B option. If the blobs repo has already been
|
|
initialized in your local tree, it won't hurt to add the -B.
|
|
|
|
```bash
|
|
util/abuild/abuild -B -t lenovo/x230 -p none
|
|
```
|
|
|
|
Adding ccache to your system and telling abuild to use it with the -y
|
|
option will speed things up a bit:
|
|
|
|
```bash
|
|
util/abuild/abuild -B -y -t lenovo/x230 -p none
|
|
```
|
|
|
|
Telling abuild to use multiple cores with the -c option helps speed
|
|
things up as well:
|
|
|
|
```bash
|
|
util/abuild/abuild -B -y -c 8 -t lenovo/x230 -p none
|
|
```
|
|
|
|
Of course, the real power of abuild is in testing multiple boards.
|
|
|
|
```bash
|
|
util/abuild/abuild -B -y -c 8 -p none
|
|
```
|
|
|
|
### Full options list
|
|
|
|
```text
|
|
coreboot autobuild v0.11.01 (Feb 3, 2023)
|
|
[...]
|
|
Usage: util/abuild/abuild [options]
|
|
util/abuild/abuild [-V|--version]
|
|
util/abuild/abuild [-h|--help]
|
|
|
|
Options:
|
|
[-a|--all] Build previously succeeded ports as well
|
|
[-A|--any-toolchain] Use any toolchain
|
|
[-b|--board-variant <name>] Build specific board variant under the
|
|
given target.
|
|
[-B|--blobs] Allow using binary files
|
|
[--checksum <path/basefile>] Store checksums at path/basefile
|
|
[-c|--cpus <numcpus>] Build on <numcpus> at the same time
|
|
[-C|--config] Configure-only mode
|
|
[-d|--dir <dir>] Directory containing config files
|
|
[-e|--exitcode] Exit with a non-zero errorlevel on failure
|
|
[-J|--junit] Write JUnit formatted xml log file
|
|
[-K|--kconfig <name>] Prepend file to generated Kconfig
|
|
[-l|--loglevel <num>] Set loglevel
|
|
[-L|--clang] Use clang on supported arch
|
|
[-n|--name] Set build name - also sets xmlfile if not
|
|
already set
|
|
[-o|--outdir <path>] Store build results in path
|
|
(defaults to coreboot-builds)
|
|
[-p|--payloads <dir>] Use payloads in <dir> to build images
|
|
[-P|--prefix <name>] File name prefix in CBFS
|
|
[-q|--quiet] Print fewer messages
|
|
[-r|--remove] Remove output dir after build
|
|
[-R|--root <path>] Absolute path to coreboot sources
|
|
(defaults to /usr/src/coreboot)
|
|
[--scan-build] Use clang's static analyzer
|
|
[--skip_set <value>] Skip building boards with this Kconfig set
|
|
[--skip_unset <value>] Skip building boards with this Kconfig not set
|
|
[--timeless] Generate timeless builds
|
|
[-t|--target <vendor/board>] Attempt to build target vendor/board only
|
|
[-T|--test] Submit image(s) to automated test system
|
|
[-u|--update] Update existing image
|
|
[-v|--verbose] Print more messages
|
|
[-x|--chromeos] Build with CHROMEOS enabled
|
|
Skip boards without ChromeOS support
|
|
[-X|--xmlfile <name>] Set JUnit XML log file filename
|
|
(defaults to /usr/src/coreboot/abuild.xml)
|
|
[-y|--ccache] Use ccache
|
|
[-z|--clean] Remove build results when finished
|
|
[-Z|--clean-somewhat] Remove build but keep coreboot.rom + config
|
|
|
|
[-V|--version] Print version number and exit
|
|
[-h|--help] Print this help and exit
|
|
|
|
[-s|--silent] obsolete
|
|
```
|