1abuild 2====== 3 4This utility is a great tool to check whether your coreboot tree 5compiles for one or all targets. It compiles the 'default' build for a 6mainboard. This is roughly equivalent to removing the .config file, 7running `make menuconfig`, selecting the manufacturer and mainboard, 8then saving the config without making any other changes. 9 10It is run on all patches submitted via gerrit as part of the process. 11Before submitting a patch, it is a very good idea to run abuild first 12to make sure your patch compiles cleanly for all. 13 14Note that abuild is a tool to do a simple build test, and binaries it 15produces may well not boot if flashed to a system. 16 17## Basic usage 18 19abuild needs to be run from the coreboot directory. If you cd into the 20coreboot/util/abuild directory and try to run it from there, it will 21not run correctly. 22 23If you invoke abuild with no parameters, it will build all boards 24automatically. 25 26You can also specify a single board to build with the -t option. For 27example, to build the Lenovo X230 target, run: 28 29```bash 30$ util/abuild/abuild -t lenovo/x230 31``` 32 33## Where builds and logs are stored 34 35The resulting images and logs are stored in directory coreboot-builds/ 36under your current directory. This can be overridden with --outdir: 37 38```bash 39$ util/abuild/abuild --outdir /mnt/portable/coreboot-builds 40``` 41 42This is useful if you want to divert the build to an external hard 43drive, e.g. to keep the solid-state drive holding the coreboot tree 44young. 45 46(We will still refer to this directory as "coreboot-builds" below.) 47 48After running the X230 build above, the build log will be in 49coreboot-builds/LENOVO_X230/make.log. 50 51For an overview of what passed and what failed, look at 52coreboot-builds/passing_boards and coreboot-builds/failing_boards. 53**These logs are overwritten with each abuild run.** Save them elsewhere 54if you feel a need to reference the results later. 55 56## Payloads 57 58You can also specify a payload directory with -p: 59 60```bash 61mkdir payloads 62cp /somewhere/filo.elf payloads 63``` 64 65Then add a file payloads/payload.sh which prints the name of the 66payload to use (and takes the mainboard as a parameter) such as: 67 68```bash 69echo "`dirname $0`/build/filo.elf" 70``` 71 72Then you can build an image with payload by specifying: 73 74```bash 75util/abuild/abuild -t lenovo/x230 -p ./payloads 76``` 77 78You can also tell abuild not to use a payload: 79 80```bash 81util/abuild/abuild -t lenovo/x230 -p none 82``` 83 84## Build non-default configurations 85 86Sometimes you do need to build test a custom, non-default configuration. 87This can be accomplished by placing a config file in configs/. 88 89First, clean your slate with `make distclean` or `rm .config`. 90 91Then run `make menuconfig`, select the manufacturer and mainboard, and 92configure the options you need to test building for. 93 94Then save a minimal config file omitting options that did not change 95from default: 96 97```bash 98make savedefconfig 99``` 100 101This file is saved as `defconfig` and can be edited further. 102 103Now this file can be saved in configs/ which will form the basis of a 104custom configuration included in an abuild. However, it needs to be 105named in a specific way for abuild to pick it up: 106 107``` 108config.<board>_<suffix> 109``` 110 111<board> is effectively the BOARD\_xxx Kconfig option without "BOARD\_". 112<suffix> is a free form description of the configuration being built. 113 114For example, a config for ASUS P8Z77-M PRO that tests building with MRC 115raminit code (as opposed to the default native raminit) would be named 116`config.asus_p8z77_m_pro_mrc_bin` and contains: 117 118``` 119CONFIG_VENDOR_ASUS=y 120CONFIG_BOARD_ASUS_P8Z77_M_PRO=y 121# CONFIG_USE_NATIVE_RAMINIT is not set 122CONFIG_CPU_MICROCODE_CBFS_NONE=y 123# CONFIG_BOOTBLOCK_CONSOLE is not set 124# CONFIG_POSTCAR_CONSOLE is not set 125``` 126 127For what we are trying to do, not setting USE_NATIVE_RAMINIT is the 128important part. The other three optional changes are meant to speed 129things up. All these options can be selected during `make menuconfig`. 130 131Path to MRC binary blob remains default and thus not included here. 132 133Custom configurations can also be put in a file and applied to an entire 134abuild run using -K. Assume for example you are not interested in 135the postcar stage at all and just want it to shut up, you can create 136a file named `myconfig` with this line: 137 138``` 139# CONFIG_POSTCAR_CONSOLE is not set 140``` 141 142and run `abuild -K myconfig` to build everything with a silent postcar 143stage. 144 145## Selectively build certain targets only (also config file naming caveats) 146 147The P8Z77-M PRO example above would fail for P8Z77-M, because the 148config file name is ambiguous. `abuild` would pick up this config when 149building for P8Z77-M, but fails when it sees that this config isn't 150meant for P8Z77-M (but for P8Z77-M PRO). To avoid this error, you have 151to skip this config using --skip_set: 152 153```bash 154util/abuild/abuild --skip_set BOARD_ASUS_P8Z77_M_PRO 155``` 156 157To complete the test, run abuild again specifically for this board 158variant (see next section). 159 160You can skip building other targets based on other Kconfigs. To skip 161building targets without a Kconfig set, use --skip_unset: 162 163```bash 164util/abuild/abuild --skip_unset USE_NATIVE_RAMINIT 165``` 166This example skips building configs not using (Sandy/Ivy Bridge) native 167RAM init. 168 169## Additional Examples 170 171Many boards have multiple variants. You can build for a specific 172variant of a board: 173 174```bash 175util/abuild/abuild -t asus/p8x7x-series -b p8z77-m_pro -p none 176``` 177 178Many of the boards need files from the 'blobs' repository, which will 179be initialized by the -B option. If the blobs repo has already been 180initialized in your local tree, it won't hurt to add the -B. 181 182```bash 183util/abuild/abuild -B -t lenovo/x230 -p none 184``` 185 186Adding ccache to your system and telling abuild to use it with the -y 187option will speed things up a bit: 188 189```bash 190util/abuild/abuild -B -y -t lenovo/x230 -p none 191``` 192 193Telling abuild to use multiple cores with the -c option helps speed 194things up as well: 195 196```bash 197util/abuild/abuild -B -y -c 8 -t lenovo/x230 -p none 198``` 199 200Of course, the real power of abuild is in testing multiple boards. 201 202```bash 203util/abuild/abuild -B -y -c 8 -p none 204``` 205 206## Full options list 207 208```text 209coreboot autobuild v0.11.01 (Feb 3, 2023) 210[...] 211Usage: util/abuild/abuild [options] 212 util/abuild/abuild [-V|--version] 213 util/abuild/abuild [-h|--help] 214 215Options: 216 [-a|--all] Build previously succeeded ports as well 217 [-A|--any-toolchain] Use any toolchain 218 [-b|--board-variant <name>] Build specific board variant under the 219 given target. 220 [-B|--blobs] Allow using binary files 221 [--checksum <path/basefile>] Store checksums at path/basefile 222 [-c|--cpus <numcpus>] Build on <numcpus> at the same time 223 [-C|--config] Configure-only mode 224 [-d|--dir <dir>] Directory containing config files 225 [-e|--exitcode] Exit with a non-zero errorlevel on failure 226 [-J|--junit] Write JUnit formatted xml log file 227 [-K|--kconfig <name>] Prepend file to generated Kconfig 228 [-l|--loglevel <num>] Set loglevel 229 [-L|--clang] Use clang on supported arch 230 [-n|--name] Set build name - also sets xmlfile if not 231 already set 232 [-o|--outdir <path>] Store build results in path 233 (defaults to coreboot-builds) 234 [-p|--payloads <dir>] Use payloads in <dir> to build images 235 [-P|--prefix <name>] File name prefix in CBFS 236 [-q|--quiet] Print fewer messages 237 [-r|--remove] Remove output dir after build 238 [-R|--root <path>] Absolute path to coreboot sources 239 (defaults to /usr/src/coreboot) 240 [--scan-build] Use clang's static analyzer 241 [--skip_set <value>] Skip building boards with this Kconfig set 242 [--skip_unset <value>] Skip building boards with this Kconfig not set 243 [--timeless] Generate timeless builds 244 [-t|--target <vendor/board>] Attempt to build target vendor/board only 245 [-T|--test] Submit image(s) to automated test system 246 [-u|--update] Update existing image 247 [-v|--verbose] Print more messages 248 [-x|--chromeos] Build with CHROMEOS enabled 249 Skip boards without ChromeOS support 250 [-X|--xmlfile <name>] Set JUnit XML log file filename 251 (defaults to /usr/src/coreboot/abuild.xml) 252 [-y|--ccache] Use ccache 253 [-z|--clean] Remove build results when finished 254 [-Z|--clean-somewhat] Remove build but keep coreboot.rom + config 255 256 [-V|--version] Print version number and exit 257 [-h|--help] Print this help and exit 258 259 [-s|--silent] obsolete 260``` 261