The Buildroot user manual

The Buildroot user manual

The Buildroot user manual

ii

Contents

I Getting started

1

1 About Buildroot

2

2 System requirements

3

2.1 Mandatory packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 Optional packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3 Getting Buildroot

5

4 Buildroot quick start

6

5 Community resources

8

II User guide

9

6 Buildroot configuration

10

6.1 Cross-compilation toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

6.1.1 Internal toolchain backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6.1.2 External toolchain backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6.1.3 Build an external toolchain with Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6.1.3.1 External toolchain wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.2 /dev management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.3 init system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

7 Configuration of other components

16

8 General Buildroot usage

17

8.1 make tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

8.2 Understanding when a full rebuild is necessary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

8.3 Understanding how to rebuild packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

8.4 Offline builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

The Buildroot user manual

iii

8.5 Building out-of-tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 8.6 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8.7 Dealing efficiently with filesystem images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8.8 Details about packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.9 Graphing the dependencies between packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.10 Graphing the build duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.11 Graphing the filesystem size contribution of packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.12 Top-level parallel build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 8.13 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

8.13.1 Using the generated toolchain outside Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.13.2 Using gdb in Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.13.3 Using ccache in Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 8.13.4 Location of downloaded packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 8.13.5 Package-specific make targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 8.13.6 Using Buildroot during development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

9 Project-specific customization

30

9.1 Recommended directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

9.1.1 Implementing layered customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

9.2 Keeping customizations outside of Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

9.2.1 Layout of a br2-external tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

9.2.1.1 The external.desc file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

9.2.1.2 The Config.in and external.mk files . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

9.2.1.3 The configs/ directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

9.2.1.4 The provides/ directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

9.2.1.5 Free-form content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

9.2.1.6 Additional Linux kernel extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

9.2.1.7 Example layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

9.3 Storing the Buildroot configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

9.4 Storing the configuration of other components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

9.5 Customizing the generated target filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

9.5.1 Setting file permissions and ownership and adding custom devices nodes . . . . . . . . . . . . . . . . . 40

9.6 Adding custom user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

9.7 Customization after the images have been created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9.8 Adding project-specific patches and hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9.8.1 Providing extra patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9.8.2 Providing extra hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.9 Adding project-specific packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

9.10 Quick guide to storing your project-specific customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

The Buildroot user manual

iv

10 Integration topics

45

10.1 Systemd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

10.1.1 DBus daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

10.2 Using SELinux in Buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

10.2.1 Enabling SELinux support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

10.2.2 SELinux policy tweaking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

11 Frequently Asked Questions & Troubleshooting

47

11.1 The boot hangs after Starting network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

11.2 Why is there no compiler on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

11.3 Why are there no development files on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

11.4 Why is there no documentation on the target? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

11.5 Why are some packages not visible in the Buildroot config menu? . . . . . . . . . . . . . . . . . . . . . . . . . 48

11.6 Why not use the target directory as a chroot directory? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

11.7 Why doesn't Buildroot generate binary packages (.deb, .ipkg. . . )? . . . . . . . . . . . . . . . . . . . . . . . . . 48

11.8 How to speed-up the build process? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

11.9 How does Buildroot support Y2038? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

12 Known issues

51

13 Legal notice and licensing

52

13.1 Complying with open source licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

13.2 Complying with the Buildroot license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

13.2.1 Patches to packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

14 Beyond Buildroot

54

14.1 Boot the generated images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

14.1.1 NFS boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

14.1.2 Live CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

14.2 Chroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

III Developer guide

55

15 How Buildroot works

56

16 Coding style

57

16.1 Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

16.2 The .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

16.3 The genimage.cfg file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

16.4 The documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

16.5 Support scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

The Buildroot user manual

v

17 Adding support for a particular board

61

18 Adding new packages to Buildroot

62

18.1 Package directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

18.2 Config files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

18.2.1 Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

18.2.2 Config.in.host file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

18.2.3 Choosing depends on or select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

18.2.4 Dependencies on target and toolchain options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

18.2.5 Dependencies on a Linux kernel built by buildroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

18.2.6 Dependencies on udev /dev management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

18.2.7 Dependencies on features provided by virtual packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

18.3 The .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

18.4 The .hash file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

18.5 The SNNfoo start script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

18.6 Infrastructure for packages with specific build systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

18.6.1 generic-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

18.6.2 generic-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

18.7 Infrastructure for autotools-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

18.7.1 autotools-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

18.7.2 autotools-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

18.8 Infrastructure for CMake-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

18.8.1 cmake-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

18.8.2 cmake-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

18.9 Infrastructure for Python packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

18.9.1 python-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

18.9.2 python-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

18.9.3 Generating a python-package from a PyPI repository . . . . . . . . . . . . . . . . . . . . . . . . . 84

18.9.4 python-package CFFI backend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

18.10Infrastructure for LuaRocks-based packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

18.10.1 luarocks-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

18.10.2 luarocks-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

18.11Infrastructure for Perl/CPAN packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

18.11.1 perl-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

18.11.2 perl-package reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

18.12Infrastructure for virtual packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

18.12.1 virtual-package tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

18.12.2 Virtual package's Config.in file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

18.12.3 Virtual package's .mk file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download