8.8 KiB
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:
$ 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:
$ 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:
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:
echo "`dirname $0`/build/filo.elf"
Then you can build an image with payload by specifying:
util/abuild/abuild -t lenovo/x230 -p ./payloads
You can also tell abuild not to use a payload:
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:
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>
is effectively the BOARD_xxx Kconfig option without "BOARD_". 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:
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:
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:
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.
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:
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:
util/abuild/abuild -B -y -c 8 -t lenovo/x230 -p none
Of course, the real power of abuild is in testing multiple boards.
util/abuild/abuild -B -y -c 8 -p none
Full options list
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