The Buildroot User Manual
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 122
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
6
User guide
9
Buildroot configuration
6.1
10
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.5
Building out-of-tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
The Buildroot user manual
iii
8.6
Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.7
Dealing efficiently with filesystem images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.8
Graphing the dependencies between packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8.9
Graphing the build duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
8.10 Graphing the filesystem size contribution of packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8.11 Integration with Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.12 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.12.1 Using the generated toolchain outside Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.12.2 Using gdb in Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
8.12.3 Using ccache in Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8.12.4 Location of downloaded packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.12.5 Package-specific make targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.12.6 Using Buildroot during development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9
Project-specific customization
9.1
Recommended directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9.1.1
9.2
27
Implementing layered customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Keeping customizations outside of Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.2.1
Layout of a br2-external tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.2.1.1
The external.desc file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.2.1.2
The Config.in and external.mk files . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.2.1.3
The configs/ directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.2.1.4
Free-form content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.2.1.5
Example layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.3
Storing the Buildroot configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.4
Storing the configuration of other components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
9.5
Customizing the generated target filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.5.1
Setting file permissions and ownership and adding custom devices nodes . . . . . . . . . . . . . . . . . 35
9.6
Adding custom user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
9.7
Customization after the images have been created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
9.8
Adding project-specific patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
9.9
Adding project-specific packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
9.10 Quick guide to storing your project-specific customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
10 Frequently Asked Questions & Troubleshooting
39
10.1 The boot hangs after Starting network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
10.2 Why is there no compiler on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
10.3 Why are there no development files on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
10.4 Why is there no documentation on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
10.5 Why are some packages not visible in the Buildroot config menu? . . . . . . . . . . . . . . . . . . . . . . . . . 40
10.6 Why not use the target directory as a chroot directory? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
10.7 Why doesn’t Buildroot generate binary packages (.deb, .ipkg. . . )? . . . . . . . . . . . . . . . . . . . . . . . . . 40
10.8 How to speed-up the build process? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
The Buildroot user manual
iv
11 Known issues
43
12 Legal notice and licensing
44
12.1 Complying with open source licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
12.2 Complying with the Buildroot license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
12.2.1 Patches to packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
13 Beyond Buildroot
46
13.1 Boot the generated images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
13.1.1 NFS boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
13.1.2 Live CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
13.2 Chroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
III
Developer guide
47
14 How Buildroot works
48
15 Coding style
49
15.1 Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
15.2 The .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
15.3 The documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
15.4 Support scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
16 Adding support for a particular board
52
17 Adding new packages to Buildroot
53
17.1 Package directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
17.2 Config files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
17.2.1 Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
17.2.2 Config.in.host file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
17.2.3 Choosing depends on or select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
17.2.4 Dependencies on target and toolchain options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
17.2.5 Dependencies on a Linux kernel built by buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
17.2.6 Dependencies on udev /dev management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
17.2.7 Dependencies on features provided by virtual packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
17.3 The .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
17.4 The .hash file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
17.5 Infrastructure for packages with specific build systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
17.5.1 generic-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
17.5.2 generic-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
17.6 Infrastructure for autotools-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
The Buildroot user manual
v
17.6.1 autotools-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
17.6.2 autotools-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
17.7 Infrastructure for CMake-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
17.7.1 cmake-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
17.7.2 cmake-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
17.8 Infrastructure for Python packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
17.8.1 python-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
17.8.2 python-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
17.8.3 Generating a python-package from a PyPI repository . . . . . . . . . . . . . . . . . . . . . . . . . 72
17.8.4 python-package CFFI backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
17.9 Infrastructure for LuaRocks-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
17.9.1 luarocks-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
17.9.2 luarocks-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
17.10Infrastructure for Perl/CPAN packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
17.10.1 perl-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
17.10.2 perl-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
17.11Infrastructure for virtual packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
17.11.1 virtual-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
17.11.2 Virtual package’s Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.11.3 Virtual package’s .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.11.4 Provider’s Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.11.5 Provider’s .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.11.6 Notes on depending on a virtual package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
17.11.7 Notes on depending on a specific provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
17.12Infrastructure for packages using kconfig for configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
17.13Infrastructure for rebar-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
17.13.1 rebar-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
17.13.2 rebar-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
17.14Infrastructure for Waf-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
17.14.1 waf-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
17.14.2 waf-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
17.15Integration of Meson-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
17.15.1 meson-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
17.16Integration of Cargo-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
17.16.1 Cargo-based package’s Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
17.16.2 Cargo-based package’s .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
17.16.3 About Dependencies Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
17.17Infrastructure for Go packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
17.17.1 golang-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
The Buildroot user manual
vi
17.17.2 golang-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
17.18Infrastructure for packages building kernel modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
17.18.1 kernel-module tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
17.18.2 kernel-module reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
17.19Infrastructure for asciidoc documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
17.19.1 asciidoc-document tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
17.19.2 asciidoc-document reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
17.20Infrastructure specific to the Linux kernel package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
17.20.1 linux-kernel-tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
17.20.2 linux-kernel-extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
17.21Hooks available in the various build steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
17.21.1 Using the POST_RSYNC hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
17.21.2 Target-finalize hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
17.22Gettext integration and interaction with packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
17.23Tips and tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
17.23.1 Package name, config entry name and makefile variable relationship . . . . . . . . . . . . . . . . . . . . 93
17.23.2 How to check the coding style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
17.23.3 How to test your package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
17.23.4 How to add a package from GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
17.24Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
18 Patching a package
97
18.1 Providing patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.1.1 Downloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.1.2 Within Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18.1.3 Global patch directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.2 How patches are applied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.3 Format and licensing of the package patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
18.4 Integrating patches found on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
19 Download infrastructure
100
20 Debugging Buildroot
101
21 Contributing to Buildroot
102
21.1 Reproducing, analyzing and fixing bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
21.2 Analyzing and fixing autobuild failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
21.3 Reviewing and testing patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
21.3.1 Applying Patches from Patchwork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
21.4 Work on items from the TODO list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
The Buildroot user manual
vii
21.5 Submitting patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
21.5.1 The formatting of a patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
21.5.2 Preparing a patch series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
21.5.3 Cover letter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
21.5.4 Patch revision changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
21.6 Reporting issues/bugs or getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
22 DEVELOPERS file and get-developers
108
IV
109
Appendix
23 Makedev syntax documentation
110
24 Makeusers syntax documentation
112
25 Migrating from older Buildroot versions
114
25.1 Migrating to 2016.11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
25.2 Migrating to 2017.08 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
The Buildroot user manual
viii
Buildroot 2018.05-rc1 manual generated on 2018-05-09 21:01:35 UTC from git revision b19e24b9f7
The Buildroot manual is written by the Buildroot developers. It is licensed under the GNU General Public License, version 2.
Refer to the COPYING file in the Buildroot sources for the full text of this license.
Copyright © 2004-2018 The Buildroot developers
logo.png
The Buildroot user manual
1 / 114
Part I
Getting started
The Buildroot user manual
2 / 114
Chapter 1
About Buildroot
Buildroot is a tool that simplifies and automates the process of building a complete Linux system for an embedded system, using
cross-compilation.
In order to achieve this, Buildroot is able to generate a cross-compilation toolchain, a root filesystem, a Linux kernel image and a
bootloader for your target. Buildroot can be used for any combination of these options, independently (you can for example use
an existing cross-compilation toolchain, and build only your root filesystem with Buildroot).
Buildroot is useful mainly for people working with embedded systems. Embedded systems often use processors that are not
the regular x86 processors everyone is used to having in his PC. They can be PowerPC processors, MIPS processors, ARM
processors, etc.
Buildroot supports numerous processors and their variants; it also comes with default configurations for several boards available
off-the-shelf. Besides this, a number of third-party projects are based on, or develop their BSP 1 or SDK 2 on top of Buildroot.
1
2
BSP: Board Support Package
SDK: Software Development Kit
The Buildroot user manual
3 / 114
Chapter 2
System requirements
Buildroot is designed to run on Linux systems.
While Buildroot itself will build most host packages it needs for the compilation, certain standard Linux utilities are expected
to be already installed on the host system. Below you will find an overview of the mandatory and optional packages (note that
package names may vary between distributions).
2.1
Mandatory packages
• Build tools:
– which
– sed
– make (version 3.81 or any later)
– binutils
– build-essential (only for Debian based systems)
– gcc (version 2.95 or any later)
– g++ (version 2.95 or any later)
– bash
– patch
– gzip
– bzip2
– perl (version 5.8.7 or any later)
– tar
– cpio
– python (version 2.6 or any later)
– unzip
– rsync
– file (must be in /usr/bin/file)
– bc
• Source fetching tools:
– wget
The Buildroot user manual
2.2
4 / 114
Optional packages
• Configuration interface dependencies:
For these libraries, you need to install both runtime and development data, which in many distributions are packaged separately.
The development packages typically have a -dev or -devel suffix.
– ncurses5 to use the menuconfig interface
– qt4 to use the xconfig interface
– glib2, gtk2 and glade2 to use the gconfig interface
• Source fetching tools:
In the official tree, most of the package sources are retrieved using wget from ftp, http or https locations. A few packages are
only available through a version control system. Moreover, Buildroot is capable of downloading sources via other tools, like
rsync or scp (refer to Chapter 19 for more details). If you enable packages using any of these methods, you will need to
install the corresponding tool on the host system:
– bazaar
– cvs
– git
– mercurial
– rsync
– scp
– subversion
• Java-related packages, if the Java Classpath needs to be built for the target system:
– The javac compiler
– The jar tool
• Documentation generation tools:
– asciidoc, version 8.6.3 or higher
– w3m
– python with the argparse module (automatically present in 2.7+ and 3.2+)
– dblatex (required for the pdf manual only)
• Graph generation tools:
– graphviz to use graph-depends and -graph-depends
– python-matplotlib to use graph-build
The Buildroot user manual
5 / 114
Chapter 3
Getting Buildroot
Buildroot releases are made every 3 months, in February, May, August and November. Release numbers are in the format
YYYY.MM, so for example 2013.02, 2014.08.
Release tarballs are available at http://buildroot.org/downloads/.
For your convenience, a Vagrantfile is available in support/misc/Vagrantfile in the Buildroot source tree to quickly set
up a virtual machine with the needed dependencies to get started.
If you want to setup an isolated buildroot environment on Linux or Mac Os X, paste this line onto your terminal:
curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up
If you are on Windows, paste this into your powershell:
(new-object System.Net.WebClient).DownloadFile(
"https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
vagrant up
If you want to follow development, you can use the daily snapshots or make a clone of the Git repository. Refer to the Download
page of the Buildroot website for more details.
The Buildroot user manual
6 / 114
Chapter 4
Buildroot quick start
Important: you can and should build everything as a normal user. There is no need to be root to configure and use Buildroot.
By running all commands as a regular user, you protect your system against packages behaving badly during compilation and
installation.
The first step when using Buildroot is to create a configuration. Buildroot has a nice configuration tool similar to the one you can
find in the Linux kernel or in BusyBox.
From the buildroot directory, run
$ make menuconfig
for the original curses-based configurator, or
$ make nconfig
for the new curses-based configurator, or
$ make xconfig
for the Qt-based configurator, or
$ make gconfig
for the GTK-based configurator.
All of these "make" commands will need to build a configuration utility (including the interface), so you may need to install
"development" packages for relevant libraries used by the configuration utilities. Refer to Chapter 2 for more details, specifically
the optional requirements Section 2.2 to get the dependencies of your favorite interface.
For each menu entry in the configuration tool, you can find associated help that describes the purpose of the entry. Refer to
Chapter 6 for details on some specific configuration aspects.
Once everything is configured, the configuration tool generates a .config file that contains the entire configuration. This file
will be read by the top-level Makefile.
To start the build process, simply run:
$ make
You should never use make -jN with Buildroot: top-level parallel make is currently not supported. Instead, use the BR2_JL
EVEL option to tell Buildroot to run the compilation of each individual package with make -jN.
The make command will generally perform the following steps:
• download source files (as required);
The Buildroot user manual
7 / 114
• configure, build and install the cross-compilation toolchain, or simply import an external toolchain;
• configure, build and install selected target packages;
• build a kernel image, if selected;
• build a bootloader image, if selected;
• create a root filesystem in selected formats.
Buildroot output is stored in a single directory, output/. This directory contains several subdirectories:
• images/ where all the images (kernel image, bootloader and root filesystem images) are stored. These are the files you need
to put on your target system.
• build/ where all the components are built (this includes tools needed by Buildroot on the host and packages compiled for
the target). This directory contains one subdirectory for each of these components.
• staging/ which contains a hierarchy similar to a root filesystem hierarchy. This directory contains the headers and libraries
of the cross-compilation toolchain and all the userspace packages selected for the target. However, this directory is not intended
to be the root filesystem for the target: it contains a lot of development files, unstripped binaries and libraries that make it far
too big for an embedded system. These development files are used to compile libraries and applications for the target that
depend on other libraries.
• target/ which contains almost the complete root filesystem for the target: everything needed is present except the device
files in /dev/ (Buildroot can’t create them because Buildroot doesn’t run as root and doesn’t want to run as root). Also, it
doesn’t have the correct permissions (e.g. setuid for the busybox binary). Therefore, this directory should not be used on
your target. Instead, you should use one of the images built in the images/ directory. If you need an extracted image of
the root filesystem for booting over NFS, then use the tarball image generated in images/ and extract it as root. Compared
to staging/, target/ contains only the files and libraries needed to run the selected target applications: the development
files (headers, etc.) are not present, the binaries are stripped.
• host/ contains the installation of tools compiled for the host that are needed for the proper execution of Buildroot, including
the cross-compilation toolchain.
These commands, make menuconfig|nconfig|gconfig|xconfig and make, are the basic ones that allow to easily
and quickly generate images fitting your needs, with all the features and applications you enabled.
More details about the "make" command usage are given in Section 8.1.
The Buildroot user manual
8 / 114
Chapter 5
Community resources
Like any open source project, Buildroot has different ways to share information in its community and outside.
Each of those ways may interest you if you are looking for some help, want to understand Buildroot or contribute to the project.
Mailing List
Buildroot has a mailing list for discussion and development. It is the main method of interaction for Buildroot users and
developers.
Only subscribers to the Buildroot mailing list are allowed to post to this list. You can subscribe via the mailing list info
page.
Mails that are sent to the mailing list are also available in the mailing list archives and via Gmane, at gmane.comp.
lib.uclibc.buildroot. Please search the mailing list archives before asking questions, since there is a good chance
someone else has asked the same question before.
IRC
The Buildroot IRC channel #buildroot is hosted on Freenode. It is a useful place to ask quick questions or discuss on
certain topics.
When asking for help on IRC, share relevant logs or pieces of code using a code sharing website, such as http://code.bulix.org.
Note that for certain questions, posting to the mailing list may be better as it will reach more people, both developers and
users.
Bug tracker
Bugs in Buildroot can be reported via the mailing list or alternatively via the Buildroot bugtracker. Please refer to Section 21.6 before creating a bug report.
Wiki
The Buildroot wiki page is hosted on the eLinux wiki. It contains some useful links, an overview of past and upcoming
events, and a TODO list.
Patchwork
Patchwork is a web-based patch tracking system designed to facilitate the contribution and management of contributions to
an open-source project. Patches that have been sent to a mailing list are ’caught’ by the system, and appear on a web page.
Any comments posted that reference the patch are appended to the patch page too. For more information on Patchwork
see http://jk.ozlabs.org/projects/patchwork/.
Buildroot’s Patchwork website is mainly for use by Buildroot’s maintainer to ensure patches aren’t missed. It is also used
by Buildroot patch reviewers (see also Section 21.3.1). However, since the website exposes patches and their corresponding
review comments in a clean and concise web interface, it can be useful for all Buildroot developers.
The Buildroot patch management interface is available at http://patchwork.buildroot.org.
The Buildroot user manual
9 / 114
Part II
User guide
The Buildroot user manual
10 / 114
Chapter 6
Buildroot configuration
All the configuration options in make *config have a help text providing details about the option.
The make *config commands also offer a search tool. Read the help message in the different frontend menus to know how
to use it:
• in menuconfig, the search tool is called by pressing /;
• in xconfig, the search tool is called by pressing Ctrl + f.
The result of the search shows the help message of the matching items. In menuconfig, numbers in the left column provide a
shortcut to the corresponding entry. Just type this number to directly jump to the entry, or to the containing menu in case the
entry is not selectable due to a missing dependency.
Although the menu structure and the help text of the entries should be sufficiently self-explanatory, a number of topics require
additional explanation that cannot easily be covered in the help text and are therefore covered in the following sections.
6.1
Cross-compilation toolchain
A compilation toolchain is the set of tools that allows you to compile code for your system. It consists of a compiler (in our
case, gcc), binary utils like assembler and linker (in our case, binutils) and a C standard library (for example GNU Libc,
uClibc-ng).
The system installed on your development station certainly already has a compilation toolchain that you can use to compile an
application that runs on your system. If you’re using a PC, your compilation toolchain runs on an x86 processor and generates
code for an x86 processor. Under most Linux systems, the compilation toolchain uses the GNU libc (glibc) as the C standard
library. This compilation toolchain is called the "host compilation toolchain". The machine on which it is running, and on which
you’re working, is called the "host system" 1 .
The compilation toolchain is provided by your distribution, and Buildroot has nothing to do with it (other than using it to build a
cross-compilation toolchain and other tools that are run on the development host).
As said above, the compilation toolchain that comes with your system runs on and generates code for the processor in your host
system. As your embedded system has a different processor, you need a cross-compilation toolchain - a compilation toolchain
that runs on your host system but generates code for your target system (and target processor). For example, if your host system
uses x86 and your target system uses ARM, the regular compilation toolchain on your host runs on x86 and generates code for
x86, while the cross-compilation toolchain runs on x86 and generates code for ARM.
Buildroot provides two solutions for the cross-compilation toolchain:
• The internal toolchain backend, called Buildroot toolchain in the configuration interface.
1
This terminology differs from what is used by GNU configure, where the host is the machine on which the application will run (which is usually the same
as target)
The Buildroot user manual
11 / 114
• The external toolchain backend, called External toolchain in the configuration interface.
The choice between these two solutions is done using the Toolchain Type option in the Toolchain menu. Once one
solution has been chosen, a number of configuration options appear, they are detailed in the following sections.
6.1.1
Internal toolchain backend
The internal toolchain backend is the backend where Buildroot builds by itself a cross-compilation toolchain, before building the
userspace applications and libraries for your target embedded system.
This backend supports several C libraries: uClibc-ng, glibc and musl.
Once you have selected this backend, a number of options appear. The most important ones allow to:
• Change the version of the Linux kernel headers used to build the toolchain. This item deserves a few explanations. In the
process of building a cross-compilation toolchain, the C library is being built. This library provides the interface between
userspace applications and the Linux kernel. In order to know how to "talk" to the Linux kernel, the C library needs to have
access to the Linux kernel headers (i.e. the .h files from the kernel), which define the interface between userspace and the
kernel (system calls, data structures, etc.). Since this interface is backward compatible, the version of the Linux kernel headers
used to build your toolchain do not need to match exactly the version of the Linux kernel you intend to run on your embedded
system. They only need to have a version equal or older to the version of the Linux kernel you intend to run. If you use
kernel headers that are more recent than the Linux kernel you run on your embedded system, then the C library might be using
interfaces that are not provided by your Linux kernel.
• Change the version of the GCC compiler, binutils and the C library.
• Select a number of toolchain options (uClibc only): whether the toolchain should have RPC support (used mainly for NFS),
wide-char support, locale support (for internationalization), C++ support or thread support. Depending on which options you
choose, the number of userspace applications and libraries visible in Buildroot menus will change: many applications and
libraries require certain toolchain options to be enabled. Most packages show a comment when a certain toolchain option is
required to be able to enable those packages. If needed, you can further refine the uClibc configuration by running make
uclibc-menuconfig. Note however that all packages in Buildroot are tested against the default uClibc configuration
bundled in Buildroot: if you deviate from this configuration by removing features from uClibc, some packages may no longer
build.
It is worth noting that whenever one of those options is modified, then the entire toolchain and system must be rebuilt. See
Section 8.2.
Advantages of this backend:
• Well integrated with Buildroot
• Fast, only builds what’s necessary
Drawbacks of this backend:
• Rebuilding the toolchain is needed when doing make clean, which takes time. If you’re trying to reduce your build time,
consider using the External toolchain backend.
6.1.2
External toolchain backend
The external toolchain backend allows to use existing pre-built cross-compilation toolchains. Buildroot knows about a number of
well-known cross-compilation toolchains (from Linaro for ARM, Sourcery CodeBench for ARM, x86-64, PowerPC, and MIPS,
and is capable of downloading them automatically, or it can be pointed to a custom toolchain, either available for download or
installed locally.
Then, you have three solutions to use an external toolchain:
The Buildroot user manual
12 / 114
• Use a predefined external toolchain profile, and let Buildroot download, extract and install the toolchain. Buildroot already
knows about a few CodeSourcery and Linaro toolchains. Just select the toolchain profile in Toolchain from the available
ones. This is definitely the easiest solution.
• Use a predefined external toolchain profile, but instead of having Buildroot download and extract the toolchain, you can tell
Buildroot where your toolchain is already installed on your system. Just select the toolchain profile in Toolchain through
the available ones, unselect Download toolchain automatically, and fill the Toolchain path text entry with
the path to your cross-compiling toolchain.
• Use a completely custom external toolchain. This is particularly useful for toolchains generated using crosstool-NG or with
Buildroot itself. To do this, select the Custom toolchain solution in the Toolchain list. You need to fill the Toolch
ain path, Toolchain prefix and External toolchain C library options. Then, you have to tell Buildroot
what your external toolchain supports. If your external toolchain uses the glibc library, you only have to tell whether your
toolchain supports C++ or not and whether it has built-in RPC support. If your external toolchain uses the uClibc library, then
you have to tell Buildroot if it supports RPC, wide-char, locale, program invocation, threads and C++. At the beginning of the
execution, Buildroot will tell you if the selected options do not match the toolchain configuration.
Our external toolchain support has been tested with toolchains from CodeSourcery and Linaro, toolchains generated by crosstoolNG, and toolchains generated by Buildroot itself. In general, all toolchains that support the sysroot feature should work. If not,
do not hesitate to contact the developers.
We do not support toolchains or SDK generated by OpenEmbedded or Yocto, because these toolchains are not pure toolchains (i.e.
just the compiler, binutils, the C and C++ libraries). Instead these toolchains come with a very large set of pre-compiled libraries
and programs. Therefore, Buildroot cannot import the sysroot of the toolchain, as it would contain hundreds of megabytes of
pre-compiled libraries that are normally built by Buildroot.
We also do not support using the distribution toolchain (i.e. the gcc/binutils/C library installed by your distribution) as the
toolchain to build software for the target. This is because your distribution toolchain is not a "pure" toolchain (i.e. only with the
C/C++ library), so we cannot import it properly into the Buildroot build environment. So even if you are building a system for a
x86 or x86_64 target, you have to generate a cross-compilation toolchain with Buildroot or crosstool-NG.
If you want to generate a custom toolchain for your project, that can be used as an external toolchain in Buildroot, our recommendation is definitely to build it with crosstool-NG. We recommend to build the toolchain separately from Buildroot, and then
import it in Buildroot using the external toolchain backend.
Advantages of this backend:
• Allows to use well-known and well-tested cross-compilation toolchains.
• Avoids the build time of the cross-compilation toolchain, which is often very significant in the overall build time of an embedded Linux system.
Drawbacks of this backend:
• If your pre-built external toolchain has a bug, may be hard to get a fix from the toolchain vendor, unless you build your external
toolchain by yourself using Crosstool-NG.
6.1.2.1
External toolchain wrapper
When using an external toolchain, Buildroot generates a wrapper program, that transparently passes the appropriate options
(according to the configuration) to the external toolchain programs. In case you need to debug this wrapper to check exactly what
arguments are passed, you can set the environment variable BR2_DEBUG_WRAPPER to either one of:
• 0, empty or not set: no debug
• 1: trace all arguments on a single line
• 2: trace one argument per line
The Buildroot user manual
6.2
13 / 114
/dev management
On a Linux system, the /dev directory contains special files, called device files, that allow userspace applications to access the
hardware devices managed by the Linux kernel. Without these device files, your userspace applications would not be able to use
the hardware devices, even if they are properly recognized by the Linux kernel.
Under System configuration, /dev management, Buildroot offers four different solutions to handle the /dev directory :
• The first solution is Static using device table. This is the old classical way of handling device files in Linux. With this method,
the device files are persistently stored in the root filesystem (i.e. they persist across reboots), and there is nothing that will
automatically create and remove those device files when hardware devices are added or removed from the system. Buildroot
therefore creates a standard set of device files using a device table, the default one being stored in system/device_table
_dev.txt in the Buildroot source code. This file is processed when Buildroot generates the final root filesystem image, and
the device files are therefore not visible in the output/target directory. The BR2_ROOTFS_STATIC_DEVICE_TABLE
option allows to change the default device table used by Buildroot, or to add an additional device table, so that additional device
files are created by Buildroot during the build. So, if you use this method, and a device file is missing in your system, you
can for example create a board///device_table_dev.txt file that contains the
description of your additional device files, and then you can set BR2_ROOTFS_STATIC_DEVICE_TABLE to system/dev
ice_table_dev.txt board///device_table_dev.txt. For more details
about the format of the device table file, see Chapter 23.
• The second solution is Dynamic using devtmpfs only. devtmpfs is a virtual filesystem inside the Linux kernel that has been
introduced in kernel 2.6.32 (if you use an older kernel, it is not possible to use this option). When mounted in /dev, this
virtual filesystem will automatically make device files appear and disappear as hardware devices are added and removed from
the system. This filesystem is not persistent across reboots: it is filled dynamically by the kernel. Using devtmpfs requires
the following kernel configuration options to be enabled: CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT. When
Buildroot is in charge of building the Linux kernel for your embedded device, it makes sure that those two options are enabled.
However, if you build your Linux kernel outside of Buildroot, then it is your responsibility to enable those two options (if you
fail to do so, your Buildroot system will not boot).
• The third solution is Dynamic using devtmpfs + mdev. This method also relies on the devtmpfs virtual filesystem detailed
above (so the requirement to have CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT enabled in the kernel configuration still apply), but adds the mdev userspace utility on top of it. mdev is a program part of BusyBox that the kernel will call
every time a device is added or removed. Thanks to the /etc/mdev.conf configuration file, mdev can be configured to
for example, set specific permissions or ownership on a device file, call a script or application whenever a device appears or
disappear, etc. Basically, it allows userspace to react on device addition and removal events. mdev can for example be used to
automatically load kernel modules when devices appear on the system. mdev is also important if you have devices that require
a firmware, as it will be responsible for pushing the firmware contents to the kernel. mdev is a lightweight implementation
(with fewer features) of udev. For more details about mdev and the syntax of its configuration file, see http://git.busybox.net/busybox/tree/docs/mdev.txt.
• The fourth solution is Dynamic using devtmpfs + eudev. This method also relies on the devtmpfs virtual filesystem detailed
above, but adds the eudev userspace daemon on top of it. eudev is a daemon that runs in the background, and gets called
by the kernel when a device gets added or removed from the system. It is a more heavyweight solution than mdev, but
provides higher flexibility. eudev is a standalone version of udev, the original userspace daemon used in most desktop Linux
distributions, which is now part of Systemd. For more details, see http://en.wikipedia.org/wiki/Udev.
The Buildroot developers recommendation is to start with the Dynamic using devtmpfs only solution, until you have the need
for userspace to be notified when devices are added/removed, or if firmwares are needed, in which case Dynamic using devtmpfs
+ mdev is usually a good solution.
Note that if systemd is chosen as init system, /dev management will be performed by the udev program provided by systemd.
6.3
init system
The init program is the first userspace program started by the kernel (it carries the PID number 1), and is responsible for starting
the userspace services and programs (for example: web server, graphical applications, other network servers, etc.).
The Buildroot user manual
14 / 114
Buildroot allows to use three different types of init systems, which can be chosen from System configuration, Init
system:
• The first solution is BusyBox. Amongst many programs, BusyBox has an implementation of a basic init program, which
is sufficient for most embedded systems. Enabling the BR2_INIT_BUSYBOX will ensure BusyBox will build and install its
init program. This is the default solution in Buildroot. The BusyBox init program will read the /etc/inittab file
at boot to know what to do. The syntax of this file can be found in http://git.busybox.net/busybox/tree/examples/inittab (note
that BusyBox inittab syntax is special: do not use a random inittab documentation from the Internet to learn about
BusyBox inittab). The default inittab in Buildroot is stored in system/skeleton/etc/inittab. Apart from
mounting a few important filesystems, the main job the default inittab does is to start the /etc/init.d/rcS shell script,
and start a getty program (which provides a login prompt).
• The second solution is systemV. This solution uses the old traditional sysvinit program, packed in Buildroot in package/
sysvinit. This was the solution used in most desktop Linux distributions, until they switched to more recent alternatives
such as Upstart or Systemd. sysvinit also works with an inittab file (which has a slightly different syntax than the one
from BusyBox). The default inittab installed with this init solution is located in package/sysvinit/inittab.
• The third solution is systemd. systemd is the new generation init system for Linux. It does far more than traditional init
programs: aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand
starting of daemons, keeps track of processes using Linux control groups, supports snapshotting and restoring of the system
state, etc. systemd will be useful on relatively complex embedded systems, for example the ones requiring D-Bus and
services communicating between each other. It is worth noting that systemd brings a fairly big number of large dependencies:
dbus, udev and more. For more details about systemd, see http://www.freedesktop.org/wiki/Software/systemd.
The solution recommended by Buildroot developers is to use the BusyBox init as it is sufficient for most embedded systems.
systemd can be used for more complex situations.
The Buildroot user manual
15 / 114
Chapter 7
Configuration of other components
Before attempting to modify any of the components below, make sure you have already configured Buildroot itself, and have
enabled the corresponding package.
BusyBox
If you already have a BusyBox configuration file, you can directly specify this file in the Buildroot configuration, using
BR2_PACKAGE_BUSYBOX_CONFIG. Otherwise, Buildroot will start from a default BusyBox configuration file.
To make subsequent changes to the configuration, use make busybox-menuconfig to open the BusyBox configuration editor.
It is also possible to specify a BusyBox configuration file through an environment variable, although this is not recommended. Refer to Section 8.6 for more details.
uClibc
Configuration of uClibc is done in the same way as for BusyBox. The configuration variable to specify an existing
configuration file is BR2_UCLIBC_CONFIG. The command to make subsequent changes is make uclibc-menucon
fig.
Linux kernel
If you already have a kernel configuration file, you can directly specify this file in the Buildroot configuration, using
BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
If you do not yet have a kernel configuration file, you can either start by specifying a defconfig in the Buildroot configuration, using BR2_LINUX_KERNEL_USE_DEFCONFIG, or start by creating an empty file and specifying it as custom
configuration file, using BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
To make subsequent changes to the configuration, use make linux-menuconfig to open the Linux configuration
editor.
Barebox
Configuration of Barebox is done in the same way as for the Linux kernel. The corresponding configuration variables
are BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG and BR2_TARGET_BAREBOX_USE_DEFCONFIG. To open
the configuration editor, use make barebox-menuconfig.
U-Boot
Configuration of U-Boot (version 2015.04 or newer) is done in the same way as for the Linux kernel. The corresponding
configuration variables are BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG and BR2_TARGET_UBOOT_USE_DEFCO
NFIG. To open the configuration editor, use make uboot-menuconfig.
The Buildroot user manual
16 / 114
Chapter 8
General Buildroot usage
8.1 make tips
This is a collection of tips that help you make the most of Buildroot.
Display all commands executed by make:
$ make V=1
Display the list of boards with a defconfig:
$ make list-defconfigs
Display all available targets:
$ make help
Not all targets are always available, some settings in the .config file may hide some targets:
• busybox-menuconfig only works when busybox is enabled;
• linux-menuconfig and linux-savedefconfig only work when linux is enabled;
• uclibc-menuconfig is only available when the uClibc C library is selected in the internal toolchain backend;
• barebox-menuconfig and barebox-savedefconfig only work when the barebox bootloader is enabled.
• uboot-menuconfig and uboot-savedefconfig only work when the U-Boot bootloader is enabled.
Cleaning: Explicit cleaning is required when any of the architecture or toolchain configuration options are changed.
To delete all build products (including build directories, host, staging and target trees, the images and the toolchain):
$ make clean
Generating the manual: The present manual sources are located in the docs/manual directory. To generate the manual:
$ make manual-clean
$ make manual
The manual outputs will be generated in output/docs/manual.
N OTES
• A few tools are required to build the documentation (see: Section 2.2).
The Buildroot user manual
17 / 114
Resetting Buildroot for a new target: To delete all build products as well as the configuration:
$ make distclean
Notes If ccache is enabled, running make clean or distclean does not empty the compiler cache used by Buildroot. To
delete it, refer to Section 8.12.3.
Dumping the internal make variables: One can dump all the variables known to make, along with their values:
$ make -s printvars
VARIABLE=value_of_variable
...
It is possible to tweak the output using some variables:
• VARS will limit the listing to variables which names match the specified make-pattern
• QUOTED_VARS, if set to YES, will single-quote the value
• RAW_VARS, if set to YES, will print the unexpanded value
For example:
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
BUSYBOX_DEPENDENCIES=skeleton toolchain
BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
BUSYBOX_FINAL_PATCH_DEPENDENCIES=
BUSYBOX_RDEPENDENCIES=ncurses util-linux
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
BUSYBOX_DEPENDENCIES=’skeleton toolchain’
BUSYBOX_FINAL_ALL_DEPENDENCIES=’skeleton toolchain’
BUSYBOX_FINAL_DEPENDENCIES=’skeleton toolchain’
BUSYBOX_FINAL_PATCH_DEPENDENCIES=’’
BUSYBOX_RDEPENDENCIES=’ncurses util-linux’
$ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
BUSYBOX_DEPENDENCIES=skeleton toolchain
BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $( ←BUSYBOX_FINAL_PATCH_DEPENDENCIES))
BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
BUSYBOX_RDEPENDENCIES=ncurses util-linux
The output of quoted variables can be reused in shell scripts, for example:
$ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
$ echo $BUSYBOX_DEPENDENCIES
skeleton toolchain
8.2
Understanding when a full rebuild is necessary
Buildroot does not attempt to detect what parts of the system should be rebuilt when the system configuration is changed through
make menuconfig, make xconfig or one of the other configuration tools. In some cases, Buildroot should rebuild the
entire system, in some cases, only a specific subset of packages. But detecting this in a completely reliable manner is very
difficult, and therefore the Buildroot developers have decided to simply not attempt to do this.
Instead, it is the responsibility of the user to know when a full rebuild is necessary. As a hint, here are a few rules of thumb that
can help you understand how to work with Buildroot:
The Buildroot user manual
18 / 114
• When the target architecture configuration is changed, a complete rebuild is needed. Changing the architecture variant, the
binary format or the floating point strategy for example has an impact on the entire system.
• When the toolchain configuration is changed, a complete rebuild generally is needed. Changing the toolchain configuration
often involves changing the compiler version, the type of C library or its configuration, or some other fundamental configuration
item, and these changes have an impact on the entire system.
• When an additional package is added to the configuration, a full rebuild is not necessarily needed. Buildroot will detect that
this package has never been built, and will build it. However, if this package is a library that can optionally be used by packages
that have already been built, Buildroot will not automatically rebuild those. Either you know which packages should be rebuilt,
and you can rebuild them manually, or you should do a full rebuild. For example, let’s suppose you have built a system with
the ctorrent package, but without openssl. Your system works, but you realize you would like to have SSL support in
ctorrent, so you enable the openssl package in Buildroot configuration and restart the build. Buildroot will detect that
openssl should be built and will be build it, but it will not detect that ctorrent should be rebuilt to benefit from openssl
to add OpenSSL support. You will either have to do a full rebuild, or rebuild ctorrent itself.
• When a package is removed from the configuration, Buildroot does not do anything special. It does not remove the files
installed by this package from the target root filesystem or from the toolchain sysroot. A full rebuild is needed to get rid of
this package. However, generally you don’t necessarily need this package to be removed right now: you can wait for the next
lunch break to restart the build from scratch.
• When the sub-options of a package are changed, the package is not automatically rebuilt. After making such changes, rebuilding only this package is often sufficient, unless enabling the package sub-option adds some features to the package that are
useful for another package which has already been built. Again, Buildroot does not track when a package should be rebuilt:
once a package has been built, it is never rebuilt unless explicitly told to do so.
• When a change to the root filesystem skeleton is made, a full rebuild is needed. However, when changes to the root filesystem
overlay, a post-build script or a post-image script are made, there is no need for a full rebuild: a simple make invocation will
take the changes into account.
Generally speaking, when you’re facing a build error and you’re unsure of the potential consequences of the configuration changes
you’ve made, do a full rebuild. If you get the same build error, then you are sure that the error is not related to partial rebuilds
of packages, and if this error occurs with packages from the official Buildroot, do not hesitate to report the problem! As your
experience with Buildroot progresses, you will progressively learn when a full rebuild is really necessary, and you will save more
and more time.
For reference, a full rebuild is achieved by running:
$ make clean all
8.3
Understanding how to rebuild packages
One of the most common questions asked by Buildroot users is how to rebuild a given package or how to remove a package
without rebuilding everything from scratch.
Removing a package is unsupported by Buildroot without rebuilding from scratch. This is because Buildroot doesn’t keep track
of which package installs what files in the output/staging and output/target directories, or which package would be
compiled differently depending on the availability of another package.
The easiest way to rebuild a single package from scratch is to remove its build directory in output/build. Buildroot will
then re-extract, re-configure, re-compile and re-install this package from scratch. You can ask buildroot to do this with the make
-dirclean command.
On the other hand, if you only want to restart the build process of a package from its compilation step, you can run make
-rebuild, followed by make or make . It will restart the compilation and installation of the
package, but not from scratch: it basically re-executes make and make install inside the package, so it will only rebuild
files that changed.
If you want to restart the build process of a package from its configuration step, you can run make -reconfig
ure, followed by make or make . It will restart the configuration, compilation and installation of the package.
The Buildroot user manual
19 / 114
Internally, Buildroot creates so-called stamp files to keep track of which build steps have been completed for each package. They
are stored in the package build directory, output/build/-/ and are named .stamp_. The commands detailed above simply manipulate these stamp files to force Buildroot to restart a specific set of steps of
a package build process.
Further details about package special make targets are explained in Section 8.12.5.
8.4
Offline builds
If you intend to do an offline build and just want to download all sources that you previously selected in the configurator
(menuconfig, nconfig, xconfig or gconfig), then issue:
$ make source
You can now disconnect or copy the content of your dl directory to the build-host.
8.5
Building out-of-tree
As default, everything built by Buildroot is stored in the directory output in the Buildroot tree.
Buildroot also supports building out of tree with a syntax similar to the Linux kernel. To use it, add O= to the
make command line:
$ make O=/tmp/build
Or:
$ cd /tmp/build; make O=$PWD -C path/to/buildroot
All the output files will be located under /tmp/build. If the O path does not exist, Buildroot will create it.
Note: the O path can be either an absolute or a relative path, but if it’s passed as a relative path, it is important to note that it is
interpreted relative to the main Buildroot source directory, not the current working directory.
When using out-of-tree builds, the Buildroot .config and temporary files are also stored in the output directory. This means
that you can safely run multiple builds in parallel using the same source tree as long as they use unique output directories.
For ease of use, Buildroot generates a Makefile wrapper in the output directory - so after the first run, you no longer need to pass
O=<...> and -C <...>, simply run (in the output directory):
$ make
8.6
Environment variables
Buildroot also honors some environment variables, when they are passed to make or set in the environment:
• HOSTCXX, the host C++ compiler to use
• HOSTCC, the host C compiler to use
• UCLIBC_CONFIG_FILE=, path to the uClibc configuration file, used to compile uClibc, if an internal toolchain is being built.
Note that the uClibc configuration file can also be set from the configuration interface, so through the Buildroot .config file;
this is the recommended way of setting it.
The Buildroot user manual
20 / 114
• BUSYBOX_CONFIG_FILE=, path to the BusyBox configuration file.
Note that the BusyBox configuration file can also be set from the configuration interface, so through the Buildroot .config
file; this is the recommended way of setting it.
• BR2_CCACHE_DIR to override the directory where Buildroot stores the cached files when using ccache.
• BR2_DL_DIR to override the directory in which Buildroot stores/retrieves downloaded files
Note that the Buildroot download directory can also be set from the configuration interface, so through the Buildroot .config
file. See Section 8.12.4 for more details on how you can set the download directory.
• BR2_GRAPH_ALT, if set and non-empty, to use an alternate color-scheme in build-time graphs
• BR2_GRAPH_OUT to set the filetype of generated graphs, either pdf (the default), or png.
• BR2_GRAPH_DEPS_OPTS to pass extra options to the dependency graph; see Section 8.8 for the accepted options
• BR2_GRAPH_DOT_OPTS is passed verbatim as options to the dot utility to draw the dependency graph.
An example that uses config files located in the toplevel directory and in your $HOME:
$ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
If you want to use a compiler other than the default gcc or g++ for building helper-binaries on your host, then do
$ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
8.7
Dealing efficiently with filesystem images
Filesystem images can get pretty big, depending on the filesystem you choose, the number of packages, whether you provisioned
free space. . . Yet, some locations in the filesystems images may just be empty (e.g. a long run of zeroes); such a file is called a
sparse file.
Most tools can handle sparse files efficiently, and will only store or write those parts of a sparse file that are not empty.
For example:
• tar accepts the -S option to tell it to only store non-zero blocks of sparse files:
– tar cf archive.tar -S [files...] will efficiently store sparse files in a tarball
– tar xf archive.tar -S will efficiently store sparse files extracted from a tarball
• cp accepts the --sparse=WHEN option (WHEN is one of auto, never or always):
– cp --sparse=always source.file dest.file will make dest.file a sparse file if source.file has
long runs of zeroes
Other tools may have similar options. Please consult their respective man pages.
You can use sparse files if you need to store the filesystem images (e.g. to transfer from one machine to another), or if you need
to send them (e.g. to the Q&A team).
Note however that flashing a filesystem image to a device while using the sparse mode of dd may result in a broken filesystem
(e.g. the block bitmap of an ext2 filesystem may be corrupted; or, if you have sparse files in your filesystem, those parts may not
be all-zeroes when read back). You should only use sparse files when handling files on the build machine, not when transferring
them to an actual device that will be used on the target.
The Buildroot user manual
8.8
21 / 114
Graphing the dependencies between packages
One of Buildroot’s jobs is to know the dependencies between packages, and make sure they are built in the right order. These
dependencies can sometimes be quite complicated, and for a given system, it is often not easy to understand why such or such
package was brought into the build by Buildroot.
In order to help understanding the dependencies, and therefore better understand what is the role of the different components in
your embedded Linux system, Buildroot is capable of generating dependency graphs.
To generate a dependency graph of the full system you have compiled, simply run:
make graph-depends
You will find the generated graph in output/graphs/graph-depends.pdf.
If your system is quite large, the dependency graph may be too complex and difficult to read. It is therefore possible to generate
the dependency graph just for a given package:
make -graph-depends
You will find the generated graph in output/graph/-graph-depends.pdf.
Note that the dependency graphs are generated using the dot tool from the Graphviz project, which you must have installed on
your system to use this feature. In most distributions, it is available as the graphviz package.
By default, the dependency graphs are generated in the PDF format. However, by passing the BR2_GRAPH_OUT environment
variable, you can switch to other output formats, such as PNG, PostScript or SVG. All formats supported by the -T option of the
dot tool are supported.
BR2_GRAPH_OUT=svg make graph-depends
The graph-depends behaviour can be controlled by setting options in the BR2_GRAPH_DEPS_OPTS environment variable.
The accepted options are:
• --depth N, -d N, to limit the dependency depth to N levels. The default, 0, means no limit.
• --stop-on PKG, -s PKG, to stop the graph on the package PKG. PKG can be an actual package name, a glob, the keyword
virtual (to stop on virtual packages), or the keyword host (to stop on host packages). The package is still present on the graph,
but its dependencies are not.
• --exclude PKG, -x PKG, like --stop-on, but also omits PKG from the graph.
• --transitive, --no-transitive, to draw (or not) the transitive dependencies. The default is to not draw transitive
dependencies.
• --colors R,T,H, the comma-separated list of colors to draw the root package (R), the target packages (T) and the host
packages (H). Defaults to: lightblue,grey,gainsboro
BR2_GRAPH_DEPS_OPTS=’-d 3 --no-transitive --colors=red,green,blue’ make graph-depends
8.9
Graphing the build duration
When the build of a system takes a long time, it is sometimes useful to be able to understand which packages are the longest to
build, to see if anything can be done to speed up the build. In order to help such build time analysis, Buildroot collects the build
time of each step of each package, and allows to generate graphs from this data.
To generate the build time graph after a build, run:
make graph-build
The Buildroot user manual
22 / 114
This will generate a set of files in output/graphs :
• build.hist-build.pdf, a histogram of the build time for each package, ordered in the build order.
• build.hist-duration.pdf, a histogram of the build time for each package, ordered by duration (longest first)
• build.hist-name.pdf, a histogram of the build time for each package, order by package name.
• build.pie-packages.pdf, a pie chart of the build time per package
• build.pie-steps.pdf, a pie chart of the global time spent in each step of the packages build process.
This graph-build target requires the Python Matplotlib and Numpy libraries to be installed (python-matplotlib and
python-numpy on most distributions), and also the argparse module if you’re using a Python version older than 2.7 (pyt
hon-argparse on most distributions).
By default, the output format for the graph is PDF, but a different format can be selected using the BR2_GRAPH_OUT environment variable. The only other format supported is PNG:
BR2_GRAPH_OUT=png make graph-build
8.10
Graphing the filesystem size contribution of packages
When your target system grows, it is sometimes useful to understand how much each Buildroot package is contributing to the
overall root filesystem size. To help with such an analysis, Buildroot collects data about files installed by each package and using
this data, generates a graph and CSV files detailing the size contribution of the different packages.
To generate these data after a build, run:
make graph-size
This will generate:
• output/graphs/graph-size.pdf, a pie chart of the contribution of each package to the overall root filesystem size
• output/graphs/package-size-stats.csv, a CSV file giving the size contribution of each package to the overall
root filesystem size
• output/graphs/file-size-stats.csv, a CSV file giving the size contribution of each installed file to the package
it belongs, and to the overall filesystem size.
This graph-size target requires the Python Matplotlib library to be installed (python-matplotlib on most distributions),
and also the argparse module if you’re using a Python version older than 2.7 (python-argparse on most distributions).
Just like for the duration graph, a BR2_GRAPH_OUT environment is supported to adjust the output file format. See Section 8.8
for details about this environment variable.
Note The collected filesystem size data is only meaningful after a complete clean rebuild. Be sure to run make clean all
before using make graph-size.
To compare the root filesystem size of two different Buildroot compilations, for example after adjusting the configuration or
when switching to another Buildroot release, use the size-stats-compare script. It takes two file-size-stats.csv
files (produced by make graph-size) as input. Refer to the help text of this script for more details:
utils/size-stats-compare -h
The Buildroot user manual
8.11
23 / 114
Integration with Eclipse
While a part of the embedded Linux developers like classical text editors like Vim or Emacs, and command-line based interfaces,
a number of other embedded Linux developers like richer graphical interfaces to do their development work. Eclipse being one
of the most popular Integrated Development Environment, Buildroot integrates with Eclipse in order to ease the development
work of Eclipse users.
Our integration with Eclipse simplifies the compilation, remote execution and remote debugging of applications and libraries
that are built on top of a Buildroot system. It does not integrate the Buildroot configuration and build processes themselves with
Eclipse. Therefore, the typical usage model of our Eclipse integration would be:
• Configure your Buildroot system with make menuconfig, make xconfig or any other configuration interface provided
with Buildroot.
• Build your Buildroot system by running make.
• Start Eclipse to develop, execute and debug your own custom applications and libraries, that will rely on the libraries built and
installed by Buildroot.
The Buildroot Eclipse integration installation process and usage is described in detail at https://github.com/mbats/eclipse-buildrootbundle/wiki.
8.12
Advanced usage
8.12.1
Using the generated toolchain outside Buildroot
You may want to compile, for your target, your own programs or other software that are not packaged in Buildroot. In order to
do this you can use the toolchain that was generated by Buildroot.
The toolchain generated by Buildroot is located by default in output/host/. The simplest way to use it is to add output/
host/bin/ to your PATH environment variable and then to use ARCH-linux-gcc, ARCH-linux-objdump, ARCHlinux-ld, etc.
It is possible to relocate the toolchain, this allows to distribute the toolchain to other developers to build applications for your
target. To achieve this:
• run make sdk, which prepares the toolchain to be relocatable;
• tarball the contents of the output/host directory;
• distribute the resulting tarball.
Once the toolchain is installed to the new location, the user must run the relocate-sdk.sh script to make sure all paths are
updated with the new location.
8.12.2
Using gdb in Buildroot
Buildroot allows to do cross-debugging, where the debugger runs on the build machine and communicates with gdbserver on
the target to control the execution of the program.
To achieve this:
• If you are using an internal toolchain (built by Buildroot), you must enable BR2_PACKAGE_HOST_GDB, BR2_PACKAGE
_GDB and BR2_PACKAGE_GDB_SERVER. This ensures that both the cross gdb and gdbserver get built, and that gdbserver
gets installed to your target.
The Buildroot user manual
24 / 114
• If you are using an external toolchain, you should enable BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY, which will
copy the gdbserver included with the external toolchain to the target. If your external toolchain does not have a cross gdb or
gdbserver, it is also possible to let Buildroot build them, by enabling the same options as for the internal toolchain backend.
Now, to start debugging a program called foo, you should run on the target:
gdbserver :2345 foo
This will cause gdbserver to listen on TCP port 2345 for a connection from the cross gdb.
Then, on the host, you should start the cross gdb using the following command line:
/output/host/bin/-gdb -x /output/staging/usr/share/buildroot/ ←gdbinit foo
Of course, foo must be available in the current directory, built with debugging symbols. Typically you start this command from
the directory where foo is built (and not from output/target/ as the binaries in that directory are stripped).
The /output/staging/usr/share/buildroot/gdbinit file will tell the cross gdb where to find the
libraries of the target.
Finally, to connect to the target from the cross gdb:
(gdb) target remote :2345
8.12.3
Using ccache in Buildroot
ccache is a compiler cache. It stores the object files resulting from each compilation process, and is able to skip future compilation
of the same source file (with same compiler and same arguments) by using the pre-existing object files. When doing almost
identical builds from scratch a number of times, it can nicely speed up the build process.
ccache support is integrated in Buildroot. You just have to enable Enable compiler cache in Build options. This
will automatically build ccache and use it for every host and target compilation.
The cache is located in $HOME/.buildroot-ccache. It is stored outside of Buildroot output directory so that it can be
shared by separate Buildroot builds. If you want to get rid of the cache, simply remove this directory.
You can get statistics on the cache (its size, number of hits, misses, etc.) by running make ccache-stats.
The make target ccache-options and the CCACHE_OPTIONS variable provide more generic access to the ccache. For
example
# set cache limit size
make CCACHE_OPTIONS="--max-size=5G" ccache-options
# zero statistics counters
make CCACHE_OPTIONS="--zero-stats" ccache-options
ccache makes a hash of the source files and of the compiler options. If a compiler option is different, the cached object file
will not be used. Many compiler options, however, contain an absolute path to the staging directory. Because of this, building in
a different output directory would lead to many cache misses.
To avoid this issue, buildroot has the Use relative paths option (BR2_CCACHE_USE_BASEDIR). This will rewrite all
absolute paths that point inside the output directory into relative paths. Thus, changing the output directory no longer leads to
cache misses.
A disadvantage of the relative paths is that they also end up to be relative paths in the object file. Therefore, for example, the
debugger will no longer find the file, unless you cd to the output directory first.
See the ccache manual’s section on "Compiling in different directories" for more details about this rewriting of absolute paths.
The Buildroot user manual
8.12.4
25 / 114
Location of downloaded packages
The various tarballs that are downloaded by Buildroot are all stored in BR2_DL_DIR, which by default is the dl directory. If
you want to keep a complete version of Buildroot which is known to be working with the associated tarballs, you can make a
copy of this directory. This will allow you to regenerate the toolchain and the target filesystem with exactly the same versions.
If you maintain several Buildroot trees, it might be better to have a shared download location. This can be achieved by pointing the
BR2_DL_DIR environment variable to a directory. If this is set, then the value of BR2_DL_DIR in the Buildroot configuration
is overridden. The following line should be added to <~/.bashrc>.
export BR2_DL_DIR=
The download location can also be set in the .config file, with the BR2_DL_DIR option. Unlike most options in the .config
file, this value is overridden by the BR2_DL_DIR environment variable.
8.12.5
Package-specific make targets
Running make builds and installs that particular package and its dependencies.
For packages relying on the Buildroot infrastructure, there are numerous special make targets that can be called independently
like this:
make -
The package build targets are (in the order they are executed):
command/target
source
depends
extract
patch
configure
build
installstaging
install-target
install
Description
Fetch the source (download the tarball, clone the source repository, etc)
Build and install all dependencies required to build the package
Put the source in the package build directory (extract the tarball, copy the source, etc)
Apply the patches, if any
Run the configure commands, if any
Run the compilation commands
target package: Run the installation of the package in the staging directory, if
necessary
target package: Run the installation of the package in the target directory, if
necessary
target package: Run the 2 previous installation commands
host package: Run the installation of the package in the host directory
Additionally, there are some other useful make targets:
command/target
show-depends
graph-depends
dirclean
reinstall
rebuild
reconfigure
Description
Displays the dependencies required to build the package
Generate a dependency graph of the package, in the context of the current Buildroot
configuration. See this section Section 8.8 for more details about dependency graphs.
Remove the whole package build directory
Re-run the install commands
Re-run the compilation commands - this only makes sense when using the
OVERRIDE_SRCDIR feature or when you modified a file directly in the build
directory
Re-run the configure commands, then rebuild - this only makes sense when using the
OVERRIDE_SRCDIR feature or when you modified a file directly in the build
directory
The Buildroot user manual
8.12.6
26 / 114
Using Buildroot during development
The normal operation of Buildroot is to download a tarball, extract it, configure, compile and install the software component
found inside this tarball. The source code is extracted in output/build/-, which is a temporary
directory: whenever make clean is used, this directory is entirely removed, and re-created at the next make invocation. Even
when a Git or Subversion repository is used as the input for the package source code, Buildroot creates a tarball out of it, and
then behaves as it normally does with tarballs.
This behavior is well-suited when Buildroot is used mainly as an integration tool, to build and integrate all the components of
an embedded Linux system. However, if one uses Buildroot during the development of certain components of the system, this
behavior is not very convenient: one would instead like to make a small change to the source code of one package, and be able
to quickly rebuild the system with Buildroot.
Making changes directly in output/build/- is not an appropriate solution, because this directory
is removed on make clean.
Therefore, Buildroot provides a specific mechanism for this use case: the _OVERRIDE_SRCDIR mechanism. Buildroot
reads an override file, which allows the user to tell Buildroot the location of the source for certain packages. By default this
override file is named local.mk and located in the top directory of the Buildroot source tree, but a different location can be
specified through the BR2_PACKAGE_OVERRIDE_FILE configuration option.
In this override file, Buildroot expects to find lines of the form:
_OVERRIDE_SRCDIR = /path/to/pkg1/sources
_OVERRIDE_SRCDIR = /path/to/pkg2/sources
For example:
LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
When Buildroot finds that for a given package, an _OVERRIDE_SRCDIR has been defined, it will no longer attempt to
download, extract and patch the package. Instead, it will directly use the source code available in the specified directory and
make clean will not touch this directory. This allows to point Buildroot to your own directories, that can be managed by
Git, Subversion, or any other version control system. To achieve this, Buildroot will use rsync to copy the source code of the
component from the specified _OVERRIDE_SRCDIR to output/build/-custom/.
This mechanism is best used in conjunction with the make -rebuild and make -reconfigure targets.
A make -rebuild all sequence will rsync the source code from _OVERRIDE_SRCDIR to output/
build/-custom (thanks to rsync, only the modified files are copied), and restart the build process of just this
package.
In the example of the linux package above, the developer can then make a source code change in /home/bob/linux and
then run:
make linux-rebuild all
and in a matter of seconds gets the updated Linux kernel image in output/images. Similarly, a change can be made to the
BusyBox source code in /home/bob/busybox, and after:
make busybox-rebuild all
the root filesystem image in output/images contains the updated BusyBox.
Source trees for big projects often contain hundreds or thousands of files which are not needed for building, but will slow down
the process of copying the sources with rsync. Optionally, it is possible define _OVERRIDE_SRCDIR_RSYNC_EXCLU
SIONS to skip syncing certain files from the source tree. For example, when working on the webkitgtk package, the following
will exclude the tests and in-tree builds from a local WebKit source tree:
WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
--exclude JSTests --exclude ManualTests --exclude PerformanceTests \
--exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
--exclude WebKit.xcworkspace --exclude Websites --exclude Examples
The Buildroot user manual
27 / 114
Chapter 9
Project-specific customization
Typical actions you may need to perform for a given project are:
• configuring Buildroot (including build options and toolchain, bootloader, kernel, package and filesystem image type selection)
• configuring other components, like the Linux kernel and BusyBox
• customizing the generated target filesystem
– adding or overwriting files on the target filesystem (using BR2_ROOTFS_OVERLAY)
– modifying or deleting files on the target filesystem (using BR2_ROOTFS_POST_BUILD_SCRIPT)
– running arbitrary commands prior to generating the filesystem image (using BR2_ROOTFS_POST_BUILD_SCRIPT)
– setting file permissions and ownership (using BR2_ROOTFS_DEVICE_TABLE)
– adding custom devices nodes (using BR2_ROOTFS_STATIC_DEVICE_TABLE)
• adding custom user accounts (using BR2_ROOTFS_USERS_TABLES)
• running arbitrary commands after generating the filesystem image (using BR2_ROOTFS_POST_IMAGE_SCRIPT)
• adding project-specific patches to some packages (using BR2_GLOBAL_PATCH_DIR)
• adding project-specific packages
An important note regarding such project-specific customizations: please carefully consider which changes are indeed projectspecific and which changes are also useful to developers outside your project. The Buildroot community highly recommends
and encourages the upstreaming of improvements, packages and board support to the official Buildroot project. Of course, it is
sometimes not possible or desirable to upstream because the changes are highly specific or proprietary.
This chapter describes how to make such project-specific customizations in Buildroot and how to store them in a way that you
can build the same image in a reproducible way, even after running make clean. By following the recommended strategy, you
can even use the same Buildroot tree to build multiple distinct projects!
9.1
Recommended directory structure
When customizing Buildroot for your project, you will be creating one or more project-specific files that need to be stored
somewhere. While most of these files could be placed in any location as their path is to be specified in the Buildroot configuration,
the Buildroot developers recommend a specific directory structure which is described in this section.
Orthogonal to this directory structure, you can choose where you place this structure itself: either inside the Buildroot tree, or
outside of it using a br2-external tree. Both options are valid, the choice is up to you.
The Buildroot user manual
+-|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
+-|
|
+-|
|
|
|
|
|
|
|
|
|
+-+--
28 / 114
board/
+-- /
+-- /
+-- linux.config
+-- busybox.config
+--
+-- post_build.sh
+-- post_image.sh
+-- rootfs_overlay/
|
+-- etc/
|
+--
+-- patches/
+-- foo/
|
+--
+-- libbar/
+--
configs/
+-- _defconfig
package/
+-- /
+-- Config.in (if not using a br2-external tree)
+-- .mk (if not using a br2-external tree)
+-- package1/
|
+-- Config.in
|
+-- package1.mk
+-- package2/
+-- Config.in
+-- package2.mk
Config.in (if using a br2-external tree)
external.mk (if using a br2-external tree)
Details on the files shown above are given further in this chapter.
Note: if you choose to place this structure outside of the Buildroot tree but in a br2-external tree, the and possibly
components may be superfluous and can be left out.
9.1.1
Implementing layered customizations
It is quite common for a user to have several related projects that partly need the same customizations. Instead of duplicating
these customizations for each project, it is recommended to use a layered customization approach, as explained in this section.
Almost all of the customization methods available in Buildroot, like post-build scripts and root filesystem overlays, accept a
space-separated list of items. The specified items are always treated in order, from left to right. By creating more than one
such item, one for the common customizations and another one for the really project-specific customizations, you can avoid
unnecessary duplication. Each layer is typically embodied by a separate directory inside board//. Depending on
your projects, you could even introduce more than two layers.
An example directory structure for where a user has two customization layers common and fooboard is:
+-- board/
+-- /
+-- common/
|
+-- post_build.sh
|
+-- rootfs_overlay/
|
|
+-- ...
|
+-- patches/
|
+-- ...
|
The Buildroot user manual
29 / 114
+-- fooboard/
+-- linux.config
+-- busybox.config
+--
+-- post_build.sh
+-- rootfs_overlay/
|
+-- ...
+-- patches/
+-- ...
For example, if the user has the BR2_GLOBAL_PATCH_DIR configuration option set as:
BR2_GLOBAL_PATCH_DIR="board//common/patches board//fooboard/patches"
then first the patches from the common layer would be applied, followed by the patches from the fooboard layer.
9.2
Keeping customizations outside of Buildroot
As already briefly mentioned in Section 9.1, you can place project-specific customizations in two locations:
• directly within the Buildroot tree, typically maintaining them using branches in a version control system so that upgrading to
a newer Buildroot release is easy.
• outside of the Buildroot tree, using the br2-external mechanism. This mechanism allows to keep package recipes, board
support and configuration files outside of the Buildroot tree, while still having them nicely integrated in the build logic. We
call this location a br2-external tree. This section explains how to use the br2-external mechanism and what to provide in a
br2-external tree.
One can tell Buildroot to use one or more br2-external trees by setting the BR2_EXTERNAL make variable set to the path(s) of
the br2-external tree(s) to use. It can be passed to any Buildroot make invocation. It is automatically saved in the hidden .brexternal.mk file in the output directory. Thanks to this, there is no need to pass BR2_EXTERNAL at every make invocation.
It can however be changed at any time by passing a new value, and can be removed by passing an empty value.
Note The path to a br2-external tree can be either absolute or relative. If it is passed as a relative path, it is important to note that
it is interpreted relative to the main Buildroot source directory, not to the Buildroot output directory.
Note: If using an br2-external tree from before Buildroot 2016.11, you need to convert it before you can use it with Buildroot
2016.11 onward. See Section 25.1 for help on doing so.
Some examples:
buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
From now on, definitions from the /path/to/foo br2-external tree will be used:
buildroot/ $ make
buildroot/ $ make legal-info
We can switch to another br2-external tree at any time:
buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
We can also use multiple br2-external trees:
buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
Or disable the usage of any br2-external tree:
buildroot/ $ make BR2_EXTERNAL= xconfig
The Buildroot user manual
9.2.1
30 / 114
Layout of a br2-external tree
A br2-external tree must contain at least those three files, described in the following chapters:
• external.desc
• external.mk
• Config.in
Apart from those mandatory files, there may be additional and optional content that may be present in a br2-external tree, like
the configs/ directory. They are described in the following chapters as well.
A complete example br2-external tree layout is also described later.
9.2.1.1
The external.desc file
That file describes the br2-external tree: the name and description for that br2-external tree.
The format for this file is line based, with each line starting by a keyword, followed by a colon and one or more spaces, followed
by the value assigned to that keyword. There are two keywords currently recognised:
• name, mandatory, defines the name for that br2-external tree. That name must only use ASCII characters in the set [A-Zaz0-9_]; any other character is forbidden. Buildroot sets the variable BR2_EXTERNAL_$(NAME)_PATH to the absolute
path of the br2-external tree, so that you can use it to refer to your br2-external tree. This variable is available both in Kconfig,
so you can use it to source your Kconfig files (see below) and in the Makefile, so that you can use it to include other Makefiles
(see below) or refer to other files (like data files) from your br2-external tree.
Note: Since it is possible to use multiple br2-external trees at once, this name is used by Buildroot to generate variables for
each of those trees. That name is used to identify your br2-external tree, so try to come up with a name that really describes
your br2-external tree, in order for it to be relatively unique, so that it does not clash with another name from another br2external tree, especially if you are planning on somehow sharing your br2-external tree with third parties or using br2-external
trees from third parties.
• desc, optional, provides a short description for that br2-external tree. It shall fit on a single line, is mostly free-form (see
below), and is used when displaying information about a br2-external tree (e.g. above the list of defconfig files, or as the
prompt in the menuconfig); as such, it should relatively brief (40 chars is probably a good upper limit). The description is
available in the BR2_EXTERNAL_$(NAME)_DESC variable.
Examples of names and the corresponding BR2_EXTERNAL_$(NAME)_PATH variables:
• FOO → BR2_EXTERNAL_FOO_PATH
• BAR_42 → BR2_EXTERNAL_BAR_42_PATH
In the following examples, it is assumed the name to be set to BAR_42.
Note: Both BR2_EXTERNAL_$(NAME)_PATH and BR2_EXTERNAL_$(NAME)_DESC are available in the Kconfig files and
the Makefiles. They are also exported in the environment so are available in post-build, post-image and in-fakeroot scripts.
9.2.1.2
The Config.in and external.mk files
Those files (which may each be empty) can be used to define package recipes (i.e. foo/Config.in and foo/foo.mk like
for packages bundled in Buildroot itself) or other custom configuration options or make logic.
Buildroot automatically includes the Config.in from each br2-external tree to make it appear in the top-level configuration
menu, and includes the external.mk from each br2-external tree with the rest of the makefile logic.
The main usage of this is to store package recipes. The recommended way to do this is to write a Config.in file that looks
like:
The Buildroot user manual
31 / 114
source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
Then, have an external.mk file that looks like:
include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
And then in $(BR2_EXTERNAL_BAR_42_PATH)/package/package1 and $(BR2_EXTERNAL_BAR_42_PATH)/pac
kage/package2 create normal Buildroot package recipes, as explained in Chapter 17. If you prefer, you can also group the
packages in subdirectories called and adapt the above paths accordingly.
You can also define custom configuration options in Config.in and custom make logic in external.mk.
9.2.1.3
The configs/ directory
One can store Buildroot defconfigs in the configs subdirectory of the br2-external tree. Buildroot will automatically show
them in the output of make list-defconfigs and allow them to be loaded with the normal make _defconfig
command. They will be visible in the make list-defconfigs output, below an External configs label that contains the name
of the br2-external tree they are defined in.
Note: If a defconfig file is present in more than one br2-external tree, then the one from the last br2-external tree is used. It is
thus possible to override a defconfig bundled in Buildroot or another br2-external tree.
9.2.1.4
Free-form content
One can store all the board-specific configuration files there, such as the kernel configuration, the root filesystem overlay, or
any other configuration file for which Buildroot allows to set the location (by using the BR2_EXTERNAL_$(NAME)_PATH
variable). For example, you could set the paths to a global patch directory, to a rootfs overlay and to the kernel configuration file
as follows (e.g. by running make menuconfig and filling in these options):
BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board//overlay/
BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board//kernel. ←config
9.2.1.5
Example layout
Here is an example layout using all features of br2-external (the sample content is shown for the file above it, when it is relevant
to explain the br2-external tree; this is all entirely made up just for the sake of illustration, of course):
/path/to/br2-ext-tree/
|- external.desc
|
|name: BAR_42
|
|desc: Example br2-external tree
|
‘---|
|- Config.in
|
|source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
|
|source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
|
|
|
|config BAR_42_FLASH_ADDR
|
|
hex "my-board flash address"
|
|
default 0x10AD
|
‘---|
|- external.mk
|
|include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
The Buildroot user manual
|
|
|
|
|
|
|
||
|
|
|
|
|||
|
|
|
|
|
|
|
|
|
|
||
||||
||
|
|
|
|
|
||||
||||‘-
32 / 114
|
|flash-my-board:
|
$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
|
--image $(BINARIES_DIR)/image.bin \
|
--address $(BAR_42_FLASH_ADDR)
‘---package/pkg-1/Config.in
|config BR2_PACKAGE_PKG_1
|
bool "pkg-1"
|
help
|
Some help about pkg-1
‘---package/pkg-1/pkg-1.hash
package/pkg-1/pkg-1.mk
|PKG_1_VERSION = 1.2.3
|PKG_1_SITE = /some/where/to/get/pkg-1
|PKG_1_LICENSE = blabla
|
|define PKG_1_INSTALL_INIT_SYSV
|
$(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
|
$(TARGET_DIR)/etc/init.d/S99my-daemon
|endef
|
|$(eval $(autotools-package))
‘---package/pkg-1/S99my-daemon
package/pkg-2/Config.in
package/pkg-2/pkg-2.hash
package/pkg-2/pkg-2.mk
configs/my-board_defconfig
|BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
|BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
|BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post- ←image.sh"
|BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/ ←kernel.config"
‘---patches/linux/0001-some-change.patch
patches/linux/0002-some-other-change.patch
patches/busybox/0001-fix-something.patch
board/my-board/kernel.config
board/my-board/overlay/var/www/index.html
board/my-board/overlay/var/www/my.css
board/my-board/flash-image
board/my-board/post-image.sh
|#!/bin/sh
|generate-my-binary-image \
|
--root ${BINARIES_DIR}/rootfs.tar \
|
--kernel ${BINARIES_DIR}/zImage \
|
--dtb ${BINARIES_DIR}/my-board.dtb \
|
--output ${BINARIES_DIR}/image.bin
‘----
The br2-external tree will then be visible in the menuconfig (with the layout expanded):
External options --->
*** Example br2-external tree (in /path/to/br2-ext-tree/)
The Buildroot user manual
33 / 114
[ ] pkg-1
[ ] pkg-2
(0x10AD) my-board flash address
If you are using more than one br2-external tree, it would look like (with the layout expanded and the second one with name
FOO_27 but no desc: field in external.desc):
External options --->
Example br2-external tree --->
*** Example br2-external tree (in /path/to/br2-ext-tree)
[ ] pkg-1
[ ] pkg-2
(0x10AD) my-board flash address
FOO_27 --->
*** FOO_27 (in /path/to/another-br2-ext)
[ ] foo
[ ] bar
9.3
Storing the Buildroot configuration
The Buildroot configuration can be stored using the command make savedefconfig.
This strips the Buildroot configuration down by removing configuration options that are at their default value. The result is stored
in a file called defconfig. If you want to save it in another place, change the BR2_DEFCONFIG option in the Buildroot
configuration itself, or call make with make savedefconfig BR2_DEFCONFIG=.
The recommended place to store this defconfig is configs/_defconfig. If you follow this recommendation, the configuration will be listed in make help and can be set again by running make _defconfig.
Alternatively, you can copy the file to any other place and rebuild with make defconfig BR2_DEFCONFIG=.
9.4
Storing the configuration of other components
The configuration files for BusyBox, the Linux kernel, Barebox, U-Boot and uClibc should be stored as well if changed. For
each of these components, a Buildroot configuration option exists to point to an input configuration file, e.g. BR2_LINUX_KER
NEL_CUSTOM_CONFIG_FILE. To store their configuration, set these configuration options to a path where you want to save
the configuration files, and then use the helper targets described below to actually store the configuration.
As explained in Section 9.1, the recommended path to store these configuration files is board///
foo.config.
Make sure that you create a configuration file before changing the BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE etc. options. Otherwise, Buildroot will try to access this config file, which doesn’t exist yet, and will fail. You can create the configuration file by running make linux-menuconfig etc.
Buildroot provides a few helper targets to make the saving of configuration files easier.
• make linux-update-defconfig saves the linux configuration to the path specified by BR2_LINUX_KERNEL_CUST
OM_CONFIG_FILE. It simplifies the config file by removing default values. However, this only works with kernels starting
from 2.6.33. For earlier kernels, use make linux-update-config.
• make busybox-update-config saves the busybox configuration to the path specified by BR2_PACKAGE_BUSYBOX_
CONFIG.
• make uclibc-update-config saves the uClibc configuration to the path specified by BR2_UCLIBC_CONFIG.
• make barebox-update-defconfig saves the barebox configuration to the path specified by BR2_TARGET_BAREBO
X_CUSTOM_CONFIG_FILE.
The Buildroot user manual
34 / 114
• make uboot-update-defconfig saves the U-Boot configuration to the path specified by BR2_TARGET_UBOOT_CU
STOM_CONFIG_FILE.
• For at91bootstrap3, no helper exists so you have to copy the config file manually to BR2_TARGET_AT91BOOTSTRAP3_CU
STOM_CONFIG_FILE.
9.5
Customizing the generated target filesystem
Besides changing the configuration through make *config, there are a few other ways to customize the resulting target
filesystem.
The two recommended methods, which can co-exist, are root filesystem overlay(s) and post build script(s).
Root filesystem overlays (BR2_ROOTFS_OVERLAY)
A filesystem overlay is a tree of files that is copied directly over the target filesystem after it has been built. To enable this
feature, set config option BR2_ROOTFS_OVERLAY (in the System configuration menu) to the root of the overlay.
You can even specify multiple overlays, space-separated. If you specify a relative path, it will be relative to the root of the
Buildroot tree. Hidden directories of version control systems, like .git, .svn, .hg, etc., files called .empty and files
ending in ~ are excluded from the copy.
As shown in Section 9.1, the recommended path for this overlay is board///rootfsoverlay.
Post-build scripts (BR2_ROOTFS_POST_BUILD_SCRIPT)
Post-build scripts are shell scripts called after Buildroot builds all the selected software, but before the rootfs images are
assembled. To enable this feature, specify a space-separated list of post-build scripts in config option BR2_ROOTFS_PO
ST_BUILD_SCRIPT (in the System configuration menu). If you specify a relative path, it will be relative to the
root of the Buildroot tree.
Using post-build scripts, you can remove or modify any file in your target filesystem. You should, however, use this feature
with care. Whenever you find that a certain package generates wrong or unneeded files, you should fix that package rather
than work around it with some post-build cleanup scripts.
As shown in Section 9.1, the recommended path for this script is board///post_bu
ild.sh.
The post-build scripts are run with the main Buildroot tree as current working directory. The path to the target filesystem is
passed as the first argument to each script. If the config option BR2_ROOTFS_POST_SCRIPT_ARGS is not empty, these
arguments will be passed to the script too. All the scripts will be passed the exact same set of arguments, it is not possible
to pass different sets of arguments to each script.
In addition, you may also use these environment variables:
• BR2_CONFIG: the path to the Buildroot .config file
• HOST_DIR, STAGING_DIR, TARGET_DIR: see Section 17.5.2
• BUILD_DIR: the directory where packages are extracted and built
• BINARIES_DIR: the place where all binary files (aka images) are stored
• BASE_DIR: the base output directory
Below three more methods of customizing the target filesystem are described, but they are not recommended.
Direct modification of the target filesystem
For temporary modifications, you can modify the target filesystem directly and rebuild the image. The target filesystem is
available under output/target/. After making your changes, run make to rebuild the target filesystem image.
This method allows you to do anything to the target filesystem, but if you need to clean your Buildroot tree using make
clean, these changes will be lost. Such cleaning is necessary in several cases, refer to Section 8.2 for details. This
solution is therefore only useful for quick tests: changes do not survive the make clean command. Once you have
validated your changes, you should make sure that they will persist after a make clean, using a root filesystem overlay
or a post-build script.
The Buildroot user manual
35 / 114
Custom target skeleton (BR2_ROOTFS_SKELETON_CUSTOM)
The root filesystem image is created from a target skeleton, on top of which all packages install their files. The skeleton
is copied to the target directory output/target before any package is built and installed. The default target skeleton
provides the standard Unix filesystem layout and some basic init scripts and configuration files.
If the default skeleton (available under system/skeleton) does not match your needs, you would typically use a root
filesystem overlay or post-build script to adapt it. However, if the default skeleton is entirely different than what you need,
using a custom skeleton may be more suitable.
To enable this feature, enable config option BR2_ROOTFS_SKELETON_CUSTOM and set BR2_ROOTFS_SKELETON_C
USTOM_PATH to the path of your custom skeleton. Both options are available in the System configuration menu.
If you specify a relative path, it will be relative to the root of the Buildroot tree.
This method is not recommended because it duplicates the entire skeleton, which prevents taking advantage of the fixes or
improvements brought to the default skeleton in later Buildroot releases.
Post-fakeroot scripts (BR2_ROOTFS_POST_FAKEROOT_SCRIPT)
When aggregating the final images, some parts of the process requires root rights: creating device nodes in /dev, setting
permissions or ownership to files and directories. . . To avoid requiring actual root rights, Buildroot uses fakeroot to
simulate root rights. This is not a complete substitute for actually being root, but is enough for what Buildroot needs.
Post-fakeroot scripts are shell scripts that are called at the end of the fakeroot phase, right before the filesystem image
generator is called. As such, they are called in the fakeroot context.
Post-fakeroot scripts can be useful in case you need to tweak the filesystem to do modifications that are usually only
available to the root user.
Note: It is recommended to use the existing mechanisms to set file permissions or create entries in /dev (see Section 9.5.1)
or to create users (see Section 9.6)
Note: The difference between post-build scripts (above) and fakeroot scripts, is that post-build scripts are not called in the
fakeroot context.
Note; Using fakeroot is not an absolute substitute for actually being root. fakeroot only ever fakes the file access
rights and types (regular, block-or-char device. . . ) and uid/gid; these are emulated in-memory.
9.5.1
Setting file permissions and ownership and adding custom devices nodes
Sometimes it is needed to set specific permissions or ownership on files or device nodes. For example, certain files may need
to be owned by root. Since the post-build scripts are not run as root, you cannot do such changes from there unless you use an
explicit fakeroot from the post-build script.
Instead, Buildroot provides support for so-called permission tables. To use this feature, set config option BR2_ROOTFS_DEVI
CE_TABLE to a space-separated list of permission tables, regular text files following the makedev syntax Chapter 23.
If you are using a static device table (i.e. not using devtmpfs, mdev, or (e)udev) then you can add device nodes using the
same syntax, in so-called device tables. To use this feature, set config option BR2_ROOTFS_STATIC_DEVICE_TABLE to a
space-separated list of device tables.
As shown in Section 9.1, the recommended location for such files is board///.
It should be noted that if the specific permissions or device nodes are related to a specific application, you should set variables
FOO_PERMISSIONS and FOO_DEVICES in the package’s .mk file instead (see Section 17.5.2).
9.6
Adding custom user accounts
Sometimes it is needed to add specific users in the target system. To cover this requirement, Buildroot provides support for
so-called users tables. To use this feature, set config option BR2_ROOTFS_USERS_TABLES to a space-separated list of users
tables, regular text files following the makeusers syntax Chapter 24.
As shown in Section 9.1, the recommended location for such files is board///.
It should be noted that if the custom users are related to a specific application, you should set variable FOO_USERS in the
package’s .mk file instead (see Section 17.5.2).
The Buildroot user manual
9.7
36 / 114
Customization after the images have been created
While post-build scripts (Section 9.5) are run before building the filesystem image, kernel and bootloader, post-image scripts
can be used to perform some specific actions after all images have been created.
Post-image scripts can for example be used to automatically extract your root filesystem tarball in a location exported by your
NFS server, or to create a special firmware image that bundles your root filesystem and kernel image, or any other custom action
required for your project.
To enable this feature, specify a space-separated list of post-image scripts in config option BR2_ROOTFS_POST_IMAGE_SC
RIPT (in the System configuration menu). If you specify a relative path, it will be relative to the root of the Buildroot
tree.
Just like post-build scripts, post-image scripts are run with the main Buildroot tree as current working directory. The path to the
images output directory is passed as the first argument to each script. If the config option BR2_ROOTFS_POST_SCRIPT_A
RGS is not empty, these arguments will be passed to the script too. All the scripts will be passed the exact same set of arguments,
it is not possible to pass different sets of arguments to each script.
Again just like for the post-build scripts, the scripts have access to the environment variables BR2_CONFIG, HOST_DIR,
STAGING_DIR, TARGET_DIR, BUILD_DIR, BINARIES_DIR and BASE_DIR.
The post-image scripts will be executed as the user that executes Buildroot, which should normally not be the root user. Therefore,
any action requiring root permissions in one of these scripts will require special handling (usage of fakeroot or sudo), which is
left to the script developer.
9.8
Adding project-specific patches
It is sometimes useful to apply extra patches to packages - on top of those provided in Buildroot. This might be used to support
custom features in a project, for example, or when working on a new architecture.
The BR2_GLOBAL_PATCH_DIR configuration option can be used to specify a space separated list of one or more directories
containing package patches.
For a specific version of a specific package , patches are applied from BR2_GLOBA
L_PATCH_DIR as follows:
1. For every directory - - that exists in BR2_GLOBAL_PATCH_DIR, a will be determined as follows:
• /// if the directory exists.
• Otherwise, / if the directory exists.
2. Patches will then be applied from a as follows:
• If a series file exists in the package directory, then patches are applied according to the series file;
• Otherwise, patch files matching *.patch are applied in alphabetical order. So, to ensure they are applied in the
right order, it is highly recommended to name the patch files like this: -.patch, where
refers to the apply order.
For information about how patches are applied for a package, see Section 18.2
The BR2_GLOBAL_PATCH_DIR option is the preferred method for specifying a custom patch directory for packages. It can
be used to specify a patch directory for any package in buildroot. It should also be used in place of the custom patch directory
options that are available for packages such as U-Boot and Barebox. By doing this, it will allow a user to manage their patches
from one top-level directory.
The exception to BR2_GLOBAL_PATCH_DIR being the preferred method for specifying custom patches is BR2_LINUX_KER
NEL_PATCH. BR2_LINUX_KERNEL_PATCH should be used to specify kernel patches that are available at an URL. Note: BR2
_LINUX_KERNEL_PATCH specifies kernel patches that are applied after patches available in BR2_GLOBAL_PATCH_DIR, as
it is done from a post-patch hook of the Linux package.
The Buildroot user manual
9.9
37 / 114
Adding project-specific packages
In general, any new package should be added directly in the package directory and submitted to the Buildroot upstream project.
How to add packages to Buildroot in general is explained in full detail in Chapter 17 and will not be repeated here. However,
your project may need some proprietary packages that cannot be upstreamed. This section will explain how you can keep such
project-specific packages in a project-specific directory.
As shown in Section 9.1, the recommended location for project-specific packages is package//. If you are using
the br2-external tree feature (see Section 9.2) the recommended location is to put them in a sub-directory named package/ in
your br2-external tree.
However, Buildroot will not be aware of the packages in this location, unless we perform some additional steps. As explained
in Chapter 17, a package in Buildroot basically consists of two files: a .mk file (describing how to build the package) and a
Config.in file (describing the configuration options for this package).
Buildroot will automatically include the .mk files in first-level subdirectories of the package directory (using the pattern
package/*/*.mk). If we want Buildroot to include .mk files from deeper subdirectories (like package//pac
kage1/) then we simply have to add a .mk file in a first-level subdirectory that includes these additional .mk files. Therefore,
create a file package//.mk with following contents (assuming you have only one extra directory
level below package//):
include $(sort $(wildcard package//*/*.mk))
For the Config.in files, create a file package//Config.in that includes the Config.in files of all your
packages. An exhaustive list has to be provided since wildcards are not supported in the source command of kconfig. For
example:
source "package//package1/Config.in"
source "package//package2/Config.in"
Include this new file package//Config.in from package/Config.in, preferably in a company-specific
menu to make merges with future Buildroot versions easier.
If using a br2-external tree, refer to Section 9.2 for how to fill in those files.
9.10
Quick guide to storing your project-specific customizations
Earlier in this chapter, the different methods for making project-specific customizations have been described. This section will
now summarize all this by providing step-by-step instructions to storing your project-specific customizations. Clearly, the steps
that are not relevant to your project can be skipped.
1. make menuconfig to configure toolchain, packages and kernel.
2. make linux-menuconfig to update the kernel config, similar for other configuration like busybox, uclibc, . . .
3. mkdir -p board//
4. Set the following options to board///.config (as far as they are
relevant):
• BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE
• BR2_PACKAGE_BUSYBOX_CONFIG
• BR2_UCLIBC_CONFIG
• BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE
• BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE
• BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE
The Buildroot user manual
38 / 114
5. Write the configuration files:
• make linux-update-defconfig
• make busybox-update-config
• make uclibc-update-config
• cp
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.5
Linearized : No
Page Count : 122
Page Mode : UseOutlines
Author :
Title : The Buildroot user manual
Subject :
Creator : DBLaTeX-0.3.10
Producer : pdfTeX-1.40.17
Create Date : 2018:05:09 21:01:43Z
Modify Date : 2018:05:09 21:01:43Z
Trapped : False
PTEX Fullbanner : This is pdfTeX, Version 3.14159265-2.6-1.40.17 (TeX Live 2016) kpathsea version 6.2.2
EXIF Metadata provided by EXIF.tools