The Buildroot user manual i The Buildroot user manual The Buildroot user manual ii Contents I Getting started 1 1 About Buildroot 2 2 System requirements 3 2.1 Mandatory packages.................................................3 2.2 Optional packages...................................................4 3 Getting Buildroot 5 4 Buildroot quick start 6 5 Community resources 8 II User guide 9 6 Buildroot configuration 10 6.1 Cross-compilation toolchain............................................. 10 6.1.1 Internal toolchain backend.......................................... 11 6.1.2 External toolchain backend.......................................... 11 6.1.2.1 External toolchain wrapper.................................... 12 6.2 /dev management................................................... 13 6.3 init system....................................................... 13 7 Configuration of other components 15 8 General Buildroot usage 16 8.1 make tips....................................................... 16 8.2 Understanding when a full rebuild is necessary................................... 17 8.3 Understanding how to rebuild packages....................................... 18 8.4 Offline builds..................................................... 18 8.5 Building out-of-tree.................................................. 18 The Buildroot user manual iii 8.6 Environment variables................................................ 19 8.7 Dealing efficiently with filesystem images...................................... 19 8.8 Graphing the dependencies between packages.................................... 20 8.9 Graphing the build duration.............................................. 21 8.10 Graphing the filesystem size contribution of packages................................ 21 8.11 Integration with Eclipse................................................ 22 8.12 Advanced usage.................................................... 22 8.12.1 Using the generated toolchain outside Buildroot............................... 22 8.12.2 Using gdb in Buildroot........................................... 22 8.12.3 Using ccache in Buildroot......................................... 23 8.12.4 Location of downloaded packages...................................... 23 8.12.5 Package-specific make targets........................................ 24 8.12.6 Using Buildroot during development..................................... 24 9 Project-specific customization 26 9.1 Recommended directory structure.......................................... 26 9.1.1 Implementing layered customizations.................................... 27 9.2 Keeping customizations outside of Buildroot..................................... 28 9.3 Storing the Buildroot configuration.......................................... 29 9.4 Storing the configuration of other components.................................... 29 9.5 Customizing the generated target filesystem..................................... 30 9.5.1 Setting file permissions and ownership and adding custom devices nodes................. 31 9.6 Adding custom user accounts............................................. 32 9.7 Customization after the images have been created.................................. 32 9.8 Adding project-specific patches............................................ 32 9.9 Adding project-specific packages........................................... 33 9.10 Quick guide to storing your project-specific customizations............................. 34 10 Frequently Asked Questions & Troubleshooting 36 10.1 The boot hangs after Starting network. ....................................... 36 10.2 Why is there no compiler on the target?....................................... 36 10.3 Why are there no development files on the target?.................................. 37 10.4 Why is there no documentation on the target?.................................... 37 10.5 Why are some packages not visible in the Buildroot config menu?......................... 37 10.6 Why not use the target directory as a chroot directory?............................... 37 10.7 Why doesn’t Buildroot generate binary packages (.deb, .ipkg. )?......................... 37 10.8 How to speed-up the build process?......................................... 38 11 Known issues 40 The Buildroot user manual iv 12 Legal notice and licensing 41 12.1 Complying with open source licenses........................................ 41 12.2 License abbreviations................................................. 42 12.3 Complying with the Buildroot license........................................ 42 12.3.1 Patches to packages.............................................. 43 13 Beyond Buildroot 44 13.1 Boot the generated images.............................................. 44 13.1.1 NFS boot................................................... 44 13.1.2 Live CD.................................................... 44 13.2 Chroot......................................................... 44 III Developer guide 45 14 How Buildroot works 46 15 Coding style 47 15.1 Config.in file................................................... 47 15.2 The .mk file...................................................... 47 15.3 The documentation.................................................. 49 16 Adding support for a particular board 50 17 Adding new packages to Buildroot 51 17.1 Package directory................................................... 51 17.2 Config files...................................................... 51 17.2.1 Config.in file............................................... 51 17.2.2 Config.in.host file........................................... 52 17.2.3 Choosing depends on or select .................................... 52 17.2.4 Dependencies on target and toolchain options................................ 54 17.2.5 Dependencies on a Linux kernel built by buildroot............................. 56 17.2.6 Dependencies on udev /dev management.................................. 56 17.2.7 Dependencies on features provided by virtual packages........................... 56 17.3 The .mk file...................................................... 56 17.4 The .hash file.................................................... 57 17.5 Infrastructure for packages with specific build systems............................... 58 17.5.1 generic-package tutorial........................................ 58 17.5.2 generic-package reference....................................... 60 17.6 Infrastructure for autotools-based packages..................................... 64 17.6.1 autotools-package tutorial...................................... 64 17.6.2 autotools-package reference..................................... 65 The Buildroot user manual v 17.7 Infrastructure for CMake-based packages...................................... 66 17.7.1 cmake-package tutorial.......................................... 66 17.7.2 cmake-package reference........................................ 67 17.8 Infrastructure for Python packages.......................................... 68 17.8.1 python-package tutorial......................................... 68 17.8.2 python-package reference........................................ 69 17.8.3 Generating a python-package from a PyPI repository......................... 70 17.8.4 python-package CFFI backend..................................... 70 17.9 Infrastructure for LuaRocks-based packages..................................... 71 17.9.1 luarocks-package tutorial....................................... 71 17.9.2 luarocks-package reference...................................... 71 17.10Infrastructure for Perl/CPAN packages........................................ 72 17.10.1 perl-package tutorial.......................................... 72 17.10.2 perl-package reference......................................... 73 17.11Infrastructure for virtual packages.......................................... 73 17.11.1 virtual-package tutorial........................................ 73 17.11.2 Virtual package’s Config.in file..................................... 74 17.11.3 Virtual package’s .mk file.......................................... 74 17.11.4 Provider’s Config.in file......................................... 74 17.11.5 Provider’s .mk file.............................................. 74 17.11.6 Notes on depending on a virtual package.................................. 75 17.11.7 Notes on depending on a specific provider.................................. 75 17.12Infrastructure for packages using kconfig for configuration files........................... 75 17.13Infrastructure for rebar-based packages........................................ 76 17.13.1 rebar-package tutorial.......................................... 76 17.13.2 rebar-package reference........................................ 77 17.14Infrastructure for packages building kernel modules................................. 77 17.14.1 kernel-module tutorial.......................................... 77 17.14.2 kernel-module reference........................................ 78 17.15Infrastructure for asciidoc documents........................................ 79 17.15.1 asciidoc-document tutorial...................................... 80 17.15.2 asciidoc-document reference..................................... 80 17.16Infrastructure specific to the Linux kernel package.................................. 81 17.16.1 linux-kernel-tools............................................... 81 17.16.2 linux-kernel-extensions............................................ 82 17.17Hooks available in the various