1# Copyright (c) 2013 The Chromium OS Authors. 2# 3# SPDX-License-Identifier: GPL-2.0+ 4# 5 6(Please read 'How to change from MAKEALL' if you are used to that tool) 7 8Quick-start 9=========== 10 11If you just want to quickly set up buildman so you can build something (for 12example Raspberry Pi 2): 13 14 cd /path/to/u-boot 15 PATH=$PATH:`pwd`/tools/buildman 16 buildman --fetch-arch arm 17 buildman -k rpi_2 18 ls ../current/rpi_2 19 # u-boot.bin is the output image 20 21 22What is this? 23============= 24 25This tool handles building U-Boot to check that you have not broken it 26with your patch series. It can build each individual commit and report 27which boards fail on which commits, and which errors come up. It aims 28to make full use of multi-processor machines. 29 30A key feature of buildman is its output summary, which allows warnings, 31errors or image size increases in a particular commit or board to be 32quickly identified and the offending commit pinpointed. This can be a big 33help for anyone working with >10 patches at a time. 34 35 36Caveats 37======= 38 39Buildman can be stopped and restarted, in which case it will continue 40where it left off. This should happen cleanly and without side-effects. 41If not, it is a bug, for which a patch would be welcome. 42 43Buildman gets so tied up in its work that it can ignore the outside world. 44You may need to press Ctrl-C several times to quit it. Also it will print 45out various exceptions when stopped. You may have to kill it since the 46Ctrl-C handling is somewhat broken. 47 48 49Theory of Operation 50=================== 51 52(please read this section in full twice or you will be perpetually confused) 53 54Buildman is a builder. It is not make, although it runs make. It does not 55produce any useful output on the terminal while building, except for 56progress information (except with -v, see below). All the output (errors, 57warnings and binaries if you ask for them) is stored in output 58directories, which you can look at while the build is progressing, or when 59it is finished. 60 61Buildman is designed to build entire git branches, i.e. muliple commits. It 62can be run repeatedly on the same branch. In this case it will automatically 63rebuild commits which have changed (and remove its old results for that 64commit). It is possible to build a branch for one board, then later build it 65for another board. If you want buildman to re-build a commit it has already 66built (e.g. because of a toolchain update), use the -f flag. 67 68Buildman produces a concise summary of which boards succeeded and failed. 69It shows which commit introduced which board failure using a simple 70red/green colour coding. Full error information can be requested, in which 71case it is de-duped and displayed against the commit that introduced the 72error. An example workflow is below. 73 74Buildman stores image size information and can report changes in image size 75from commit to commit. An example of this is below. 76 77Buildman starts multiple threads, and each thread builds for one board at 78a time. A thread starts at the first commit, configures the source for your 79board and builds it. Then it checks out the next commit and does an 80incremental build. Eventually the thread reaches the last commit and stops. 81If errors or warnings are found along the way, the thread will reconfigure 82after every commit, and your build will be very slow. This is because a 83file that produces just a warning would not normally be rebuilt in an 84incremental build. 85 86Buildman works in an entirely separate place from your U-Boot repository. 87It creates a separate working directory for each thread, and puts the 88output files in the working directory, organised by commit name and board 89name, in a two-level hierarchy. 90 91Buildman is invoked in your U-Boot directory, the one with the .git 92directory. It clones this repository into a copy for each thread, and the 93threads do not affect the state of your git repository. Any checkouts done 94by the thread affect only the working directory for that thread. 95 96Buildman automatically selects the correct tool chain for each board. You 97must supply suitable tool chains, but buildman takes care of selecting the 98right one. 99 100Buildman generally builds a branch (with the -b flag), and in this case 101builds the upstream commit as well, for comparison. It cannot build 102individual commits at present, unless (maybe) you point it at an empty 103branch. Put all your commits in a branch, set the branch's upstream to a 104valid value, and all will be well. Otherwise buildman will perform random 105actions. Use -n to check what the random actions might be. 106 107If you just want to build the current source tree, leave off the -b flag 108and add -e. This will display results and errors as they happen. You can 109still look at them later using -se. Note that buildman will assume that the 110source has changed, and will build all specified boards in this case. 111 112Buildman is optimised for building many commits at once, for many boards. 113On multi-core machines, Buildman is fast because it uses most of the 114available CPU power. When it gets to the end, or if you are building just 115a few commits or boards, it will be pretty slow. As a tip, if you don't 116plan to use your machine for anything else, you can use -T to increase the 117number of threads beyond the default. 118 119Buildman lets you build all boards, or a subset. Specify the subset by passing 120command-line arguments that list the desired board name, architecture name, 121SOC name, or anything else in the boards.cfg file. Multiple arguments are 122allowed. Each argument will be interpreted as a regular expression, so 123behaviour is a superset of exact or substring matching. Examples are: 124 125* 'tegra20' All boards with a Tegra20 SoC 126* 'tegra' All boards with any Tegra Soc (Tegra20, Tegra30, Tegra114...) 127* '^tegra[23]0$' All boards with either Tegra20 or Tegra30 SoC 128* 'powerpc' All PowerPC boards 129 130While the default is to OR the terms together, you can also make use of 131the '&' operator to limit the selection: 132 133* 'freescale & arm sandbox' All Freescale boards with ARM architecture, 134 plus sandbox 135 136You can also use -x to specifically exclude some boards. For example: 137 138 buildmand arm -x nvidia,freescale,.*ball$ 139 140means to build all arm boards except nvidia, freescale and anything ending 141with 'ball'. 142 143It is convenient to use the -n option to see what will be built based on 144the subset given. Use -v as well to get an actual list of boards. 145 146Buildman does not store intermediate object files. It optionally copies 147the binary output into a directory when a build is successful. Size 148information is always recorded. It needs a fair bit of disk space to work, 149typically 250MB per thread. 150 151 152Setting up 153========== 154 1551. Get the U-Boot source. You probably already have it, but if not these 156steps should get you started with a repo and some commits for testing. 157 158$ cd /path/to/u-boot 159$ git clone git://git.denx.de/u-boot.git . 160$ git checkout -b my-branch origin/master 161$ # Add some commits to the branch, reading for testing 162 1632. Create ~/.buildman to tell buildman where to find tool chains (see 'The 164.buildman file' later for details). As an example: 165 166# Buildman settings file 167 168[toolchain] 169root: / 170rest: /toolchains/* 171eldk: /opt/eldk-4.2 172arm: /opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux 173aarch64: /opt/linaro/gcc-linaro-aarch64-none-elf-4.8-2013.10_linux 174 175[toolchain-alias] 176x86: i386 177blackfin: bfin 178nds32: nds32le 179openrisc: or1k 180 181 182This selects the available toolchain paths. Add the base directory for 183each of your toolchains here. Buildman will search inside these directories 184and also in any '/usr' and '/usr/bin' subdirectories. 185 186Make sure the tags (here root: rest: and eldk:) are unique. 187 188The toolchain-alias section indicates that the i386 toolchain should be used 189to build x86 commits. 190 191Note that you can also specific exactly toolchain prefixes if you like: 192 193[toolchain-prefix] 194arm: /opt/arm-eabi-4.6/bin/arm-eabi- 195 196or even: 197 198[toolchain-prefix] 199arm: /opt/arm-eabi-4.6/bin/arm-eabi-gcc 200 201This tells buildman that you want to use this exact toolchain for the arm 202architecture. This will override any toolchains found by searching using the 203[toolchain] settings. 204 205Since the toolchain prefix is an explicit request, buildman will report an 206error if a toolchain is not found with that prefix. The current PATH will be 207searched, so it is possible to use: 208 209[toolchain-prefix] 210arm: arm-none-eabi- 211 212and buildman will find arm-none-eabi-gcc in /usr/bin if you have it installed. 213 214[toolchain-wrapper] 215wrapper: ccache 216 217This tells buildman to use a compiler wrapper in front of CROSS_COMPILE. In 218this example, ccache. It doesn't affect the toolchain scan. The wrapper is 219added when CROSS_COMPILE environtal variable is set. The name in this 220section is ignored. If more than one line is provided, only the last one 221is taken. 222 2233. Make sure you have the require Python pre-requisites 224 225Buildman uses multiprocessing, Queue, shutil, StringIO, ConfigParser and 226urllib2. These should normally be available, but if you get an error like 227this then you will need to obtain those modules: 228 229 ImportError: No module named multiprocessing 230 231 2324. Check the available toolchains 233 234Run this check to make sure that you have a toolchain for every architecture. 235 236$ ./tools/buildman/buildman --list-tool-chains 237Scanning for tool chains 238 - scanning prefix '/opt/gcc-4.6.3-nolibc/x86_64-linux/bin/x86_64-linux-' 239Tool chain test: OK, arch='x86', priority 1 240 - scanning prefix '/opt/arm-eabi-4.6/bin/arm-eabi-' 241Tool chain test: OK, arch='arm', priority 1 242 - scanning path '/toolchains/gcc-4.9.0-nolibc/i386-linux' 243 - looking in '/toolchains/gcc-4.9.0-nolibc/i386-linux/.' 244 - looking in '/toolchains/gcc-4.9.0-nolibc/i386-linux/bin' 245 - found '/toolchains/gcc-4.9.0-nolibc/i386-linux/bin/i386-linux-gcc' 246 - looking in '/toolchains/gcc-4.9.0-nolibc/i386-linux/usr/bin' 247Tool chain test: OK, arch='i386', priority 4 248 - scanning path '/toolchains/gcc-4.9.0-nolibc/aarch64-linux' 249 - looking in '/toolchains/gcc-4.9.0-nolibc/aarch64-linux/.' 250 - looking in '/toolchains/gcc-4.9.0-nolibc/aarch64-linux/bin' 251 - found '/toolchains/gcc-4.9.0-nolibc/aarch64-linux/bin/aarch64-linux-gcc' 252 - looking in '/toolchains/gcc-4.9.0-nolibc/aarch64-linux/usr/bin' 253Tool chain test: OK, arch='aarch64', priority 4 254 - scanning path '/toolchains/gcc-4.9.0-nolibc/microblaze-linux' 255 - looking in '/toolchains/gcc-4.9.0-nolibc/microblaze-linux/.' 256 - looking in '/toolchains/gcc-4.9.0-nolibc/microblaze-linux/bin' 257 - found '/toolchains/gcc-4.9.0-nolibc/microblaze-linux/bin/microblaze-linux-gcc' 258 - looking in '/toolchains/gcc-4.9.0-nolibc/microblaze-linux/usr/bin' 259Tool chain test: OK, arch='microblaze', priority 4 260 - scanning path '/toolchains/gcc-4.9.0-nolibc/mips64-linux' 261 - looking in '/toolchains/gcc-4.9.0-nolibc/mips64-linux/.' 262 - looking in '/toolchains/gcc-4.9.0-nolibc/mips64-linux/bin' 263 - found '/toolchains/gcc-4.9.0-nolibc/mips64-linux/bin/mips64-linux-gcc' 264 - looking in '/toolchains/gcc-4.9.0-nolibc/mips64-linux/usr/bin' 265Tool chain test: OK, arch='mips64', priority 4 266 - scanning path '/toolchains/gcc-4.9.0-nolibc/sparc64-linux' 267 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc64-linux/.' 268 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc64-linux/bin' 269 - found '/toolchains/gcc-4.9.0-nolibc/sparc64-linux/bin/sparc64-linux-gcc' 270 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc64-linux/usr/bin' 271Tool chain test: OK, arch='sparc64', priority 4 272 - scanning path '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi' 273 - looking in '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi/.' 274 - looking in '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi/bin' 275 - found '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi/bin/arm-unknown-linux-gnueabi-gcc' 276 - looking in '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi/usr/bin' 277Tool chain test: OK, arch='arm', priority 3 278Toolchain '/toolchains/gcc-4.9.0-nolibc/arm-unknown-linux-gnueabi/bin/arm-unknown-linux-gnueabi-gcc' at priority 3 will be ignored because another toolchain for arch 'arm' has priority 1 279 - scanning path '/toolchains/gcc-4.9.0-nolibc/sparc-linux' 280 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc-linux/.' 281 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc-linux/bin' 282 - found '/toolchains/gcc-4.9.0-nolibc/sparc-linux/bin/sparc-linux-gcc' 283 - looking in '/toolchains/gcc-4.9.0-nolibc/sparc-linux/usr/bin' 284Tool chain test: OK, arch='sparc', priority 4 285 - scanning path '/toolchains/gcc-4.9.0-nolibc/mips-linux' 286 - looking in '/toolchains/gcc-4.9.0-nolibc/mips-linux/.' 287 - looking in '/toolchains/gcc-4.9.0-nolibc/mips-linux/bin' 288 - found '/toolchains/gcc-4.9.0-nolibc/mips-linux/bin/mips-linux-gcc' 289 - looking in '/toolchains/gcc-4.9.0-nolibc/mips-linux/usr/bin' 290Tool chain test: OK, arch='mips', priority 4 291 - scanning path '/toolchains/gcc-4.9.0-nolibc/x86_64-linux' 292 - looking in '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/.' 293 - looking in '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/bin' 294 - found '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/bin/x86_64-linux-gcc' 295 - found '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/bin/x86_64-linux-x86_64-linux-gcc' 296 - looking in '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/usr/bin' 297Tool chain test: OK, arch='x86_64', priority 4 298Tool chain test: OK, arch='x86_64', priority 4 299Toolchain '/toolchains/gcc-4.9.0-nolibc/x86_64-linux/bin/x86_64-linux-x86_64-linux-gcc' at priority 4 will be ignored because another toolchain for arch 'x86_64' has priority 4 300 - scanning path '/toolchains/gcc-4.9.0-nolibc/m68k-linux' 301 - looking in '/toolchains/gcc-4.9.0-nolibc/m68k-linux/.' 302 - looking in '/toolchains/gcc-4.9.0-nolibc/m68k-linux/bin' 303 - found '/toolchains/gcc-4.9.0-nolibc/m68k-linux/bin/m68k-linux-gcc' 304 - looking in '/toolchains/gcc-4.9.0-nolibc/m68k-linux/usr/bin' 305Tool chain test: OK, arch='m68k', priority 4 306 - scanning path '/toolchains/gcc-4.9.0-nolibc/powerpc-linux' 307 - looking in '/toolchains/gcc-4.9.0-nolibc/powerpc-linux/.' 308 - looking in '/toolchains/gcc-4.9.0-nolibc/powerpc-linux/bin' 309 - found '/toolchains/gcc-4.9.0-nolibc/powerpc-linux/bin/powerpc-linux-gcc' 310 - looking in '/toolchains/gcc-4.9.0-nolibc/powerpc-linux/usr/bin' 311Tool chain test: OK, arch='powerpc', priority 4 312 - scanning path '/toolchains/gcc-4.6.3-nolibc/bfin-uclinux' 313 - looking in '/toolchains/gcc-4.6.3-nolibc/bfin-uclinux/.' 314 - looking in '/toolchains/gcc-4.6.3-nolibc/bfin-uclinux/bin' 315 - found '/toolchains/gcc-4.6.3-nolibc/bfin-uclinux/bin/bfin-uclinux-gcc' 316 - looking in '/toolchains/gcc-4.6.3-nolibc/bfin-uclinux/usr/bin' 317Tool chain test: OK, arch='bfin', priority 6 318 - scanning path '/toolchains/gcc-4.6.3-nolibc/sparc-linux' 319 - looking in '/toolchains/gcc-4.6.3-nolibc/sparc-linux/.' 320 - looking in '/toolchains/gcc-4.6.3-nolibc/sparc-linux/bin' 321 - found '/toolchains/gcc-4.6.3-nolibc/sparc-linux/bin/sparc-linux-gcc' 322 - looking in '/toolchains/gcc-4.6.3-nolibc/sparc-linux/usr/bin' 323Tool chain test: OK, arch='sparc', priority 4 324Toolchain '/toolchains/gcc-4.6.3-nolibc/sparc-linux/bin/sparc-linux-gcc' at priority 4 will be ignored because another toolchain for arch 'sparc' has priority 4 325 - scanning path '/toolchains/gcc-4.6.3-nolibc/mips-linux' 326 - looking in '/toolchains/gcc-4.6.3-nolibc/mips-linux/.' 327 - looking in '/toolchains/gcc-4.6.3-nolibc/mips-linux/bin' 328 - found '/toolchains/gcc-4.6.3-nolibc/mips-linux/bin/mips-linux-gcc' 329 - looking in '/toolchains/gcc-4.6.3-nolibc/mips-linux/usr/bin' 330Tool chain test: OK, arch='mips', priority 4 331Toolchain '/toolchains/gcc-4.6.3-nolibc/mips-linux/bin/mips-linux-gcc' at priority 4 will be ignored because another toolchain for arch 'mips' has priority 4 332 - scanning path '/toolchains/gcc-4.6.3-nolibc/m68k-linux' 333 - looking in '/toolchains/gcc-4.6.3-nolibc/m68k-linux/.' 334 - looking in '/toolchains/gcc-4.6.3-nolibc/m68k-linux/bin' 335 - found '/toolchains/gcc-4.6.3-nolibc/m68k-linux/bin/m68k-linux-gcc' 336 - looking in '/toolchains/gcc-4.6.3-nolibc/m68k-linux/usr/bin' 337Tool chain test: OK, arch='m68k', priority 4 338Toolchain '/toolchains/gcc-4.6.3-nolibc/m68k-linux/bin/m68k-linux-gcc' at priority 4 will be ignored because another toolchain for arch 'm68k' has priority 4 339 - scanning path '/toolchains/gcc-4.6.3-nolibc/powerpc-linux' 340 - looking in '/toolchains/gcc-4.6.3-nolibc/powerpc-linux/.' 341 - looking in '/toolchains/gcc-4.6.3-nolibc/powerpc-linux/bin' 342 - found '/toolchains/gcc-4.6.3-nolibc/powerpc-linux/bin/powerpc-linux-gcc' 343 - looking in '/toolchains/gcc-4.6.3-nolibc/powerpc-linux/usr/bin' 344Tool chain test: OK, arch='powerpc', priority 4 345Tool chain test: OK, arch='or32', priority 4 346 - scanning path '/' 347 - looking in '/.' 348 - looking in '/bin' 349 - looking in '/usr/bin' 350 - found '/usr/bin/i586-mingw32msvc-gcc' 351 - found '/usr/bin/c89-gcc' 352 - found '/usr/bin/x86_64-linux-gnu-gcc' 353 - found '/usr/bin/gcc' 354 - found '/usr/bin/c99-gcc' 355 - found '/usr/bin/arm-linux-gnueabi-gcc' 356 - found '/usr/bin/aarch64-linux-gnu-gcc' 357 - found '/usr/bin/winegcc' 358 - found '/usr/bin/arm-linux-gnueabihf-gcc' 359Tool chain test: OK, arch='i586', priority 11 360Tool chain test: OK, arch='c89', priority 11 361Tool chain test: OK, arch='x86_64', priority 4 362Toolchain '/usr/bin/x86_64-linux-gnu-gcc' at priority 4 will be ignored because another toolchain for arch 'x86_64' has priority 4 363Tool chain test: OK, arch='sandbox', priority 11 364Tool chain test: OK, arch='c99', priority 11 365Tool chain test: OK, arch='arm', priority 4 366Toolchain '/usr/bin/arm-linux-gnueabi-gcc' at priority 4 will be ignored because another toolchain for arch 'arm' has priority 1 367Tool chain test: OK, arch='aarch64', priority 4 368Toolchain '/usr/bin/aarch64-linux-gnu-gcc' at priority 4 will be ignored because another toolchain for arch 'aarch64' has priority 4 369Tool chain test: OK, arch='sandbox', priority 11 370Toolchain '/usr/bin/winegcc' at priority 11 will be ignored because another toolchain for arch 'sandbox' has priority 11 371Tool chain test: OK, arch='arm', priority 4 372Toolchain '/usr/bin/arm-linux-gnueabihf-gcc' at priority 4 will be ignored because another toolchain for arch 'arm' has priority 1 373List of available toolchains (34): 374aarch64 : /toolchains/gcc-4.9.0-nolibc/aarch64-linux/bin/aarch64-linux-gcc 375alpha : /toolchains/gcc-4.9.0-nolibc/alpha-linux/bin/alpha-linux-gcc 376am33_2.0 : /toolchains/gcc-4.9.0-nolibc/am33_2.0-linux/bin/am33_2.0-linux-gcc 377arm : /opt/arm-eabi-4.6/bin/arm-eabi-gcc 378bfin : /toolchains/gcc-4.6.3-nolibc/bfin-uclinux/bin/bfin-uclinux-gcc 379c89 : /usr/bin/c89-gcc 380c99 : /usr/bin/c99-gcc 381frv : /toolchains/gcc-4.9.0-nolibc/frv-linux/bin/frv-linux-gcc 382h8300 : /toolchains/gcc-4.9.0-nolibc/h8300-elf/bin/h8300-elf-gcc 383hppa : /toolchains/gcc-4.9.0-nolibc/hppa-linux/bin/hppa-linux-gcc 384hppa64 : /toolchains/gcc-4.9.0-nolibc/hppa64-linux/bin/hppa64-linux-gcc 385i386 : /toolchains/gcc-4.9.0-nolibc/i386-linux/bin/i386-linux-gcc 386i586 : /usr/bin/i586-mingw32msvc-gcc 387ia64 : /toolchains/gcc-4.9.0-nolibc/ia64-linux/bin/ia64-linux-gcc 388m32r : /toolchains/gcc-4.9.0-nolibc/m32r-linux/bin/m32r-linux-gcc 389m68k : /toolchains/gcc-4.9.0-nolibc/m68k-linux/bin/m68k-linux-gcc 390microblaze: /toolchains/gcc-4.9.0-nolibc/microblaze-linux/bin/microblaze-linux-gcc 391mips : /toolchains/gcc-4.9.0-nolibc/mips-linux/bin/mips-linux-gcc 392mips64 : /toolchains/gcc-4.9.0-nolibc/mips64-linux/bin/mips64-linux-gcc 393or32 : /toolchains/gcc-4.5.1-nolibc/or32-linux/bin/or32-linux-gcc 394powerpc : /toolchains/gcc-4.9.0-nolibc/powerpc-linux/bin/powerpc-linux-gcc 395powerpc64 : /toolchains/gcc-4.9.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcc 396ppc64le : /toolchains/gcc-4.9.0-nolibc/ppc64le-linux/bin/ppc64le-linux-gcc 397s390x : /toolchains/gcc-4.9.0-nolibc/s390x-linux/bin/s390x-linux-gcc 398sandbox : /usr/bin/gcc 399sh4 : /toolchains/gcc-4.6.3-nolibc/sh4-linux/bin/sh4-linux-gcc 400sparc : /toolchains/gcc-4.9.0-nolibc/sparc-linux/bin/sparc-linux-gcc 401sparc64 : /toolchains/gcc-4.9.0-nolibc/sparc64-linux/bin/sparc64-linux-gcc 402tilegx : /toolchains/gcc-4.6.2-nolibc/tilegx-linux/bin/tilegx-linux-gcc 403x86 : /opt/gcc-4.6.3-nolibc/x86_64-linux/bin/x86_64-linux-gcc 404x86_64 : /toolchains/gcc-4.9.0-nolibc/x86_64-linux/bin/x86_64-linux-gcc 405 406 407You can see that everything is covered, even some strange ones that won't 408be used (c88 and c99). This is a feature. 409 410 4115. Install new toolchains if needed 412 413You can download toolchains and update the [toolchain] section of the 414settings file to find them. 415 416To make this easier, buildman can automatically download and install 417toolchains from kernel.org. First list the available architectures: 418 419$ ./tools/buildman/buildman --fetch-arch list 420Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.6.3/ 421Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.6.2/ 422Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.5.1/ 423Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.2.4/ 424Available architectures: alpha am33_2.0 arm bfin cris crisv32 frv h8300 425hppa hppa64 i386 ia64 m32r m68k mips mips64 or32 powerpc powerpc64 s390x sh4 426sparc sparc64 tilegx x86_64 xtensa 427 428Then pick one and download it: 429 430$ ./tools/buildman/buildman --fetch-arch or32 431Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.6.3/ 432Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.6.2/ 433Checking: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.5.1/ 434Downloading: https://www.kernel.org/pub/tools/crosstool/files/bin/x86_64/4.5.1//x86_64-gcc-4.5.1-nolibc_or32-linux.tar.xz 435Unpacking to: /home/sjg/.buildman-toolchains 436Testing 437 - looking in '/home/sjg/.buildman-toolchains/gcc-4.5.1-nolibc/or32-linux/.' 438 - looking in '/home/sjg/.buildman-toolchains/gcc-4.5.1-nolibc/or32-linux/bin' 439 - found '/home/sjg/.buildman-toolchains/gcc-4.5.1-nolibc/or32-linux/bin/or32-linux-gcc' 440Tool chain test: OK 441 442Or download them all from kernel.org and move them to /toolchains directory, 443 444$ ./tools/buildman/buildman --fetch-arch all 445$ sudo mkdir -p /toolchains 446$ sudo mv ~/.buildman-toolchains/*/* /toolchains/ 447 448For those not available from kernel.org, download from the following links. 449 450arc: https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases/ 451 download/arc-2016.09-release/arc_gnu_2016.09_prebuilt_uclibc_le_archs_linux_install.tar.gz 452blackfin: http://sourceforge.net/projects/adi-toolchain/files/ 453 blackfin-toolchain-elf-gcc-4.5-2014R1_45-RC2.x86_64.tar.bz2 454nds32: http://osdk.andestech.com/packages/ 455 nds32le-linux-glibc-v1.tgz 456nios2: http://sourcery.mentor.com/public/gnu_toolchain/nios2-linux-gnu/ 457 sourceryg++-2015.11-27-nios2-linux-gnu-i686-pc-linux-gnu.tar.bz2 458sh: http://sourcery.mentor.com/public/gnu_toolchain/sh-linux-gnu/ 459 renesas-4.4-200-sh-linux-gnu-i686-pc-linux-gnu.tar.bz2 460 461Note openrisc kernel.org toolchain is out of date. Download the latest one from 462http://opencores.org/or1k/OpenRISC_GNU_tool_chain#Prebuilt_versions - eg: 463ftp://ocuser:ocuser@openrisc.opencores.org/toolchain/gcc-or1k-elf-4.8.1-x86.tar.bz2. 464 465Buildman should now be set up to use your new toolchain. 466 467At the time of writing, U-Boot has these architectures: 468 469 arc, arm, blackfin, m68k, microblaze, mips, nds32, nios2, openrisc 470 powerpc, sandbox, sh, sparc, x86 471 472Of these, only arc and nds32 are not available at kernel.org.. 473 474 475How to run it 476============= 477 478First do a dry run using the -n flag: (replace <branch> with a real, local 479branch with a valid upstream) 480 481$ ./tools/buildman/buildman -b <branch> -n 482 483If it can't detect the upstream branch, try checking out the branch, and 484doing something like 'git branch --set-upstream-to upstream/master' 485or something similar. Buildman will try to guess a suitable upstream branch 486if it can't find one (you will see a message like" Guessing upstream as ...). 487 488As an example: 489 490Dry run, so not doing much. But I would do this: 491 492Building 18 commits for 1059 boards (4 threads, 1 job per thread) 493Build directory: ../lcd9b 494 5bb3505 Merge branch 'master' of git://git.denx.de/u-boot-arm 495 c18f1b4 tegra: Use const for pinmux_config_pingroup/table() 496 2f043ae tegra: Add display support to funcmux 497 e349900 tegra: fdt: Add pwm binding and node 498 424a5f0 tegra: fdt: Add LCD definitions for Tegra 499 0636ccf tegra: Add support for PWM 500 a994fe7 tegra: Add SOC support for display/lcd 501 fcd7350 tegra: Add LCD driver 502 4d46e9d tegra: Add LCD support to Nvidia boards 503 991bd48 arm: Add control over cachability of memory regions 504 54e8019 lcd: Add CONFIG_LCD_ALIGNMENT to select frame buffer alignment 505 d92aff7 lcd: Add support for flushing LCD fb from dcache after update 506 dbd0677 tegra: Align LCD frame buffer to section boundary 507 0cff9b8 tegra: Support control of cache settings for LCD 508 9c56900 tegra: fdt: Add LCD definitions for Seaboard 509 5cc29db lcd: Add CONFIG_CONSOLE_SCROLL_LINES option to speed console 510 cac5a23 tegra: Enable display/lcd support on Seaboard 511 49ff541 wip 512 513Total boards to build for each commit: 1059 514 515This shows that it will build all 1059 boards, using 4 threads (because 516we have a 4-core CPU). Each thread will run with -j1, meaning that each 517make job will use a single CPU. The list of commits to be built helps you 518confirm that things look about right. Notice that buildman has chosen a 519'base' directory for you, immediately above your source tree. 520 521Buildman works entirely inside the base directory, here ../lcd9b, 522creating a working directory for each thread, and creating output 523directories for each commit and board. 524 525 526Suggested Workflow 527================== 528 529To run the build for real, take off the -n: 530 531$ ./tools/buildman/buildman -b <branch> 532 533Buildman will set up some working directories, and get started. After a 534minute or so it will settle down to a steady pace, with a display like this: 535 536Building 18 commits for 1059 boards (4 threads, 1 job per thread) 537 528 36 124 /19062 1:13:30 : SIMPC8313_SP 538 539This means that it is building 19062 board/commit combinations. So far it 540has managed to successfully build 528. Another 36 have built with warnings, 541and 124 more didn't build at all. Buildman expects to complete the process 542in around an hour and a quarter. Use this time to buy a faster computer. 543 544 545To find out how the build went, ask for a summary with -s. You can do this 546either before the build completes (presumably in another terminal) or 547afterwards. Let's work through an example of how this is used: 548 549$ ./tools/buildman/buildman -b lcd9b -s 550... 55101: Merge branch 'master' of git://git.denx.de/u-boot-arm 552 powerpc: + galaxy5200_LOWBOOT 55302: tegra: Use const for pinmux_config_pingroup/table() 55403: tegra: Add display support to funcmux 55504: tegra: fdt: Add pwm binding and node 55605: tegra: fdt: Add LCD definitions for Tegra 55706: tegra: Add support for PWM 55807: tegra: Add SOC support for display/lcd 55908: tegra: Add LCD driver 56009: tegra: Add LCD support to Nvidia boards 56110: arm: Add control over cachability of memory regions 56211: lcd: Add CONFIG_LCD_ALIGNMENT to select frame buffer alignment 56312: lcd: Add support for flushing LCD fb from dcache after update 564 arm: + lubbock 56513: tegra: Align LCD frame buffer to section boundary 56614: tegra: Support control of cache settings for LCD 56715: tegra: fdt: Add LCD definitions for Seaboard 56816: lcd: Add CONFIG_CONSOLE_SCROLL_LINES option to speed console 56917: tegra: Enable display/lcd support on Seaboard 57018: wip 571 572This shows which commits have succeeded and which have failed. In this case 573the build is still in progress so many boards are not built yet (use -u to 574see which ones). But still we can see a few failures. The galaxy5200_LOWBOOT 575never builds correctly. This could be a problem with our toolchain, or it 576could be a bug in the upstream. The good news is that we probably don't need 577to blame our commits. The bad news is that our commits are not tested on that 578board. 579 580Commit 12 broke lubbock. That's what the '+ lubbock' means. The failure 581is never fixed by a later commit, or you would see lubbock again, in green, 582without the +. 583 584To see the actual error: 585 586$ ./tools/buildman/buildman -b <branch> -se lubbock 587... 58812: lcd: Add support for flushing LCD fb from dcache after update 589 arm: + lubbock 590+common/libcommon.o: In function `lcd_sync': 591+/u-boot/lcd9b/.bm-work/00/common/lcd.c:120: undefined reference to `flush_dcache_range' 592+arm-none-linux-gnueabi-ld: BFD (Sourcery G++ Lite 2010q1-202) 2.19.51.20090709 assertion fail /scratch/julian/2010q1-release-linux-lite/obj/binutils-src-2010q1-202-arm-none-linux-gnueabi-i686-pc-linux-gnu/bfd/elf32-arm.c:12572 593+make: *** [/u-boot/lcd9b/.bm-work/00/build/u-boot] Error 139 59413: tegra: Align LCD frame buffer to section boundary 59514: tegra: Support control of cache settings for LCD 59615: tegra: fdt: Add LCD definitions for Seaboard 59716: lcd: Add CONFIG_CONSOLE_SCROLL_LINES option to speed console 598-/u-boot/lcd9b/.bm-work/00/common/lcd.c:120: undefined reference to `flush_dcache_range' 599+/u-boot/lcd9b/.bm-work/00/common/lcd.c:125: undefined reference to `flush_dcache_range' 60017: tegra: Enable display/lcd support on Seaboard 60118: wip 602 603So the problem is in lcd.c, due to missing cache operations. This information 604should be enough to work out what that commit is doing to break these 605boards. (In this case pxa did not have cache operations defined). 606 607If you see error lines marked with '-', that means that the errors were fixed 608by that commit. Sometimes commits can be in the wrong order, so that a 609breakage is introduced for a few commits and fixed by later commits. This 610shows up clearly with buildman. You can then reorder the commits and try 611again. 612 613At commit 16, the error moves: you can see that the old error at line 120 614is fixed, but there is a new one at line 126. This is probably only because 615we added some code and moved the broken line further down the file. 616 617If many boards have the same error, then -e will display the error only 618once. This makes the output as concise as possible. To see which boards have 619each error, use -l. So it is safe to omit the board name - you will not get 620lots of repeated output for every board. 621 622Buildman tries to distinguish warnings from errors, and shows warning lines 623separately with a 'w' prefix. 624 625The full build output in this case is available in: 626 627../lcd9b/12_of_18_gd92aff7_lcd--Add-support-for/lubbock/ 628 629 done: Indicates the build was done, and holds the return code from make. 630 This is 0 for a good build, typically 2 for a failure. 631 632 err: Output from stderr, if any. Errors and warnings appear here. 633 634 log: Output from stdout. Normally there isn't any since buildman runs 635 in silent mode. Use -V to force a verbose build (this passes V=1 636 to 'make') 637 638 toolchain: Shows information about the toolchain used for the build. 639 640 sizes: Shows image size information. 641 642It is possible to get the build binary output there also. Use the -k option 643for this. In that case you will also see some output files, like: 644 645 System.map toolchain u-boot u-boot.bin u-boot.map autoconf.mk 646 (also SPL versions u-boot-spl and u-boot-spl.bin if available) 647 648 649Checking Image Sizes 650==================== 651 652A key requirement for U-Boot is that you keep code/data size to a minimum. 653Where a new feature increases this noticeably it should normally be put 654behind a CONFIG flag so that boards can leave it disabled and keep the image 655size more or less the same with each new release. 656 657To check the impact of your commits on image size, use -S. For example: 658 659$ ./tools/buildman/buildman -b us-x86 -sS 660Summary of 10 commits for 1066 boards (4 threads, 1 job per thread) 66101: MAKEALL: add support for per architecture toolchains 66202: x86: Add function to get top of usable ram 663 x86: (for 1/3 boards) text -272.0 rodata +41.0 66403: x86: Add basic cache operations 66504: x86: Permit bootstage and timer data to be used prior to relocation 666 x86: (for 1/3 boards) data +16.0 66705: x86: Add an __end symbol to signal the end of the U-Boot binary 668 x86: (for 1/3 boards) text +76.0 66906: x86: Rearrange the output input to remove BSS 670 x86: (for 1/3 boards) bss -2140.0 67107: x86: Support relocation of FDT on start-up 672 x86: + coreboot-x86 67308: x86: Add error checking to x86 relocation code 67409: x86: Adjust link device tree include file 67510: x86: Enable CONFIG_OF_CONTROL on coreboot 676 677 678You can see that image size only changed on x86, which is good because this 679series is not supposed to change any other board. From commit 7 onwards the 680build fails so we don't get code size numbers. The numbers are fractional 681because they are an average of all boards for that architecture. The 682intention is to allow you to quickly find image size problems introduced by 683your commits. 684 685Note that the 'text' region and 'rodata' are split out. You should add the 686two together to get the total read-only size (reported as the first column 687in the output from binutil's 'size' utility). 688 689A useful option is --step which lets you skip some commits. For example 690--step 2 will show the image sizes for only every 2nd commit (so it will 691compare the image sizes of the 1st, 3rd, 5th... commits). You can also use 692--step 0 which will compare only the first and last commits. This is useful 693for an overview of how your entire series affects code size. It will build 694only the upstream commit and your final branch commit. 695 696You can also use -d to see a detailed size breakdown for each board. This 697list is sorted in order from largest growth to largest reduction. 698 699It is even possible to go a little further with the -B option (--bloat). This 700shows where U-Boot has bloated, breaking the size change down to the function 701level. Example output is below: 702 703$ ./tools/buildman/buildman -b us-mem4 -sSdB 704... 70519: Roll crc32 into hash infrastructure 706 arm: (for 10/10 boards) all -143.4 bss +1.2 data -4.8 rodata -48.2 text -91.6 707 paz00 : all +23 bss -4 rodata -29 text +56 708 u-boot: add: 1/0, grow: 3/-2 bytes: 168/-104 (64) 709 function old new delta 710 hash_command 80 160 +80 711 crc32_wd_buf - 56 +56 712 ext4fs_read_file 540 568 +28 713 insert_var_value_sub 688 692 +4 714 run_list_real 1996 1992 -4 715 do_mem_crc 168 68 -100 716 trimslice : all -9 bss +16 rodata -29 text +4 717 u-boot: add: 1/0, grow: 1/-3 bytes: 136/-124 (12) 718 function old new delta 719 hash_command 80 160 +80 720 crc32_wd_buf - 56 +56 721 ext4fs_iterate_dir 672 668 -4 722 ext4fs_read_file 568 548 -20 723 do_mem_crc 168 68 -100 724 whistler : all -9 bss +16 rodata -29 text +4 725 u-boot: add: 1/0, grow: 1/-3 bytes: 136/-124 (12) 726 function old new delta 727 hash_command 80 160 +80 728 crc32_wd_buf - 56 +56 729 ext4fs_iterate_dir 672 668 -4 730 ext4fs_read_file 568 548 -20 731 do_mem_crc 168 68 -100 732 seaboard : all -9 bss -28 rodata -29 text +48 733 u-boot: add: 1/0, grow: 3/-2 bytes: 160/-104 (56) 734 function old new delta 735 hash_command 80 160 +80 736 crc32_wd_buf - 56 +56 737 ext4fs_read_file 548 568 +20 738 run_list_real 1996 2000 +4 739 do_nandboot 760 756 -4 740 do_mem_crc 168 68 -100 741 colibri_t20 : all -9 rodata -29 text +20 742 u-boot: add: 1/0, grow: 2/-3 bytes: 140/-112 (28) 743 function old new delta 744 hash_command 80 160 +80 745 crc32_wd_buf - 56 +56 746 read_abs_bbt 204 208 +4 747 do_nandboot 760 756 -4 748 ext4fs_read_file 576 568 -8 749 do_mem_crc 168 68 -100 750 ventana : all -37 bss -12 rodata -29 text +4 751 u-boot: add: 1/0, grow: 1/-3 bytes: 136/-124 (12) 752 function old new delta 753 hash_command 80 160 +80 754 crc32_wd_buf - 56 +56 755 ext4fs_iterate_dir 672 668 -4 756 ext4fs_read_file 568 548 -20 757 do_mem_crc 168 68 -100 758 harmony : all -37 bss -16 rodata -29 text +8 759 u-boot: add: 1/0, grow: 2/-3 bytes: 140/-124 (16) 760 function old new delta 761 hash_command 80 160 +80 762 crc32_wd_buf - 56 +56 763 nand_write_oob_syndrome 428 432 +4 764 ext4fs_iterate_dir 672 668 -4 765 ext4fs_read_file 568 548 -20 766 do_mem_crc 168 68 -100 767 medcom-wide : all -417 bss +28 data -16 rodata -93 text -336 768 u-boot: add: 1/-1, grow: 1/-2 bytes: 88/-376 (-288) 769 function old new delta 770 crc32_wd_buf - 56 +56 771 do_fat_read_at 2872 2904 +32 772 hash_algo 16 - -16 773 do_mem_crc 168 68 -100 774 hash_command 420 160 -260 775 tec : all -449 bss -4 data -16 rodata -93 text -336 776 u-boot: add: 1/-1, grow: 1/-2 bytes: 88/-376 (-288) 777 function old new delta 778 crc32_wd_buf - 56 +56 779 do_fat_read_at 2872 2904 +32 780 hash_algo 16 - -16 781 do_mem_crc 168 68 -100 782 hash_command 420 160 -260 783 plutux : all -481 bss +16 data -16 rodata -93 text -388 784 u-boot: add: 1/-1, grow: 1/-3 bytes: 68/-408 (-340) 785 function old new delta 786 crc32_wd_buf - 56 +56 787 do_load_serial_bin 1688 1700 +12 788 hash_algo 16 - -16 789 do_fat_read_at 2904 2872 -32 790 do_mem_crc 168 68 -100 791 hash_command 420 160 -260 792 powerpc: (for 5/5 boards) all +37.4 data -3.2 rodata -41.8 text +82.4 793 MPC8610HPCD : all +55 rodata -29 text +84 794 u-boot: add: 1/0, grow: 0/-1 bytes: 176/-96 (80) 795 function old new delta 796 hash_command - 176 +176 797 do_mem_crc 184 88 -96 798 MPC8641HPCN : all +55 rodata -29 text +84 799 u-boot: add: 1/0, grow: 0/-1 bytes: 176/-96 (80) 800 function old new delta 801 hash_command - 176 +176 802 do_mem_crc 184 88 -96 803 MPC8641HPCN_36BIT: all +55 rodata -29 text +84 804 u-boot: add: 1/0, grow: 0/-1 bytes: 176/-96 (80) 805 function old new delta 806 hash_command - 176 +176 807 do_mem_crc 184 88 -96 808 sbc8641d : all +55 rodata -29 text +84 809 u-boot: add: 1/0, grow: 0/-1 bytes: 176/-96 (80) 810 function old new delta 811 hash_command - 176 +176 812 do_mem_crc 184 88 -96 813 xpedite517x : all -33 data -16 rodata -93 text +76 814 u-boot: add: 1/-1, grow: 0/-1 bytes: 176/-112 (64) 815 function old new delta 816 hash_command - 176 +176 817 hash_algo 16 - -16 818 do_mem_crc 184 88 -96 819... 820 821 822This shows that commit 19 has reduced codesize for arm slightly and increased 823it for powerpc. This increase was offset in by reductions in rodata and 824data/bss. 825 826Shown below the summary lines are the sizes for each board. Below each board 827are the sizes for each function. This information starts with: 828 829 add - number of functions added / removed 830 grow - number of functions which grew / shrunk 831 bytes - number of bytes of code added to / removed from all functions, 832 plus the total byte change in brackets 833 834The change seems to be that hash_command() has increased by more than the 835do_mem_crc() function has decreased. The function sizes typically add up to 836roughly the text area size, but note that every read-only section except 837rodata is included in 'text', so the function total does not exactly 838correspond. 839 840It is common when refactoring code for the rodata to decrease as the text size 841increases, and vice versa. 842 843 844The .buildman file 845================== 846 847The .buildman file provides information about the available toolchains and 848also allows build flags to be passed to 'make'. It consists of several 849sections, with the section name in square brackets. Within each section are 850a set of (tag, value) pairs. 851 852'[toolchain]' section 853 854 This lists the available toolchains. The tag here doesn't matter, but 855 make sure it is unique. The value is the path to the toolchain. Buildman 856 will look in that path for a file ending in 'gcc'. It will then execute 857 it to check that it is a C compiler, passing only the --version flag to 858 it. If the return code is 0, buildman assumes that it is a valid C 859 compiler. It uses the first part of the name as the architecture and 860 strips off the last part when setting the CROSS_COMPILE environment 861 variable (parts are delimited with a hyphen). 862 863 For example powerpc-linux-gcc will be noted as a toolchain for 'powerpc' 864 and CROSS_COMPILE will be set to powerpc-linux- when using it. 865 866'[toolchain-alias]' section 867 868 This converts toolchain architecture names to U-Boot names. For example, 869 if an x86 toolchains is called i386-linux-gcc it will not normally be 870 used for architecture 'x86'. Adding 'x86: i386 x86_64' to this section 871 will tell buildman that the i386 and x86_64 toolchains can be used for 872 the x86 architecture. 873 874'[make-flags]' section 875 876 U-Boot's build system supports a few flags (such as BUILD_TAG) which 877 affect the build product. These flags can be specified in the buildman 878 settings file. They can also be useful when building U-Boot against other 879 open source software. 880 881 [make-flags] 882 at91-boards=ENABLE_AT91_TEST=1 883 snapper9260=${at91-boards} BUILD_TAG=442 884 snapper9g45=${at91-boards} BUILD_TAG=443 885 886 This will use 'make ENABLE_AT91_TEST=1 BUILD_TAG=442' for snapper9260 887 and 'make ENABLE_AT91_TEST=1 BUILD_TAG=443' for snapper9g45. A special 888 variable ${target} is available to access the target name (snapper9260 889 and snapper9g20 in this case). Variables are resolved recursively. Note 890 that variables can only contain the characters A-Z, a-z, 0-9, hyphen (-) 891 and underscore (_). 892 893 It is expected that any variables added are dealt with in U-Boot's 894 config.mk file and documented in the README. 895 896 Note that you can pass ad-hoc options to the build using environment 897 variables, for example: 898 899 SOME_OPTION=1234 ./tools/buildman/buildman my_board 900 901 902Quick Sanity Check 903================== 904 905If you have made changes and want to do a quick sanity check of the 906currently checked-out source, run buildman without the -b flag. This will 907build the selected boards and display build status as it runs (i.e. -v is 908enabled automatically). Use -e to see errors/warnings as well. 909 910 911Building Ranges 912=============== 913 914You can build a range of commits by specifying a range instead of a branch 915when using the -b flag. For example: 916 917 upstream/master..us-buildman 918 919will build commits in us-buildman that are not in upstream/master. 920 921 922Building Faster 923=============== 924 925By default, buildman executes 'make mrproper' prior to building the first 926commit for each board. This causes everything to be built from scratch. If you 927trust the build system's incremental build capabilities, you can pass the -I 928flag to skip the 'make mproper' invocation, which will reduce the amount of 929work 'make' does, and hence speed up the build. This flag will speed up any 930buildman invocation, since it reduces the amount of work done on any build. 931 932One possible application of buildman is as part of a continual edit, build, 933edit, build, ... cycle; repeatedly applying buildman to the same change or 934series of changes while making small incremental modifications to the source 935each time. This provides quick feedback regarding the correctness of recent 936modifications. In this scenario, buildman's default choice of build directory 937causes more build work to be performed than strictly necessary. 938 939By default, each buildman thread uses a single directory for all builds. When a 940thread builds multiple boards, the configuration built in this directory will 941cycle through various different configurations, one per board built by the 942thread. Variations in the configuration will force a rebuild of affected source 943files when a thread switches between boards. Ideally, such buildman-induced 944rebuilds would not happen, thus allowing the build to operate as efficiently as 945the build system and source changes allow. buildman's -P flag may be used to 946enable this; -P causes each board to be built in a separate (board-specific) 947directory, thus avoiding any buildman-induced configuration changes in any 948build directory. 949 950U-Boot's build system embeds information such as a build timestamp into the 951final binary. This information varies each time U-Boot is built. This causes 952various files to be rebuilt even if no source changes are made, which in turn 953requires that the final U-Boot binary be re-linked. This unnecessary work can 954be avoided by turning off the timestamp feature. This can be achieved by 955setting the SOURCE_DATE_EPOCH environment variable to 0. 956 957Combining all of these options together yields the command-line shown below. 958This will provide the quickest possible feedback regarding the current content 959of the source tree, thus allowing rapid tested evolution of the code. 960 961 SOURCE_DATE_EPOCH=0 ./tools/buildman/buildman -I -P tegra 962 963 964Checking configuration 965====================== 966 967A common requirement when converting CONFIG options to Kconfig is to check 968that the effective configuration has not changed due to the conversion. 969Buildman supports this with the -K option, used after a build. This shows 970differences in effective configuration between one commit and the next. 971 972For example: 973 974 $ buildman -b kc4 -sK 975 ... 976 43: Convert CONFIG_SPL_USBETH_SUPPORT to Kconfig 977 arm: 978 + u-boot.cfg: CONFIG_SPL_ENV_SUPPORT=1 CONFIG_SPL_NET_SUPPORT=1 979 + u-boot-spl.cfg: CONFIG_SPL_MMC_SUPPORT=1 CONFIG_SPL_NAND_SUPPORT=1 980 + all: CONFIG_SPL_ENV_SUPPORT=1 CONFIG_SPL_MMC_SUPPORT=1 CONFIG_SPL_NAND_SUPPORT=1 CONFIG_SPL_NET_SUPPORT=1 981 am335x_evm_usbspl : 982 + u-boot.cfg: CONFIG_SPL_ENV_SUPPORT=1 CONFIG_SPL_NET_SUPPORT=1 983 + u-boot-spl.cfg: CONFIG_SPL_MMC_SUPPORT=1 CONFIG_SPL_NAND_SUPPORT=1 984 + all: CONFIG_SPL_ENV_SUPPORT=1 CONFIG_SPL_MMC_SUPPORT=1 CONFIG_SPL_NAND_SUPPORT=1 CONFIG_SPL_NET_SUPPORT=1 985 44: Convert CONFIG_SPL_USB_HOST_SUPPORT to Kconfig 986 ... 987 988This shows that commit 44 enabled three new options for the board 989am335x_evm_usbspl which were not enabled in commit 43. There is also a 990summary for 'arm' showing all the changes detected for that architecture. 991In this case there is only one board with changes, so 'arm' output is the 992same as 'am335x_evm_usbspl'/ 993 994The -K option uses the u-boot.cfg, spl/u-boot-spl.cfg and tpl/u-boot-tpl.cfg 995files which are produced by a build. If all you want is to check the 996configuration you can in fact avoid doing a full build, using -D. This tells 997buildman to configuration U-Boot and create the .cfg files, but not actually 998build the source. This is 5-10 times faster than doing a full build. 999 1000By default buildman considers the follow two configuration methods 1001equivalent: 1002 1003 #define CONFIG_SOME_OPTION 1004 1005 CONFIG_SOME_OPTION=y 1006 1007The former would appear in a header filer and the latter in a defconfig 1008file. The achieve this, buildman considers 'y' to be '1' in configuration 1009variables. This avoids lots of useless output when converting a CONFIG 1010option to Kconfig. To disable this behaviour, use --squash-config-y. 1011 1012 1013Other options 1014============= 1015 1016Buildman has various other command line options. Try --help to see them. 1017 1018When doing builds, Buildman's return code will reflect the overall result: 1019 1020 0 (success) No errors or warnings found 1021 128 Errors found 1022 129 Warnings found 1023 1024 1025How to change from MAKEALL 1026========================== 1027 1028Buildman includes most of the features of MAKEALL and is generally faster 1029and easier to use. In particular it builds entire branches: if a particular 1030commit introduces an error in a particular board, buildman can easily show 1031you this, even if a later commit fixes that error. 1032 1033The reasons to deprecate MAKEALL are: 1034- We don't want to maintain two build systems 1035- Buildman is typically faster 1036- Buildman has a lot more features 1037 1038But still, many people will be sad to lose MAKEALL. If you are used to 1039MAKEALL, here are a few pointers. 1040 1041First you need to set up your tool chains - see the 'Setting up' section 1042for details. Once you have your required toolchain(s) detected then you are 1043ready to go. 1044 1045To build the current source tree, run buildman without a -b flag: 1046 1047 ./tools/buildman/buildman <list of things to build> 1048 1049This will build the current source tree for the given boards and display 1050the results and errors. 1051 1052However buildman usually works on entire branches, and for that you must 1053specify a board flag: 1054 1055 ./tools/buildman/buildman -b <branch_name> <list of things to build> 1056 1057followed by (afterwards, or perhaps concurrently in another terminal): 1058 1059 ./tools/buildman/buildman -b <branch_name> -s <list of things to build> 1060 1061to see the results of the build. Rather than showing you all the output, 1062buildman just shows a summary, with red indicating that a commit introduced 1063an error and green indicating that a commit fixed an error. Use the -e 1064flag to see the full errors and -l to see which boards caused which errors. 1065 1066If you really want to see build results as they happen, use -v when doing a 1067build (and -e to see the errors/warnings too). 1068 1069You don't need to stick around on that branch while buildman is running. It 1070checks out its own copy of the source code, so you can change branches, 1071add commits, etc. without affecting the build in progress. 1072 1073The <list of things to build> can include board names, architectures or the 1074like. There are no flags to disambiguate since ambiguities are rare. Using 1075the examples from MAKEALL: 1076 1077Examples: 1078 - build all Power Architecture boards: 1079 MAKEALL -a powerpc 1080 MAKEALL --arch powerpc 1081 MAKEALL powerpc 1082 ** buildman -b <branch> powerpc 1083 - build all PowerPC boards manufactured by vendor "esd": 1084 MAKEALL -a powerpc -v esd 1085 ** buildman -b <branch> esd 1086 - build all PowerPC boards manufactured either by "keymile" or "siemens": 1087 MAKEALL -a powerpc -v keymile -v siemens 1088 ** buildman -b <branch> keymile siemens 1089 - build all Freescale boards with MPC83xx CPUs, plus all 4xx boards: 1090 MAKEALL -c mpc83xx -v freescale 4xx 1091 ** buildman -b <branch> mpc83xx freescale 4xx 1092 1093Buildman automatically tries to use all the CPUs in your machine. If you 1094are building a lot of boards it will use one thread for every CPU core 1095it detects in your machine. This is like MAKEALL's BUILD_NBUILDS option. 1096You can use the -T flag to change the number of threads. If you are only 1097building a few boards, buildman will automatically run make with the -j 1098flag to increase the number of concurrent make tasks. It isn't normally 1099that helpful to fiddle with this option, but if you use the BUILD_NCPUS 1100option in MAKEALL then -j is the equivalent in buildman. 1101 1102Buildman puts its output in ../<branch_name> by default but you can change 1103this with the -o option. Buildman normally does out-of-tree builds: use -i 1104to disable that if you really want to. But be careful that once you have 1105used -i you pollute buildman's copies of the source tree, and you will need 1106to remove the build directory (normally ../<branch_name>) to run buildman 1107in normal mode (without -i). 1108 1109Buildman doesn't keep the output result normally, but use the -k option to 1110do this. 1111 1112Please read 'Theory of Operation' a few times as it will make a lot of 1113things clearer. 1114 1115Some options you might like are: 1116 1117 -B shows which functions are growing/shrinking in which commit - great 1118 for finding code bloat. 1119 -S shows image sizes for each commit (just an overall summary) 1120 -u shows boards that you haven't built yet 1121 --step 0 will build just the upstream commit and the last commit of your 1122 branch. This is often a quick sanity check that your branch doesn't 1123 break anything. But note this does not check bisectability! 1124 1125 1126TODO 1127==== 1128 1129This has mostly be written in my spare time as a response to my difficulties 1130in testing large series of patches. Apart from tidying up there is quite a 1131bit of scope for improvement. Things like better error diffs and easier 1132access to log files. Also it would be nice if buildman could 'hunt' for 1133problems, perhaps by building a few boards for each arch, or checking 1134commits for changed files and building only boards which use those files. 1135 1136A specific problem to fix is that Ctrl-C does not exit buildman cleanly when 1137multiple builder threads are active. 1138 1139Credits 1140======= 1141 1142Thanks to Grant Grundler <grundler@chromium.org> for his ideas for improving 1143the build speed by building all commits for a board instead of the other 1144way around. 1145 1146 1147Simon Glass 1148sjg@chromium.org 1149Halloween 2012 1150Updated 12-12-12 1151Updated 23-02-13 1152