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.3 Build an external toolchain with Buildroot.................................. 12 6.1.3.1 External toolchain wrapper.................................... 13 6.2 /dev management................................................... 13 6.3 init system....................................................... 14 7 Configuration of other components 16 8 General Buildroot usage 17 8.1 make tips....................................................... 17 8.2 Understanding when a full rebuild is necessary................................... 19 8.3 Understanding how to rebuild packages....................................... 20 8.4 Offline builds..................................................... 20 The Buildroot user manual iii 8.5 Building out-of-tree.................................................. 20 8.6 Environment variables................................................ 21 8.7 Dealing efficiently with filesystem images...................................... 22 8.8 Details about packages................................................ 22 8.9 Graphing the dependencies between packages.................................... 23 8.10 Graphing the build duration.............................................. 24 8.11 Graphing the filesystem size contribution of packages................................ 24 8.12 Top-level parallel build................................................ 25 8.13 Integration with Eclipse................................................ 26 8.14 Advanced usage.................................................... 26 8.14.1 Using the generated toolchain outside Buildroot............................... 26 8.14.2 Using gdb in Buildroot........................................... 26 8.14.3 Using ccache in Buildroot......................................... 27 8.14.4 Location of downloaded packages...................................... 28 8.14.5 Package-specific make targets........................................ 28 8.14.6 Using Buildroot during development..................................... 29 9 Project-specific customization 31 9.1 Recommended directory structure.......................................... 31 9.1.1 Implementing layered customizations.................................... 32 9.2 Keeping customizations outside of Buildroot..................................... 33 9.2.1 Layout of a br2-external tree......................................... 34 9.2.1.1 The external.desc file.................................... 34 9.2.1.2 The Config.in and external.mk files........................... 35 9.2.1.3 The configs/ directory..................................... 35 9.2.1.4 The provides/ directory.................................... 35 9.2.1.5 Free-form content......................................... 36 9.2.1.6 Additional Linux kernel extensions................................ 36 9.2.1.7 Example layout.......................................... 36 9.3 Storing the Buildroot configuration.......................................... 39 9.4 Storing the configuration of other components.................................... 40 9.5 Customizing the generated target filesystem..................................... 40 9.5.1 Setting file permissions and ownership and adding custom devices nodes................. 42 9.6 Adding custom user accounts............................................. 42 9.7 Customization after the images have been created.................................. 42 9.8 Adding project-specific patches............................................ 43 9.9 Adding project-specific packages........................................... 43 9.10 Quick guide to storing your project-specific customizations............................. 44 The Buildroot user manual iv 10 Using SELinux in Buildroot 46 10.1 Enabling SELinux support.............................................. 46 10.2 SELinux policy tweaking............................................... 46 11 Frequently Asked Questions & Troubleshooting 48 11.1 The boot hangs after Starting network. ....................................... 48 11.2 Why is there no compiler on the target?....................................... 48 11.3 Why are there no development files on the target?.................................. 49 11.4 Why is there no documentation on the target?.................................... 49 11.5 Why are some packages not visible in the Buildroot config menu?......................... 49 11.6 Why not use the target directory as a chroot directory?............................... 49 11.7 Why doesn’t Buildroot generate binary packages (.deb, .ipkg. )?......................... 49 11.8 How to speed-up the build process?......................................... 50 12 Known issues 52 13 Legal notice and licensing 53 13.1 Complying with open source licenses........................................ 53 13.2 Complying with the Buildroot license........................................ 54 13.2.1 Patches to packages.............................................. 54 14 Beyond Buildroot 55 14.1 Boot the generated images.............................................. 55 14.1.1 NFS boot................................................... 55 14.1.2 Live CD.................................................... 55 14.2 Chroot......................................................... 56 III Developer guide 57 15 How Buildroot works 58 16 Coding style 59 16.1 Config.in file................................................... 59 16.2 The .mk file...................................................... 59 16.3 The documentation.................................................. 61 16.4 Support scripts.................................................... 61 17 Adding support for a particular board 62 The Buildroot user manual v 18 Adding new packages to Buildroot 63 18.1 Package directory................................................... 63 18.2 Config files...................................................... 63 18.2.1 Config.in file............................................... 63 18.2.2 Config.in.host file........................................... 64 18.2.3 Choosing depends on or select .................................... 65 18.2.4 Dependencies on target and toolchain options................................ 66 18.2.5 Dependencies on a Linux kernel built by buildroot............................. 68 18.2.6 Dependencies on udev /dev management.................................. 68 18.2.7 Dependencies on features provided by virtual packages........................... 69 18.3 The .mk file...................................................... 69 18.4 The .hash file.................................................... 69 18.5 Infrastructure for packages with specific build systems............................... 71 18.5.1 generic-package tutorial........................................ 71 18.5.2 generic-package reference....................................... 73 18.6 Infrastructure for autotools-based packages..................................... 78 18.6.1 autotools-package tutorial...................................... 78 18.6.2 autotools-package reference..................................... 79 18.7 Infrastructure for CMake-based packages...................................... 80 18.7.1 cmake-package tutorial.......................................... 80 18.7.2 cmake-package reference........................................ 81 18.8 Infrastructure for Python packages.......................................... 82 18.8.1 python-package tutorial......................................... 82 18.8.2 python-package reference........................................ 83 18.8.3 Generating a python-package from a PyPI repository......................... 84 18.8.4 python-package CFFI backend..................................... 84 18.9 Infrastructure for LuaRocks-based packages..................................... 85 18.9.1 luarocks-package tutorial....................................... 85 18.9.2 luarocks-package reference...................................... 86 18.10Infrastructure for Perl/CPAN packages........................................ 86 18.10.1 perl-package tutorial.......................................... 86 18.10.2 perl-package reference......................................... 87 18.11Infrastructure for virtual packages.......................................... 88 18.11.1 virtual-package tutorial........................................ 88 18.11.2 Virtual package’s Config.in file..................................... 88 18.11.3 Virtual package’s .mk file.......................................... 89 18.11.4 Provider’s Config.in file......................................... 89 18.11.5 Provider’s .mk file.............................................. 89 18.11.6 Notes on depending on a virtual package.................................. 89 The Buildroot user manual vi 18.11.7 Notes on depending on a specific provider.................................. 90 18.12Infrastructure for packages using kconfig for configuration