"Fossies" - the Fresh Open Source Software Archive

Member "buildroot-2021.05/docs/manual/manual.text" (6 Jun 2021, 360590 Bytes) of package /linux/privat/buildroot-2021.05.tar.bz2:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) plain text source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes reports for "manual.text": 2021.05-rc3_vs_2021.05 or 2021.02.2_vs_2021.05.

    1 
    2 ---------------------------------------------------------------------
    3 
    4 The Buildroot user manual
    5 
    6 ---------------------------------------------------------------------
    7 ---------------------------------------------------------------------
    8 
    9 Table of Contents
   10 
   11  
   12 I. Getting started
   13 
   14     1. About Buildroot
   15     2. System requirements
   16 
   17         2.1. Mandatory packages
   18         2.2. Optional packages
   19 
   20     3. Getting Buildroot
   21     4. Buildroot quick start
   22     5. Community resources
   23 
   24 II. User guide
   25 
   26     6. Buildroot configuration
   27 
   28         6.1. Cross-compilation toolchain
   29         6.2. /dev management
   30         6.3. init system
   31 
   32     7. Configuration of other components
   33     8. General Buildroot usage
   34 
   35         8.1. make tips
   36         8.2. Understanding when a full rebuild is necessary
   37         8.3. Understanding how to rebuild packages
   38         8.4. Offline builds
   39         8.5. Building out-of-tree
   40         8.6. Environment variables
   41         8.7. Dealing efficiently with filesystem images
   42         8.8. Details about packages
   43         8.9. Graphing the dependencies between packages
   44         8.10. Graphing the build duration
   45         8.11. Graphing the filesystem size contribution of packages
   46         8.12. Top-level parallel build
   47         8.13. Integration with Eclipse
   48         8.14. Advanced usage
   49 
   50     9. Project-specific customization
   51 
   52         9.1. Recommended directory structure
   53         9.2. Keeping customizations outside of Buildroot
   54         9.3. Storing the Buildroot configuration
   55         9.4. Storing the configuration of other components
   56         9.5. Customizing the generated target filesystem
   57         9.6. Adding custom user accounts
   58         9.7. Customization after the images have been created
   59         9.8. Adding project-specific patches
   60         9.9. Adding project-specific packages
   61         9.10. Quick guide to storing your project-specific
   62             customizations
   63 
   64     10. Using SELinux in Buildroot
   65 
   66         10.1. Enabling SELinux support
   67         10.2. SELinux policy tweaking
   68 
   69     11. Frequently Asked Questions & Troubleshooting
   70 
   71         11.1. The boot hangs after Starting network…
   72         11.2. Why is there no compiler on the target?
   73         11.3. Why are there no development files on the target?
   74         11.4. Why is there no documentation on the target?
   75         11.5. Why are some packages not visible in the Buildroot
   76             config menu?
   77         11.6. Why not use the target directory as a chroot directory?
   78         11.7. Why doesn’t Buildroot generate binary packages (.deb,
   79             .ipkg…)?
   80         11.8. How to speed-up the build process?
   81 
   82     12. Known issues
   83     13. Legal notice and licensing
   84 
   85         13.1. Complying with open source licenses
   86         13.2. Complying with the Buildroot license
   87 
   88     14. Beyond Buildroot
   89 
   90         14.1. Boot the generated images
   91         14.2. Chroot
   92 
   93 III. Developer guide
   94 
   95     15. How Buildroot works
   96     16. Coding style
   97 
   98         16.1. Config.in file
   99         16.2. The .mk file
  100         16.3. The documentation
  101         16.4. Support scripts
  102 
  103     17. Adding support for a particular board
  104     18. Adding new packages to Buildroot
  105 
  106         18.1. Package directory
  107         18.2. Config files
  108         18.3. The .mk file
  109         18.4. The .hash file
  110         18.5. Infrastructure for packages with specific build systems
  111         18.6. Infrastructure for autotools-based packages
  112         18.7. Infrastructure for CMake-based packages
  113         18.8. Infrastructure for Python packages
  114         18.9. Infrastructure for LuaRocks-based packages
  115         18.10. Infrastructure for Perl/CPAN packages
  116         18.11. Infrastructure for virtual packages
  117         18.12. Infrastructure for packages using kconfig for
  118             configuration files
  119         18.13. Infrastructure for rebar-based packages
  120         18.14. Infrastructure for Waf-based packages
  121         18.15. Infrastructure for Meson-based packages
  122         18.16. Integration of Cargo-based packages
  123         18.17. Infrastructure for Go packages
  124         18.18. Infrastructure for QMake-based packages
  125         18.19. Infrastructure for packages building kernel modules
  126         18.20. Infrastructure for asciidoc documents
  127         18.21. Infrastructure specific to the Linux kernel package
  128         18.22. Hooks available in the various build steps
  129         18.23. Gettext integration and interaction with packages
  130         18.24. Tips and tricks
  131         18.25. Conclusion
  132 
  133     19. Patching a package
  134 
  135         19.1. Providing patches
  136         19.2. How patches are applied
  137         19.3. Format and licensing of the package patches
  138         19.4. Integrating patches found on the Web
  139 
  140     20. Download infrastructure
  141     21. Debugging Buildroot
  142     22. Contributing to Buildroot
  143 
  144         22.1. Reproducing, analyzing and fixing bugs
  145         22.2. Analyzing and fixing autobuild failures
  146         22.3. Reviewing and testing patches
  147         22.4. Work on items from the TODO list
  148         22.5. Submitting patches
  149         22.6. Reporting issues/bugs or getting help
  150         22.7. Using the run-tests framework
  151 
  152     23. DEVELOPERS file and get-developers
  153     24. Release Engineering
  154 
  155         24.1. Releases
  156         24.2. Development
  157 
  158 IV. Appendix
  159 
  160     25. Makedev syntax documentation
  161     26. Makeusers syntax documentation
  162     27. Migrating from older Buildroot versions
  163 
  164         27.1. Migrating to 2016.11
  165         27.2. Migrating to 2017.08
  166 
  167 List of Examples
  168 
  169 18.1. Config script: divine package
  170 18.2. Config script: imagemagick package:
  171 
  172 
  173 ---------------------------------------------------------------------
  174 
  175 ---------------------------------------------------------------------
  176 
  177 Buildroot 2021.05 manual generated on 2021-06-06 21:24:12 UTC from
  178 git revision 69f79f2a2e
  179 
  180 The Buildroot manual is written by the Buildroot developers. It is
  181 licensed under the GNU General Public License, version 2. Refer to
  182 the COPYING [http://git.buildroot.org/buildroot/tree/COPYING?id=
  183 69f79f2a2ee1417e19c1ead2c9226e11753c06cb] file in the Buildroot
  184 sources for the full text of this license.
  185 
  186 Copyright © 2004-2020 The Buildroot developers
  187 
  188 Part I. Getting started
  189 
  190 Table of Contents
  191 
  192 1. About Buildroot
  193 2. System requirements
  194 
  195     2.1. Mandatory packages
  196     2.2. Optional packages
  197 
  198 3. Getting Buildroot
  199 4. Buildroot quick start
  200 5. Community resources
  201 
  202 Chapter 1. About Buildroot
  203 
  204 Buildroot is a tool that simplifies and automates the process of
  205 building a complete Linux system for an embedded system, using
  206 cross-compilation.
  207 
  208 In order to achieve this, Buildroot is able to generate a
  209 cross-compilation toolchain, a root filesystem, a Linux kernel image
  210 and a bootloader for your target. Buildroot can be used for any
  211 combination of these options, independently (you can for example use
  212 an existing cross-compilation toolchain, and build only your root
  213 filesystem with Buildroot).
  214 
  215 Buildroot is useful mainly for people working with embedded systems.
  216 Embedded systems often use processors that are not the regular x86
  217 processors everyone is used to having in his PC. They can be PowerPC
  218 processors, MIPS processors, ARM processors, etc.
  219 
  220 Buildroot supports numerous processors and their variants; it also
  221 comes with default configurations for several boards available
  222 off-the-shelf. Besides this, a number of third-party projects are
  223 based on, or develop their BSP ^[1] or SDK ^[2] on top of Buildroot.
  224 
  225 
  226 ---------------------------------------------------------------------
  227 
  228 ^[1] BSP: Board Support Package
  229 
  230 ^[2] SDK: Software Development Kit
  231 
  232 Chapter 2. System requirements
  233 
  234 Buildroot is designed to run on Linux systems.
  235 
  236 While Buildroot itself will build most host packages it needs for the
  237 compilation, certain standard Linux utilities are expected to be
  238 already installed on the host system. Below you will find an overview
  239 of the mandatory and optional packages (note that package names may
  240 vary between distributions).
  241 
  242 2.1. Mandatory packages
  243 
  244   * Build tools:
  245 
  246       + which
  247       + sed
  248       + make (version 3.81 or any later)
  249       + binutils
  250       + build-essential (only for Debian based systems)
  251       + gcc (version 4.8 or any later)
  252       + g++ (version 4.8 or any later)
  253       + bash
  254       + patch
  255       + gzip
  256       + bzip2
  257       + perl (version 5.8.7 or any later)
  258       + tar
  259       + cpio
  260       + unzip
  261       + rsync
  262       + file (must be in /usr/bin/file)
  263       + bc
  264   * Source fetching tools:
  265 
  266       + wget
  267 
  268 2.2. Optional packages
  269 
  270   * Recommended dependencies:
  271 
  272     Some features or utilities in Buildroot, like the legal-info, or
  273     the graph generation tools, have additional dependencies.
  274     Although they are not mandatory for a simple build, they are
  275     still highly recommended:
  276 
  277       + python (version 2.7 or any later)
  278   * Configuration interface dependencies:
  279 
  280     For these libraries, you need to install both runtime and
  281     development data, which in many distributions are packaged
  282     separately. The development packages typically have a -dev or 
  283     -devel suffix.
  284 
  285       + ncurses5 to use the menuconfig interface
  286       + qt5 to use the xconfig interface
  287       + glib2, gtk2 and glade2 to use the gconfig interface
  288   * Source fetching tools:
  289 
  290     In the official tree, most of the package sources are retrieved
  291     using wget from ftp, http or https locations. A few packages are
  292     only available through a version control system. Moreover,
  293     Buildroot is capable of downloading sources via other tools, like
  294     rsync or scp (refer to Chapter 20, Download infrastructure for
  295     more details). If you enable packages using any of these methods,
  296     you will need to install the corresponding tool on the host
  297     system:
  298 
  299       + bazaar
  300       + cvs
  301       + git
  302       + mercurial
  303       + rsync
  304       + scp
  305       + subversion
  306   * Java-related packages, if the Java Classpath needs to be built
  307     for the target system:
  308 
  309       + The javac compiler
  310       + The jar tool
  311   * Documentation generation tools:
  312 
  313       + asciidoc, version 8.6.3 or higher
  314       + w3m
  315       + python with the argparse module (automatically present in
  316         2.7+ and 3.2+)
  317       + dblatex (required for the pdf manual only)
  318   * Graph generation tools:
  319 
  320       + graphviz to use graph-depends and <pkg>-graph-depends
  321       + python-matplotlib to use graph-build
  322 
  323 Chapter 3. Getting Buildroot
  324 
  325 Buildroot releases are made every 3 months, in February, May, August
  326 and November. Release numbers are in the format YYYY.MM, so for
  327 example 2013.02, 2014.08.
  328 
  329 Release tarballs are available at http://buildroot.org/downloads/.
  330 
  331 For your convenience, a Vagrantfile [https://www.vagrantup.com/] is
  332 available in support/misc/Vagrantfile in the Buildroot source tree to
  333 quickly set up a virtual machine with the needed dependencies to get
  334 started.
  335 
  336 If you want to setup an isolated buildroot environment on Linux or
  337 Mac Os X, paste this line onto your terminal:
  338 
  339 curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up
  340 
  341 If you are on Windows, paste this into your powershell:
  342 
  343 (new-object System.Net.WebClient).DownloadFile(
  344 "https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
  345 vagrant up
  346 
  347 If you want to follow development, you can use the daily snapshots or
  348 make a clone of the Git repository. Refer to the Download page [http:
  349 //buildroot.org/download] of the Buildroot website for more details.
  350 
  351 Chapter 4. Buildroot quick start
  352 
  353 Important: you can and should build everything as a normal user.
  354 There is no need to be root to configure and use Buildroot. By
  355 running all commands as a regular user, you protect your system
  356 against packages behaving badly during compilation and installation.
  357 
  358 The first step when using Buildroot is to create a configuration.
  359 Buildroot has a nice configuration tool similar to the one you can
  360 find in the Linux kernel [http://www.kernel.org/] or in BusyBox
  361 [http://www.busybox.net/].
  362 
  363 From the buildroot directory, run
  364 
  365  $ make menuconfig
  366 
  367 for the original curses-based configurator, or
  368 
  369  $ make nconfig
  370 
  371 for the new curses-based configurator, or
  372 
  373  $ make xconfig
  374 
  375 for the Qt-based configurator, or
  376 
  377  $ make gconfig
  378 
  379 for the GTK-based configurator.
  380 
  381 All of these "make" commands will need to build a configuration
  382 utility (including the interface), so you may need to install
  383 "development" packages for relevant libraries used by the
  384 configuration utilities. Refer to Chapter 2, System requirements for
  385 more details, specifically the optional requirements to get the
  386 dependencies of your favorite interface.
  387 
  388 For each menu entry in the configuration tool, you can find
  389 associated help that describes the purpose of the entry. Refer to
  390 Chapter 6, Buildroot configuration for details on some specific
  391 configuration aspects.
  392 
  393 Once everything is configured, the configuration tool generates a
  394 .config file that contains the entire configuration. This file will
  395 be read by the top-level Makefile.
  396 
  397 To start the build process, simply run:
  398 
  399  $ make
  400 
  401 By default, Buildroot does not support top-level parallel build, so
  402 running make -jN is not necessary. There is however experimental
  403 support for top-level parallel build, see Section 8.12, “Top-level
  404 parallel build”.
  405 
  406 The make command will generally perform the following steps:
  407 
  408   * download source files (as required);
  409   * configure, build and install the cross-compilation toolchain, or
  410     simply import an external toolchain;
  411   * configure, build and install selected target packages;
  412   * build a kernel image, if selected;
  413   * build a bootloader image, if selected;
  414   * create a root filesystem in selected formats.
  415 
  416 Buildroot output is stored in a single directory, output/. This
  417 directory contains several subdirectories:
  418 
  419   * images/ where all the images (kernel image, bootloader and root
  420     filesystem images) are stored. These are the files you need to
  421     put on your target system.
  422   * build/ where all the components are built (this includes tools
  423     needed by Buildroot on the host and packages compiled for the
  424     target). This directory contains one subdirectory for each of
  425     these components.
  426   * host/ contains both the tools built for the host, and the sysroot
  427     of the target toolchain. The former is an installation of tools
  428     compiled for the host that are needed for the proper execution of
  429     Buildroot, including the cross-compilation toolchain. The latter
  430     is a hierarchy similar to a root filesystem hierarchy. It
  431     contains the headers and libraries of all user-space packages
  432     that provide and install libraries used by other packages.
  433     However, this directory is not intended to be the root filesystem
  434     for the target: it contains a lot of development files,
  435     unstripped binaries and libraries that make it far too big for an
  436     embedded system. These development files are used to compile
  437     libraries and applications for the target that depend on other
  438     libraries.
  439   * staging/ is a symlink to the target toolchain sysroot inside host
  440     /, which exists for backwards compatibility.
  441   * target/ which contains almost the complete root filesystem for
  442     the target: everything needed is present except the device files
  443     in /dev/ (Buildroot can’t create them because Buildroot doesn’t
  444     run as root and doesn’t want to run as root). Also, it doesn’t
  445     have the correct permissions (e.g. setuid for the busybox
  446     binary). Therefore, this directory should not be used on your
  447     target. Instead, you should use one of the images built in the
  448     images/ directory. If you need an extracted image of the root
  449     filesystem for booting over NFS, then use the tarball image
  450     generated in images/ and extract it as root. Compared to staging
  451     /, target/ contains only the files and libraries needed to run
  452     the selected target applications: the development files (headers,
  453     etc.) are not present, the binaries are stripped.
  454 
  455 These commands, make menuconfig|nconfig|gconfig|xconfig and make, are
  456 the basic ones that allow to easily and quickly generate images
  457 fitting your needs, with all the features and applications you
  458 enabled.
  459 
  460 More details about the "make" command usage are given in Section 8.1,
  461 “make tips”.
  462 
  463 Chapter 5. Community resources
  464 
  465 Like any open source project, Buildroot has different ways to share
  466 information in its community and outside.
  467 
  468 Each of those ways may interest you if you are looking for some help,
  469 want to understand Buildroot or contribute to the project.
  470 
  471 Mailing List
  472 
  473     Buildroot has a mailing list for discussion and development. It
  474     is the main method of interaction for Buildroot users and
  475     developers.
  476 
  477     Only subscribers to the Buildroot mailing list are allowed to
  478     post to this list. You can subscribe via the mailing list info
  479     page [http://lists.buildroot.org/mailman/listinfo/buildroot].
  480 
  481     Mails that are sent to the mailing list are also available in the
  482     mailing list archives [http://lists.buildroot.org/pipermail/
  483     buildroot] and via Gmane [http://gmane.org], at
  484     gmane.comp.lib.uclibc.buildroot [http://dir.gmane.org/
  485     gmane.comp.lib.uclibc.buildroot]. Please search the mailing list
  486     archives before asking questions, since there is a good chance
  487     someone else has asked the same question before.
  488 
  489 IRC
  490 
  491     The Buildroot IRC channel #buildroot [irc://irc.oftc.net/#
  492     buildroot] is hosted on OFTC [https://www.oftc.net/WebChat/]. It
  493     is a useful place to ask quick questions or discuss on certain
  494     topics.
  495 
  496     When asking for help on IRC, share relevant logs or pieces of
  497     code using a code sharing website, such as http://code.bulix.org.
  498 
  499     Note that for certain questions, posting to the mailing list may
  500     be better as it will reach more people, both developers and
  501     users.
  502 
  503 Bug tracker
  504     Bugs in Buildroot can be reported via the mailing list or
  505     alternatively via the Buildroot bugtracker [https://
  506     bugs.buildroot.org/buglist.cgi?product=buildroot]. Please refer
  507     to Section 22.6, “Reporting issues/bugs or getting help” before
  508     creating a bug report.
  509 Wiki
  510     The Buildroot wiki page [http://elinux.org/Buildroot] is hosted
  511     on the eLinux [http://elinux.org] wiki. It contains some useful
  512     links, an overview of past and upcoming events, and a TODO list.
  513 Patchwork
  514 
  515     Patchwork is a web-based patch tracking system designed to
  516     facilitate the contribution and management of contributions to an
  517     open-source project. Patches that have been sent to a mailing
  518     list are 'caught' by the system, and appear on a web page. Any
  519     comments posted that reference the patch are appended to the
  520     patch page too. For more information on Patchwork see http://
  521     jk.ozlabs.org/projects/patchwork/.
  522 
  523     Buildroot’s Patchwork website is mainly for use by Buildroot’s
  524     maintainer to ensure patches aren’t missed. It is also used by
  525     Buildroot patch reviewers (see also Section 22.3.1, “Applying
  526     Patches from Patchwork”). However, since the website exposes
  527     patches and their corresponding review comments in a clean and
  528     concise web interface, it can be useful for all Buildroot
  529     developers.
  530 
  531     The Buildroot patch management interface is available at http://
  532     patchwork.buildroot.org.
  533 
  534 Part II. User guide
  535 
  536 Table of Contents
  537 
  538 6. Buildroot configuration
  539 
  540     6.1. Cross-compilation toolchain
  541     6.2. /dev management
  542     6.3. init system
  543 
  544 7. Configuration of other components
  545 8. General Buildroot usage
  546 
  547     8.1. make tips
  548     8.2. Understanding when a full rebuild is necessary
  549     8.3. Understanding how to rebuild packages
  550     8.4. Offline builds
  551     8.5. Building out-of-tree
  552     8.6. Environment variables
  553     8.7. Dealing efficiently with filesystem images
  554     8.8. Details about packages
  555     8.9. Graphing the dependencies between packages
  556     8.10. Graphing the build duration
  557     8.11. Graphing the filesystem size contribution of packages
  558     8.12. Top-level parallel build
  559     8.13. Integration with Eclipse
  560     8.14. Advanced usage
  561 
  562 9. Project-specific customization
  563 
  564     9.1. Recommended directory structure
  565     9.2. Keeping customizations outside of Buildroot
  566     9.3. Storing the Buildroot configuration
  567     9.4. Storing the configuration of other components
  568     9.5. Customizing the generated target filesystem
  569     9.6. Adding custom user accounts
  570     9.7. Customization after the images have been created
  571     9.8. Adding project-specific patches
  572     9.9. Adding project-specific packages
  573     9.10. Quick guide to storing your project-specific customizations
  574 
  575 10. Using SELinux in Buildroot
  576 
  577     10.1. Enabling SELinux support
  578     10.2. SELinux policy tweaking
  579 
  580 11. Frequently Asked Questions & Troubleshooting
  581 
  582     11.1. The boot hangs after Starting network…
  583     11.2. Why is there no compiler on the target?
  584     11.3. Why are there no development files on the target?
  585     11.4. Why is there no documentation on the target?
  586     11.5. Why are some packages not visible in the Buildroot config
  587         menu?
  588     11.6. Why not use the target directory as a chroot directory?
  589     11.7. Why doesn’t Buildroot generate binary packages (.deb,
  590         .ipkg…)?
  591     11.8. How to speed-up the build process?
  592 
  593 12. Known issues
  594 13. Legal notice and licensing
  595 
  596     13.1. Complying with open source licenses
  597     13.2. Complying with the Buildroot license
  598 
  599 14. Beyond Buildroot
  600 
  601     14.1. Boot the generated images
  602     14.2. Chroot
  603 
  604 Chapter 6. Buildroot configuration
  605 
  606 All the configuration options in make *config have a help text
  607 providing details about the option.
  608 
  609 The make *config commands also offer a search tool. Read the help
  610 message in the different frontend menus to know how to use it:
  611 
  612   * in menuconfig, the search tool is called by pressing /;
  613   * in xconfig, the search tool is called by pressing Ctrl + f.
  614 
  615 The result of the search shows the help message of the matching
  616 items. In menuconfig, numbers in the left column provide a shortcut
  617 to the corresponding entry. Just type this number to directly jump to
  618 the entry, or to the containing menu in case the entry is not
  619 selectable due to a missing dependency.
  620 
  621 Although the menu structure and the help text of the entries should
  622 be sufficiently self-explanatory, a number of topics require
  623 additional explanation that cannot easily be covered in the help text
  624 and are therefore covered in the following sections.
  625 
  626 6.1. Cross-compilation toolchain
  627 
  628 A compilation toolchain is the set of tools that allows you to
  629 compile code for your system. It consists of a compiler (in our case,
  630 gcc), binary utils like assembler and linker (in our case, binutils)
  631 and a C standard library (for example GNU Libc [http://www.gnu.org/
  632 software/libc/libc.html], uClibc-ng [http://www.uclibc-ng.org/]).
  633 
  634 The system installed on your development station certainly already
  635 has a compilation toolchain that you can use to compile an
  636 application that runs on your system. If you’re using a PC, your
  637 compilation toolchain runs on an x86 processor and generates code for
  638 an x86 processor. Under most Linux systems, the compilation toolchain
  639 uses the GNU libc (glibc) as the C standard library. This compilation
  640 toolchain is called the "host compilation toolchain". The machine on
  641 which it is running, and on which you’re working, is called the "host
  642 system" ^[3].
  643 
  644 The compilation toolchain is provided by your distribution, and
  645 Buildroot has nothing to do with it (other than using it to build a
  646 cross-compilation toolchain and other tools that are run on the
  647 development host).
  648 
  649 As said above, the compilation toolchain that comes with your system
  650 runs on and generates code for the processor in your host system. As
  651 your embedded system has a different processor, you need a
  652 cross-compilation toolchain - a compilation toolchain that runs on
  653 your host system but generates code for your target system (and
  654 target processor). For example, if your host system uses x86 and your
  655 target system uses ARM, the regular compilation toolchain on your
  656 host runs on x86 and generates code for x86, while the
  657 cross-compilation toolchain runs on x86 and generates code for ARM.
  658 
  659 Buildroot provides two solutions for the cross-compilation toolchain:
  660 
  661   * The internal toolchain backend, called Buildroot toolchain in the
  662     configuration interface.
  663   * The external toolchain backend, called External toolchain in the
  664     configuration interface.
  665 
  666 The choice between these two solutions is done using the Toolchain
  667 Type option in the Toolchain menu. Once one solution has been chosen,
  668 a number of configuration options appear, they are detailed in the
  669 following sections.
  670 
  671 6.1.1. Internal toolchain backend
  672 
  673 The internal toolchain backend is the backend where Buildroot builds
  674 by itself a cross-compilation toolchain, before building the
  675 userspace applications and libraries for your target embedded system.
  676 
  677 This backend supports several C libraries: uClibc-ng [http://
  678 www.uclibc-ng.org], glibc [http://www.gnu.org/software/libc/
  679 libc.html] and musl [http://www.musl-libc.org].
  680 
  681 Once you have selected this backend, a number of options appear. The
  682 most important ones allow to:
  683 
  684   * Change the version of the Linux kernel headers used to build the
  685     toolchain. This item deserves a few explanations. In the process
  686     of building a cross-compilation toolchain, the C library is being
  687     built. This library provides the interface between userspace
  688     applications and the Linux kernel. In order to know how to "talk"
  689     to the Linux kernel, the C library needs to have access to the 
  690     Linux kernel headers (i.e. the .h files from the kernel), which
  691     define the interface between userspace and the kernel (system
  692     calls, data structures, etc.). Since this interface is backward
  693     compatible, the version of the Linux kernel headers used to build
  694     your toolchain do not need to match exactly the version of the
  695     Linux kernel you intend to run on your embedded system. They only
  696     need to have a version equal or older to the version of the Linux
  697     kernel you intend to run. If you use kernel headers that are more
  698     recent than the Linux kernel you run on your embedded system,
  699     then the C library might be using interfaces that are not
  700     provided by your Linux kernel.
  701   * Change the version of the GCC compiler, binutils and the C
  702     library.
  703   * Select a number of toolchain options (uClibc only): whether the
  704     toolchain should have RPC support (used mainly for NFS),
  705     wide-char support, locale support (for internationalization), C++
  706     support or thread support. Depending on which options you choose,
  707     the number of userspace applications and libraries visible in
  708     Buildroot menus will change: many applications and libraries
  709     require certain toolchain options to be enabled. Most packages
  710     show a comment when a certain toolchain option is required to be
  711     able to enable those packages. If needed, you can further refine
  712     the uClibc configuration by running make uclibc-menuconfig. Note
  713     however that all packages in Buildroot are tested against the
  714     default uClibc configuration bundled in Buildroot: if you deviate
  715     from this configuration by removing features from uClibc, some
  716     packages may no longer build.
  717 
  718 It is worth noting that whenever one of those options is modified,
  719 then the entire toolchain and system must be rebuilt. See
  720 Section 8.2, “Understanding when a full rebuild is necessary”.
  721 
  722 Advantages of this backend:
  723 
  724   * Well integrated with Buildroot
  725   * Fast, only builds what’s necessary
  726 
  727 Drawbacks of this backend:
  728 
  729   * Rebuilding the toolchain is needed when doing make clean, which
  730     takes time. If you’re trying to reduce your build time, consider
  731     using the External toolchain backend.
  732 
  733 6.1.2. External toolchain backend
  734 
  735 The external toolchain backend allows to use existing pre-built
  736 cross-compilation toolchains. Buildroot knows about a number of
  737 well-known cross-compilation toolchains (from Linaro [http://
  738 www.linaro.org] for ARM, Sourcery CodeBench [http://www.mentor.com/
  739 embedded-software/sourcery-tools/sourcery-codebench/editions/
  740 lite-edition/] for ARM, x86-64, PowerPC, and MIPS, and is capable of
  741 downloading them automatically, or it can be pointed to a custom
  742 toolchain, either available for download or installed locally.
  743 
  744 Then, you have three solutions to use an external toolchain:
  745 
  746   * Use a predefined external toolchain profile, and let Buildroot
  747     download, extract and install the toolchain. Buildroot already
  748     knows about a few CodeSourcery and Linaro toolchains. Just select
  749     the toolchain profile in Toolchain from the available ones. This
  750     is definitely the easiest solution.
  751   * Use a predefined external toolchain profile, but instead of
  752     having Buildroot download and extract the toolchain, you can tell
  753     Buildroot where your toolchain is already installed on your
  754     system. Just select the toolchain profile in Toolchain through
  755     the available ones, unselect Download toolchain automatically,
  756     and fill the Toolchain path text entry with the path to your
  757     cross-compiling toolchain.
  758   * Use a completely custom external toolchain. This is particularly
  759     useful for toolchains generated using crosstool-NG or with
  760     Buildroot itself. To do this, select the Custom toolchain
  761     solution in the Toolchain list. You need to fill the Toolchain
  762     path, Toolchain prefix and External toolchain C library options.
  763     Then, you have to tell Buildroot what your external toolchain
  764     supports. If your external toolchain uses the glibc library, you
  765     only have to tell whether your toolchain supports C++ or not and
  766     whether it has built-in RPC support. If your external toolchain
  767     uses the uClibc library, then you have to tell Buildroot if it
  768     supports RPC, wide-char, locale, program invocation, threads and
  769     C++. At the beginning of the execution, Buildroot will tell you
  770     if the selected options do not match the toolchain configuration.
  771 
  772 Our external toolchain support has been tested with toolchains from
  773 CodeSourcery and Linaro, toolchains generated by crosstool-NG [http:/
  774 /crosstool-ng.org], and toolchains generated by Buildroot itself. In
  775 general, all toolchains that support the sysroot feature should work.
  776 If not, do not hesitate to contact the developers.
  777 
  778 We do not support toolchains or SDK generated by OpenEmbedded or
  779 Yocto, because these toolchains are not pure toolchains (i.e. just
  780 the compiler, binutils, the C and C++ libraries). Instead these
  781 toolchains come with a very large set of pre-compiled libraries and
  782 programs. Therefore, Buildroot cannot import the sysroot of the
  783 toolchain, as it would contain hundreds of megabytes of pre-compiled
  784 libraries that are normally built by Buildroot.
  785 
  786 We also do not support using the distribution toolchain (i.e. the gcc
  787 /binutils/C library installed by your distribution) as the toolchain
  788 to build software for the target. This is because your distribution
  789 toolchain is not a "pure" toolchain (i.e. only with the C/C++
  790 library), so we cannot import it properly into the Buildroot build
  791 environment. So even if you are building a system for a x86 or x86_64
  792 target, you have to generate a cross-compilation toolchain with
  793 Buildroot or crosstool-NG.
  794 
  795 If you want to generate a custom toolchain for your project, that can
  796 be used as an external toolchain in Buildroot, our recommendation is
  797 to build it either with Buildroot itself (see Section 6.1.3, “Build
  798 an external toolchain with Buildroot”) or with crosstool-NG [http://
  799 crosstool-ng.org].
  800 
  801 Advantages of this backend:
  802 
  803   * Allows to use well-known and well-tested cross-compilation
  804     toolchains.
  805   * Avoids the build time of the cross-compilation toolchain, which
  806     is often very significant in the overall build time of an
  807     embedded Linux system.
  808 
  809 Drawbacks of this backend:
  810 
  811   * If your pre-built external toolchain has a bug, may be hard to
  812     get a fix from the toolchain vendor, unless you build your
  813     external toolchain by yourself using Buildroot or Crosstool-NG.
  814 
  815 6.1.3. Build an external toolchain with Buildroot
  816 
  817 The Buildroot internal toolchain option can be used to create an
  818 external toolchain. Here are a series of steps to build an internal
  819 toolchain and package it up for reuse by Buildroot itself (or other
  820 projects).
  821 
  822 Create a new Buildroot configuration, with the following details:
  823 
  824   * Select the appropriate Target options for your target CPU
  825     architecture
  826   * In the Toolchain menu, keep the default of Buildroot toolchain
  827     for Toolchain type, and configure your toolchain as desired
  828   * In the System configuration menu, select None as the Init system
  829     and none as /bin/sh
  830   * In the Target packages menu, disable BusyBox
  831   * In the Filesystem images menu, disable tar the root filesystem
  832 
  833 Then, we can trigger the build, and also ask Buildroot to generate a
  834 SDK. This will conveniently generate for us a tarball which contains
  835 our toolchain:
  836 
  837 make sdk
  838 
  839 This produces the SDK tarball in $(O)/images, with a name similar to
  840 arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz. Save this
  841 tarball, as it is now the toolchain that you can re-use as an
  842 external toolchain in other Buildroot projects.
  843 
  844 In those other Buildroot projects, in the Toolchain menu:
  845 
  846   * Set Toolchain type to External toolchain
  847   * Set Toolchain to Custom toolchain
  848   * Set Toolchain origin to Toolchain to be downloaded and installed
  849   * Set Toolchain URL to file:///path/to/your/sdk/tarball.tar.gz
  850 
  851 6.1.3.1. External toolchain wrapper
  852 
  853 When using an external toolchain, Buildroot generates a wrapper
  854 program, that transparently passes the appropriate options (according
  855 to the configuration) to the external toolchain programs. In case you
  856 need to debug this wrapper to check exactly what arguments are
  857 passed, you can set the environment variable BR2_DEBUG_WRAPPER to
  858 either one of:
  859 
  860   * 0, empty or not set: no debug
  861   * 1: trace all arguments on a single line
  862   * 2: trace one argument per line
  863 
  864 6.2. /dev management
  865 
  866 On a Linux system, the /dev directory contains special files, called 
  867 device files, that allow userspace applications to access the
  868 hardware devices managed by the Linux kernel. Without these device
  869 files, your userspace applications would not be able to use the
  870 hardware devices, even if they are properly recognized by the Linux
  871 kernel.
  872 
  873 Under System configuration, /dev management, Buildroot offers four
  874 different solutions to handle the /dev directory :
  875 
  876   * The first solution is Static using device table. This is the old
  877     classical way of handling device files in Linux. With this
  878     method, the device files are persistently stored in the root
  879     filesystem (i.e. they persist across reboots), and there is
  880     nothing that will automatically create and remove those device
  881     files when hardware devices are added or removed from the system.
  882     Buildroot therefore creates a standard set of device files using
  883     a device table, the default one being stored in system/
  884     device_table_dev.txt in the Buildroot source code. This file is
  885     processed when Buildroot generates the final root filesystem
  886     image, and the device files are therefore not visible in the
  887     output/target directory. The BR2_ROOTFS_STATIC_DEVICE_TABLE
  888     option allows to change the default device table used by
  889     Buildroot, or to add an additional device table, so that
  890     additional device files are created by Buildroot during the
  891     build. So, if you use this method, and a device file is missing
  892     in your system, you can for example create a board/<yourcompany>/
  893     <yourproject>/device_table_dev.txt file that contains the
  894     description of your additional device files, and then you can set
  895     BR2_ROOTFS_STATIC_DEVICE_TABLE to system/device_table_dev.txt
  896     board/<yourcompany>/<yourproject>/device_table_dev.txt. For more
  897     details about the format of the device table file, see
  898     Chapter 25, Makedev syntax documentation.
  899   * The second solution is Dynamic using devtmpfs only. devtmpfs is a
  900     virtual filesystem inside the Linux kernel that has been
  901     introduced in kernel 2.6.32 (if you use an older kernel, it is
  902     not possible to use this option). When mounted in /dev, this
  903     virtual filesystem will automatically make device files appear
  904     and disappear as hardware devices are added and removed from the
  905     system. This filesystem is not persistent across reboots: it is
  906     filled dynamically by the kernel. Using devtmpfs requires the
  907     following kernel configuration options to be enabled:
  908     CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT. When Buildroot is in
  909     charge of building the Linux kernel for your embedded device, it
  910     makes sure that those two options are enabled. However, if you
  911     build your Linux kernel outside of Buildroot, then it is your
  912     responsibility to enable those two options (if you fail to do so,
  913     your Buildroot system will not boot).
  914   * The third solution is Dynamic using devtmpfs + mdev. This method
  915     also relies on the devtmpfs virtual filesystem detailed above (so
  916     the requirement to have CONFIG_DEVTMPFS and CONFIG_DEVTMPFS_MOUNT
  917     enabled in the kernel configuration still apply), but adds the
  918     mdev userspace utility on top of it. mdev is a program part of
  919     BusyBox that the kernel will call every time a device is added or
  920     removed. Thanks to the /etc/mdev.conf configuration file, mdev
  921     can be configured to for example, set specific permissions or
  922     ownership on a device file, call a script or application whenever
  923     a device appears or disappear, etc. Basically, it allows 
  924     userspace to react on device addition and removal events. mdev
  925     can for example be used to automatically load kernel modules when
  926     devices appear on the system. mdev is also important if you have
  927     devices that require a firmware, as it will be responsible for
  928     pushing the firmware contents to the kernel. mdev is a
  929     lightweight implementation (with fewer features) of udev. For
  930     more details about mdev and the syntax of its configuration file,
  931     see http://git.busybox.net/busybox/tree/docs/mdev.txt.
  932   * The fourth solution is Dynamic using devtmpfs + eudev. This
  933     method also relies on the devtmpfs virtual filesystem detailed
  934     above, but adds the eudev userspace daemon on top of it. eudev is
  935     a daemon that runs in the background, and gets called by the
  936     kernel when a device gets added or removed from the system. It is
  937     a more heavyweight solution than mdev, but provides higher
  938     flexibility. eudev is a standalone version of udev, the original
  939     userspace daemon used in most desktop Linux distributions, which
  940     is now part of Systemd. For more details, see http://
  941     en.wikipedia.org/wiki/Udev.
  942 
  943 The Buildroot developers recommendation is to start with the Dynamic
  944 using devtmpfs only solution, until you have the need for userspace
  945 to be notified when devices are added/removed, or if firmwares are
  946 needed, in which case Dynamic using devtmpfs + mdev is usually a good
  947 solution.
  948 
  949 Note that if systemd is chosen as init system, /dev management will
  950 be performed by the udev program provided by systemd.
  951 
  952 6.3. init system
  953 
  954 The init program is the first userspace program started by the kernel
  955 (it carries the PID number 1), and is responsible for starting the
  956 userspace services and programs (for example: web server, graphical
  957 applications, other network servers, etc.).
  958 
  959 Buildroot allows to use three different types of init systems, which
  960 can be chosen from System configuration, Init system:
  961 
  962   * The first solution is BusyBox. Amongst many programs, BusyBox has
  963     an implementation of a basic init program, which is sufficient
  964     for most embedded systems. Enabling the BR2_INIT_BUSYBOX will
  965     ensure BusyBox will build and install its init program. This is
  966     the default solution in Buildroot. The BusyBox init program will
  967     read the /etc/inittab file at boot to know what to do. The syntax
  968     of this file can be found in http://git.busybox.net/busybox/tree/
  969     examples/inittab (note that BusyBox inittab syntax is special: do
  970     not use a random inittab documentation from the Internet to learn
  971     about BusyBox inittab). The default inittab in Buildroot is
  972     stored in system/skeleton/etc/inittab. Apart from mounting a few
  973     important filesystems, the main job the default inittab does is
  974     to start the /etc/init.d/rcS shell script, and start a getty
  975     program (which provides a login prompt).
  976   * The second solution is systemV. This solution uses the old
  977     traditional sysvinit program, packed in Buildroot in package/
  978     sysvinit. This was the solution used in most desktop Linux
  979     distributions, until they switched to more recent alternatives
  980     such as Upstart or Systemd. sysvinit also works with an inittab
  981     file (which has a slightly different syntax than the one from
  982     BusyBox). The default inittab installed with this init solution
  983     is located in package/sysvinit/inittab.
  984   * The third solution is systemd. systemd is the new generation init
  985     system for Linux. It does far more than traditional init
  986     programs: aggressive parallelization capabilities, uses socket
  987     and D-Bus activation for starting services, offers on-demand
  988     starting of daemons, keeps track of processes using Linux control
  989     groups, supports snapshotting and restoring of the system state,
  990     etc. systemd will be useful on relatively complex embedded
  991     systems, for example the ones requiring D-Bus and services
  992     communicating between each other. It is worth noting that systemd
  993     brings a fairly big number of large dependencies: dbus, udev and
  994     more. For more details about systemd, see http://
  995     www.freedesktop.org/wiki/Software/systemd.
  996 
  997 The solution recommended by Buildroot developers is to use the 
  998 BusyBox init as it is sufficient for most embedded systems. systemd
  999 can be used for more complex situations.
 1000 
 1001 
 1002 ---------------------------------------------------------------------
 1003 
 1004 ^[3] This terminology differs from what is used by GNU configure,
 1005 where the host is the machine on which the application will run
 1006 (which is usually the same as target)
 1007 
 1008 Chapter 7. Configuration of other components
 1009 
 1010 Before attempting to modify any of the components below, make sure
 1011 you have already configured Buildroot itself, and have enabled the
 1012 corresponding package.
 1013 
 1014 BusyBox
 1015 
 1016     If you already have a BusyBox configuration file, you can
 1017     directly specify this file in the Buildroot configuration, using
 1018     BR2_PACKAGE_BUSYBOX_CONFIG. Otherwise, Buildroot will start from
 1019     a default BusyBox configuration file.
 1020 
 1021     To make subsequent changes to the configuration, use make
 1022     busybox-menuconfig to open the BusyBox configuration editor.
 1023 
 1024     It is also possible to specify a BusyBox configuration file
 1025     through an environment variable, although this is not
 1026     recommended. Refer to Section 8.6, “Environment variables” for
 1027     more details.
 1028 
 1029 uClibc
 1030     Configuration of uClibc is done in the same way as for BusyBox.
 1031     The configuration variable to specify an existing configuration
 1032     file is BR2_UCLIBC_CONFIG. The command to make subsequent changes
 1033     is make uclibc-menuconfig.
 1034 Linux kernel
 1035 
 1036     If you already have a kernel configuration file, you can directly
 1037     specify this file in the Buildroot configuration, using
 1038     BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
 1039 
 1040     If you do not yet have a kernel configuration file, you can
 1041     either start by specifying a defconfig in the Buildroot
 1042     configuration, using BR2_LINUX_KERNEL_USE_DEFCONFIG, or start by
 1043     creating an empty file and specifying it as custom configuration
 1044     file, using BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG.
 1045 
 1046     To make subsequent changes to the configuration, use make
 1047     linux-menuconfig to open the Linux configuration editor.
 1048 
 1049 Barebox
 1050     Configuration of Barebox is done in the same way as for the Linux
 1051     kernel. The corresponding configuration variables are
 1052     BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG and
 1053     BR2_TARGET_BAREBOX_USE_DEFCONFIG. To open the configuration
 1054     editor, use make barebox-menuconfig.
 1055 U-Boot
 1056     Configuration of U-Boot (version 2015.04 or newer) is done in the
 1057     same way as for the Linux kernel. The corresponding configuration
 1058     variables are BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG and
 1059     BR2_TARGET_UBOOT_USE_DEFCONFIG. To open the configuration editor,
 1060     use make uboot-menuconfig.
 1061 
 1062 Chapter 8. General Buildroot usage
 1063 
 1064 8.1. make tips
 1065 
 1066 This is a collection of tips that help you make the most of
 1067 Buildroot.
 1068 
 1069 Display all commands executed by make: 
 1070 
 1071  $ make V=1 <target>
 1072 
 1073 Display the list of boards with a defconfig: 
 1074 
 1075  $ make list-defconfigs
 1076 
 1077 Display all available targets: 
 1078 
 1079  $ make help
 1080 
 1081 Not all targets are always available, some settings in the .config
 1082 file may hide some targets:
 1083 
 1084   * busybox-menuconfig only works when busybox is enabled;
 1085   * linux-menuconfig and linux-savedefconfig only work when linux is
 1086     enabled;
 1087   * uclibc-menuconfig is only available when the uClibc C library is
 1088     selected in the internal toolchain backend;
 1089   * barebox-menuconfig and barebox-savedefconfig only work when the
 1090     barebox bootloader is enabled.
 1091   * uboot-menuconfig and uboot-savedefconfig only work when the
 1092     U-Boot bootloader is enabled.
 1093 
 1094 Cleaning: Explicit cleaning is required when any of the architecture
 1095 or toolchain configuration options are changed.
 1096 
 1097 To delete all build products (including build directories, host,
 1098 staging and target trees, the images and the toolchain):
 1099 
 1100  $ make clean
 1101 
 1102 Generating the manual: The present manual sources are located in the 
 1103 docs/manual directory. To generate the manual:
 1104 
 1105  $ make manual-clean
 1106  $ make manual
 1107 
 1108 The manual outputs will be generated in output/docs/manual.
 1109 
 1110 Notes
 1111 
 1112   * A few tools are required to build the documentation (see:
 1113     Section 2.2, “Optional packages”).
 1114 
 1115 Resetting Buildroot for a new target: To delete all build products as
 1116 well as the configuration:
 1117 
 1118  $ make distclean
 1119 
 1120 Notes. If ccache is enabled, running make clean or distclean does not
 1121 empty the compiler cache used by Buildroot. To delete it, refer to
 1122 Section 8.14.3, “Using ccache in Buildroot”.
 1123 
 1124 Dumping the internal make variables: One can dump the variables known
 1125 to make, along with their values:
 1126 
 1127  $ make -s printvars VARS='VARIABLE1 VARIABLE2'
 1128  VARIABLE1=value_of_variable
 1129  VARIABLE2=value_of_variable
 1130 
 1131 It is possible to tweak the output using some variables:
 1132 
 1133   * VARS will limit the listing to variables which names match the
 1134     specified make-patterns - this must be set else nothing is
 1135     printed
 1136   * QUOTED_VARS, if set to YES, will single-quote the value
 1137   * RAW_VARS, if set to YES, will print the unexpanded value
 1138 
 1139 For example:
 1140 
 1141  $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
 1142  BUSYBOX_DEPENDENCIES=skeleton toolchain
 1143  BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
 1144  BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
 1145  BUSYBOX_FINAL_PATCH_DEPENDENCIES=
 1146  BUSYBOX_RDEPENDENCIES=ncurses util-linux
 1147 
 1148  $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
 1149  BUSYBOX_DEPENDENCIES='skeleton toolchain'
 1150  BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
 1151  BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
 1152  BUSYBOX_FINAL_PATCH_DEPENDENCIES=''
 1153  BUSYBOX_RDEPENDENCIES='ncurses util-linux'
 1154 
 1155  $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
 1156  BUSYBOX_DEPENDENCIES=skeleton toolchain
 1157  BUSYBOX_FINAL_ALL_DEPENDENCIES=$(sort $(BUSYBOX_FINAL_DEPENDENCIES) $(BUSYBOX_FINAL_PATCH_DEPENDENCIES))
 1158  BUSYBOX_FINAL_DEPENDENCIES=$(sort $(BUSYBOX_DEPENDENCIES))
 1159  BUSYBOX_FINAL_PATCH_DEPENDENCIES=$(sort $(BUSYBOX_PATCH_DEPENDENCIES))
 1160  BUSYBOX_RDEPENDENCIES=ncurses util-linux
 1161 
 1162 The output of quoted variables can be reused in shell scripts, for
 1163 example:
 1164 
 1165  $ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
 1166  $ echo $BUSYBOX_DEPENDENCIES
 1167  skeleton toolchain
 1168 
 1169 8.2. Understanding when a full rebuild is necessary
 1170 
 1171 Buildroot does not attempt to detect what parts of the system should
 1172 be rebuilt when the system configuration is changed through make
 1173 menuconfig, make xconfig or one of the other configuration tools. In
 1174 some cases, Buildroot should rebuild the entire system, in some
 1175 cases, only a specific subset of packages. But detecting this in a
 1176 completely reliable manner is very difficult, and therefore the
 1177 Buildroot developers have decided to simply not attempt to do this.
 1178 
 1179 Instead, it is the responsibility of the user to know when a full
 1180 rebuild is necessary. As a hint, here are a few rules of thumb that
 1181 can help you understand how to work with Buildroot:
 1182 
 1183   * When the target architecture configuration is changed, a complete
 1184     rebuild is needed. Changing the architecture variant, the binary
 1185     format or the floating point strategy for example has an impact
 1186     on the entire system.
 1187   * When the toolchain configuration is changed, a complete rebuild
 1188     generally is needed. Changing the toolchain configuration often
 1189     involves changing the compiler version, the type of C library or
 1190     its configuration, or some other fundamental configuration item,
 1191     and these changes have an impact on the entire system.
 1192   * When an additional package is added to the configuration, a full
 1193     rebuild is not necessarily needed. Buildroot will detect that
 1194     this package has never been built, and will build it. However, if
 1195     this package is a library that can optionally be used by packages
 1196     that have already been built, Buildroot will not automatically
 1197     rebuild those. Either you know which packages should be rebuilt,
 1198     and you can rebuild them manually, or you should do a full
 1199     rebuild. For example, let’s suppose you have built a system with
 1200     the ctorrent package, but without openssl. Your system works, but
 1201     you realize you would like to have SSL support in ctorrent, so
 1202     you enable the openssl package in Buildroot configuration and
 1203     restart the build. Buildroot will detect that openssl should be
 1204     built and will be build it, but it will not detect that ctorrent
 1205     should be rebuilt to benefit from openssl to add OpenSSL support.
 1206     You will either have to do a full rebuild, or rebuild ctorrent
 1207     itself.
 1208   * When a package is removed from the configuration, Buildroot does
 1209     not do anything special. It does not remove the files installed
 1210     by this package from the target root filesystem or from the
 1211     toolchain sysroot. A full rebuild is needed to get rid of this
 1212     package. However, generally you don’t necessarily need this
 1213     package to be removed right now: you can wait for the next lunch
 1214     break to restart the build from scratch.
 1215   * When the sub-options of a package are changed, the package is not
 1216     automatically rebuilt. After making such changes, rebuilding only
 1217     this package is often sufficient, unless enabling the package
 1218     sub-option adds some features to the package that are useful for
 1219     another package which has already been built. Again, Buildroot
 1220     does not track when a package should be rebuilt: once a package
 1221     has been built, it is never rebuilt unless explicitly told to do
 1222     so.
 1223   * When a change to the root filesystem skeleton is made, a full
 1224     rebuild is needed. However, when changes to the root filesystem
 1225     overlay, a post-build script or a post-image script are made,
 1226     there is no need for a full rebuild: a simple make invocation
 1227     will take the changes into account.
 1228   * When a package listed in FOO_DEPENDENCIES is rebuilt or removed,
 1229     the package foo is not automatically rebuilt. For example, if a
 1230     package bar is listed in FOO_DEPENDENCIES with FOO_DEPENDENCIES =
 1231     bar and the configuration of the bar package is changed, the
 1232     configuration change would not result in a rebuild of package foo
 1233     automatically. In this scenario, you may need to either rebuild
 1234     any packages in your build which reference bar in their
 1235     DEPENDENCIES, or perform a full rebuild to ensure any bar
 1236     dependent packages are up to date.
 1237 
 1238 Generally speaking, when you’re facing a build error and you’re
 1239 unsure of the potential consequences of the configuration changes
 1240 you’ve made, do a full rebuild. If you get the same build error, then
 1241 you are sure that the error is not related to partial rebuilds of
 1242 packages, and if this error occurs with packages from the official
 1243 Buildroot, do not hesitate to report the problem! As your experience
 1244 with Buildroot progresses, you will progressively learn when a full
 1245 rebuild is really necessary, and you will save more and more time.
 1246 
 1247 For reference, a full rebuild is achieved by running:
 1248 
 1249 $ make clean all
 1250 
 1251 8.3. Understanding how to rebuild packages
 1252 
 1253 One of the most common questions asked by Buildroot users is how to
 1254 rebuild a given package or how to remove a package without rebuilding
 1255 everything from scratch.
 1256 
 1257 Removing a package is unsupported by Buildroot without rebuilding
 1258 from scratch. This is because Buildroot doesn’t keep track of which
 1259 package installs what files in the output/staging and output/target
 1260 directories, or which package would be compiled differently depending
 1261 on the availability of another package.
 1262 
 1263 The easiest way to rebuild a single package from scratch is to remove
 1264 its build directory in output/build. Buildroot will then re-extract,
 1265 re-configure, re-compile and re-install this package from scratch.
 1266 You can ask buildroot to do this with the make <package>-dirclean
 1267 command.
 1268 
 1269 On the other hand, if you only want to restart the build process of a
 1270 package from its compilation step, you can run make <package>
 1271 -rebuild. It will restart the compilation and installation of the
 1272 package, but not from scratch: it basically re-executes make and make
 1273 install inside the package, so it will only rebuild files that
 1274 changed.
 1275 
 1276 If you want to restart the build process of a package from its
 1277 configuration step, you can run make <package>-reconfigure. It will
 1278 restart the configuration, compilation and installation of the
 1279 package.
 1280 
 1281 While <package>-rebuild implies <package>-reinstall and <package>
 1282 -reconfigure implies <package>-rebuild, these targets as well as
 1283 <package> only act on the said package, and do not trigger
 1284 re-creating the root filesystem image. If re-creating the root
 1285 filesystem in necessary, one should in addition run make or make all.
 1286 
 1287 Internally, Buildroot creates so-called stamp files to keep track of
 1288 which build steps have been completed for each package. They are
 1289 stored in the package build directory, output/build/<package>-
 1290 <version>/ and are named .stamp_<step-name>. The commands detailed
 1291 above simply manipulate these stamp files to force Buildroot to
 1292 restart a specific set of steps of a package build process.
 1293 
 1294 Further details about package special make targets are explained in
 1295 Section 8.14.5, “Package-specific make targets”.
 1296 
 1297 8.4. Offline builds
 1298 
 1299 If you intend to do an offline build and just want to download all
 1300 sources that you previously selected in the configurator (menuconfig,
 1301 nconfig, xconfig or gconfig), then issue:
 1302 
 1303  $ make source
 1304 
 1305 You can now disconnect or copy the content of your dl directory to
 1306 the build-host.
 1307 
 1308 8.5. Building out-of-tree
 1309 
 1310 As default, everything built by Buildroot is stored in the directory
 1311 output in the Buildroot tree.
 1312 
 1313 Buildroot also supports building out of tree with a syntax similar to
 1314 the Linux kernel. To use it, add O=<directory> to the make command
 1315 line:
 1316 
 1317  $ make O=/tmp/build
 1318 
 1319 Or:
 1320 
 1321  $ cd /tmp/build; make O=$PWD -C path/to/buildroot
 1322 
 1323 All the output files will be located under /tmp/build. If the O path
 1324 does not exist, Buildroot will create it.
 1325 
 1326 Note: the O path can be either an absolute or a relative path, but if
 1327 it’s passed as a relative path, it is important to note that it is
 1328 interpreted relative to the main Buildroot source directory, not the
 1329 current working directory.
 1330 
 1331 When using out-of-tree builds, the Buildroot .config and temporary
 1332 files are also stored in the output directory. This means that you
 1333 can safely run multiple builds in parallel using the same source tree
 1334 as long as they use unique output directories.
 1335 
 1336 For ease of use, Buildroot generates a Makefile wrapper in the output
 1337 directory - so after the first run, you no longer need to pass O=<…>
 1338 and -C <…>, simply run (in the output directory):
 1339 
 1340  $ make <target>
 1341 
 1342 8.6. Environment variables
 1343 
 1344 Buildroot also honors some environment variables, when they are
 1345 passed to make or set in the environment:
 1346 
 1347   * HOSTCXX, the host C++ compiler to use
 1348   * HOSTCC, the host C compiler to use
 1349   * UCLIBC_CONFIG_FILE=<path/to/.config>, path to the uClibc
 1350     configuration file, used to compile uClibc, if an internal
 1351     toolchain is being built. Note that the uClibc configuration file
 1352     can also be set from the configuration interface, so through the
 1353     Buildroot .config file; this is the recommended way of setting
 1354     it.
 1355   * BUSYBOX_CONFIG_FILE=<path/to/.config>, path to the BusyBox
 1356     configuration file. Note that the BusyBox configuration file can
 1357     also be set from the configuration interface, so through the
 1358     Buildroot .config file; this is the recommended way of setting
 1359     it.
 1360   * BR2_CCACHE_DIR to override the directory where Buildroot stores
 1361     the cached files when using ccache.
 1362   * BR2_DL_DIR to override the directory in which Buildroot stores/
 1363     retrieves downloaded files. Note that the Buildroot download
 1364     directory can also be set from the configuration interface, so
 1365     through the Buildroot .config file. See Section 8.14.4, “Location
 1366     of downloaded packages” for more details on how you can set the
 1367     download directory.
 1368   * BR2_GRAPH_ALT, if set and non-empty, to use an alternate
 1369     color-scheme in build-time graphs
 1370   * BR2_GRAPH_OUT to set the filetype of generated graphs, either pdf
 1371     (the default), or png.
 1372   * BR2_GRAPH_DEPS_OPTS to pass extra options to the dependency
 1373     graph; see Section 8.9, “Graphing the dependencies between
 1374     packages” for the accepted options
 1375   * BR2_GRAPH_DOT_OPTS is passed verbatim as options to the dot
 1376     utility to draw the dependency graph.
 1377   * BR2_GRAPH_SIZE_OPTS to pass extra options to the size graph; see
 1378     Section 8.11, “Graphing the filesystem size contribution of
 1379     packages” for the acepted options
 1380 
 1381 An example that uses config files located in the toplevel directory
 1382 and in your $HOME:
 1383 
 1384  $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config
 1385 
 1386 If you want to use a compiler other than the default gcc or g++ for
 1387 building helper-binaries on your host, then do
 1388 
 1389  $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
 1390 
 1391 8.7. Dealing efficiently with filesystem images
 1392 
 1393 Filesystem images can get pretty big, depending on the filesystem you
 1394 choose, the number of packages, whether you provisioned free space…
 1395 Yet, some locations in the filesystems images may just be empty (e.g.
 1396 a long run of zeroes); such a file is called a sparse file.
 1397 
 1398 Most tools can handle sparse files efficiently, and will only store
 1399 or write those parts of a sparse file that are not empty.
 1400 
 1401 For example:
 1402 
 1403   * tar accepts the -S option to tell it to only store non-zero
 1404     blocks of sparse files:
 1405 
 1406       + tar cf archive.tar -S [files…] will efficiently store sparse
 1407         files in a tarball
 1408       + tar xf archive.tar -S will efficiently store sparse files
 1409         extracted from a tarball
 1410   * cp accepts the --sparse=WHEN option (WHEN is one of auto, never
 1411     or always):
 1412 
 1413       + cp --sparse=always source.file dest.file will make dest.file
 1414         a sparse file if source.file has long runs of zeroes
 1415 
 1416 Other tools may have similar options. Please consult their respective
 1417 man pages.
 1418 
 1419 You can use sparse files if you need to store the filesystem images
 1420 (e.g. to transfer from one machine to another), or if you need to
 1421 send them (e.g. to the Q&A team).
 1422 
 1423 Note however that flashing a filesystem image to a device while using
 1424 the sparse mode of dd may result in a broken filesystem (e.g. the
 1425 block bitmap of an ext2 filesystem may be corrupted; or, if you have
 1426 sparse files in your filesystem, those parts may not be all-zeroes
 1427 when read back). You should only use sparse files when handling files
 1428 on the build machine, not when transferring them to an actual device
 1429 that will be used on the target.
 1430 
 1431 8.8. Details about packages
 1432 
 1433 Buildroot can produce a JSON blurb that describes the set of enabled
 1434 packages in the current configuration, together with their
 1435 dependencies, licenses and other metadata. This JSON blurb is
 1436 produced by using the show-info make target:
 1437 
 1438 make show-info
 1439 
 1440 Buildroot can also produce details about packages as HTML and JSON
 1441 output using the pkg-stats make target. Amongst other things, these
 1442 details include whether known CVEs (security vulnerabilities) affect
 1443 the packages in your current configuration. It also shows if there is
 1444 a newer upstream version for those packages.
 1445 
 1446 make pkg-stats
 1447 
 1448 8.9. Graphing the dependencies between packages
 1449 
 1450 One of Buildroot’s jobs is to know the dependencies between packages,
 1451 and make sure they are built in the right order. These dependencies
 1452 can sometimes be quite complicated, and for a given system, it is
 1453 often not easy to understand why such or such package was brought
 1454 into the build by Buildroot.
 1455 
 1456 In order to help understanding the dependencies, and therefore better
 1457 understand what is the role of the different components in your
 1458 embedded Linux system, Buildroot is capable of generating dependency
 1459 graphs.
 1460 
 1461 To generate a dependency graph of the full system you have compiled,
 1462 simply run:
 1463 
 1464 make graph-depends
 1465 
 1466 You will find the generated graph in output/graphs/graph-depends.pdf.
 1467 
 1468 If your system is quite large, the dependency graph may be too
 1469 complex and difficult to read. It is therefore possible to generate
 1470 the dependency graph just for a given package:
 1471 
 1472 make <pkg>-graph-depends
 1473 
 1474 You will find the generated graph in output/graph/<pkg>
 1475 -graph-depends.pdf.
 1476 
 1477 Note that the dependency graphs are generated using the dot tool from
 1478 the Graphviz project, which you must have installed on your system to
 1479 use this feature. In most distributions, it is available as the
 1480 graphviz package.
 1481 
 1482 By default, the dependency graphs are generated in the PDF format.
 1483 However, by passing the BR2_GRAPH_OUT environment variable, you can
 1484 switch to other output formats, such as PNG, PostScript or SVG. All
 1485 formats supported by the -T option of the dot tool are supported.
 1486 
 1487 BR2_GRAPH_OUT=svg make graph-depends
 1488 
 1489 The graph-depends behaviour can be controlled by setting options in
 1490 the BR2_GRAPH_DEPS_OPTS environment variable. The accepted options
 1491 are:
 1492 
 1493   * --depth N, -d N, to limit the dependency depth to N levels. The
 1494     default, 0, means no limit.
 1495   * --stop-on PKG, -s PKG, to stop the graph on the package PKG. PKG
 1496     can be an actual package name, a glob, the keyword virtual (to
 1497     stop on virtual packages), or the keyword host (to stop on host
 1498     packages). The package is still present on the graph, but its
 1499     dependencies are not.
 1500   * --exclude PKG, -x PKG, like --stop-on, but also omits PKG from
 1501     the graph.
 1502   * --transitive, --no-transitive, to draw (or not) the transitive
 1503     dependencies. The default is to not draw transitive dependencies.
 1504   * --colors R,T,H, the comma-separated list of colors to draw the
 1505     root package (R), the target packages (T) and the host packages
 1506     (H). Defaults to: lightblue,grey,gainsboro
 1507 
 1508 BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends
 1509 
 1510 8.10. Graphing the build duration
 1511 
 1512 When the build of a system takes a long time, it is sometimes useful
 1513 to be able to understand which packages are the longest to build, to
 1514 see if anything can be done to speed up the build. In order to help
 1515 such build time analysis, Buildroot collects the build time of each
 1516 step of each package, and allows to generate graphs from this data.
 1517 
 1518 To generate the build time graph after a build, run:
 1519 
 1520 make graph-build
 1521 
 1522 This will generate a set of files in output/graphs :
 1523 
 1524   * build.hist-build.pdf, a histogram of the build time for each
 1525     package, ordered in the build order.
 1526   * build.hist-duration.pdf, a histogram of the build time for each
 1527     package, ordered by duration (longest first)
 1528   * build.hist-name.pdf, a histogram of the build time for each
 1529     package, order by package name.
 1530   * build.pie-packages.pdf, a pie chart of the build time per package
 1531   * build.pie-steps.pdf, a pie chart of the global time spent in each
 1532     step of the packages build process.
 1533 
 1534 This graph-build target requires the Python Matplotlib and Numpy
 1535 libraries to be installed (python-matplotlib and python-numpy on most
 1536 distributions), and also the argparse module if you’re using a Python
 1537 version older than 2.7 (python-argparse on most distributions).
 1538 
 1539 By default, the output format for the graph is PDF, but a different
 1540 format can be selected using the BR2_GRAPH_OUT environment variable.
 1541 The only other format supported is PNG:
 1542 
 1543 BR2_GRAPH_OUT=png make graph-build
 1544 
 1545 8.11. Graphing the filesystem size contribution of packages
 1546 
 1547 When your target system grows, it is sometimes useful to understand
 1548 how much each Buildroot package is contributing to the overall root
 1549 filesystem size. To help with such an analysis, Buildroot collects
 1550 data about files installed by each package and using this data,
 1551 generates a graph and CSV files detailing the size contribution of
 1552 the different packages.
 1553 
 1554 To generate these data after a build, run:
 1555 
 1556 make graph-size
 1557 
 1558 This will generate:
 1559 
 1560   * output/graphs/graph-size.pdf, a pie chart of the contribution of
 1561     each package to the overall root filesystem size
 1562   * output/graphs/package-size-stats.csv, a CSV file giving the size
 1563     contribution of each package to the overall root filesystem size
 1564   * output/graphs/file-size-stats.csv, a CSV file giving the size
 1565     contribution of each installed file to the package it belongs,
 1566     and to the overall filesystem size.
 1567 
 1568 This graph-size target requires the Python Matplotlib library to be
 1569 installed (python-matplotlib on most distributions), and also the
 1570 argparse module if you’re using a Python version older than 2.7
 1571 (python-argparse on most distributions).
 1572 
 1573 Just like for the duration graph, a BR2_GRAPH_OUT environment
 1574 variable is supported to adjust the output file format. See
 1575 Section 8.9, “Graphing the dependencies between packages” for details
 1576 about this environment variable.
 1577 
 1578 Additionally, one may set the environment variable
 1579 BR2_GRAPH_SIZE_OPTS to further control the generated graph. Accepted
 1580 options are:
 1581 
 1582   * --size-limit X, -l X, will group all packages which individual
 1583     contribution is below X percent, to a single entry labelled 
 1584     Others in the graph. By default, X=0.01, which means packages
 1585     each contributing less than 1% are grouped under Others. Accepted
 1586     values are in the range [0.0..1.0].
 1587   * --iec, --binary, --si, --decimal, to use IEC (binary, powers of
 1588     1024) or SI (decimal, powers of 1000; the default) prefixes.
 1589   * --biggest-first, to sort packages in decreasing size order,
 1590     rather than in increasing size order.
 1591 
 1592 Note. The collected filesystem size data is only meaningful after a
 1593 complete clean rebuild. Be sure to run make clean all before using
 1594 make graph-size.
 1595 
 1596 To compare the root filesystem size of two different Buildroot
 1597 compilations, for example after adjusting the configuration or when
 1598 switching to another Buildroot release, use the size-stats-compare
 1599 script. It takes two file-size-stats.csv files (produced by make
 1600 graph-size) as input. Refer to the help text of this script for more
 1601 details:
 1602 
 1603 utils/size-stats-compare -h
 1604 
 1605 8.12. Top-level parallel build
 1606 
 1607 Note. This section deals with a very experimental feature, which is
 1608 known to break even in some non-unusual situations. Use at your own
 1609 risk.
 1610 
 1611 Buildroot has always been capable of using parallel build on a per
 1612 package basis: each package is built by Buildroot using make -jN (or
 1613 the equivalent invocation for non-make-based build systems). The
 1614 level of parallelism is by default number of CPUs + 1, but it can be
 1615 adjusted using the BR2_JLEVEL configuration option.
 1616 
 1617 Until 2020.02, Buildroot was however building packages in a serial
 1618 fashion: each package was built one after the other, without
 1619 parallelization of the build between packages. As of 2020.02,
 1620 Buildroot has experimental support for top-level parallel build,
 1621 which allows some signicant build time savings by building packages
 1622 that have no dependency relationship in parallel. This feature is
 1623 however marked as experimental and is known not to work in some
 1624 cases.
 1625 
 1626 In order to use top-level parallel build, one must:
 1627 
 1628  1. Enable the option BR2_PER_PACKAGE_DIRECTORIES in the Buildroot
 1629     configuration
 1630  2. Use make -jN when starting the Buildroot build
 1631 
 1632 Internally, the BR2_PER_PACKAGE_DIRECTORIES will enable a mechanism
 1633 called per-package directories, which will have the following
 1634 effects:
 1635 
 1636   * Instead of a global target directory and a global host directory
 1637     common to all packages, per-package target and host directories
 1638     will be used, in $(O)/per-package/<pkg>/target/ and $(O)/
 1639     per-package/<pkg>/host/ respectively. Those folders will be
 1640     populated from the corresponding folders of the package
 1641     dependencies at the beginning of <pkg> build. The compiler and
 1642     all other tools will therefore only be able to see and access
 1643     files installed by dependencies explicitly listed by <pkg>.
 1644   * At the end of the build, the global target and host directories
 1645     will be populated, located in $(O)/target and $(O)/host
 1646     respectively. This means that during the build, those folders
 1647     will be empty and it’s only at the very end of the build that
 1648     they will be populated.
 1649 
 1650 8.13. Integration with Eclipse
 1651 
 1652 While a part of the embedded Linux developers like classical text
 1653 editors like Vim or Emacs, and command-line based interfaces, a
 1654 number of other embedded Linux developers like richer graphical
 1655 interfaces to do their development work. Eclipse being one of the
 1656 most popular Integrated Development Environment, Buildroot integrates
 1657 with Eclipse in order to ease the development work of Eclipse users.
 1658 
 1659 Our integration with Eclipse simplifies the compilation, remote
 1660 execution and remote debugging of applications and libraries that are
 1661 built on top of a Buildroot system. It does not integrate the
 1662 Buildroot configuration and build processes themselves with Eclipse.
 1663 Therefore, the typical usage model of our Eclipse integration would
 1664 be:
 1665 
 1666   * Configure your Buildroot system with make menuconfig, make
 1667     xconfig or any other configuration interface provided with
 1668     Buildroot.
 1669   * Build your Buildroot system by running make.
 1670   * Start Eclipse to develop, execute and debug your own custom
 1671     applications and libraries, that will rely on the libraries built
 1672     and installed by Buildroot.
 1673 
 1674 The Buildroot Eclipse integration installation process and usage is
 1675 described in detail at https://github.com/mbats/
 1676 eclipse-buildroot-bundle/wiki.
 1677 
 1678 8.14. Advanced usage
 1679 
 1680 8.14.1. Using the generated toolchain outside Buildroot
 1681 
 1682 You may want to compile, for your target, your own programs or other
 1683 software that are not packaged in Buildroot. In order to do this you
 1684 can use the toolchain that was generated by Buildroot.
 1685 
 1686 The toolchain generated by Buildroot is located by default in output/
 1687 host/. The simplest way to use it is to add output/host/bin/ to your
 1688 PATH environment variable and then to use ARCH-linux-gcc,
 1689 ARCH-linux-objdump, ARCH-linux-ld, etc.
 1690 
 1691 Alternatively, Buildroot can also export the toolchain and the
 1692 development files of all selected packages, as an SDK, by running the
 1693 command make sdk. This generates a tarball of the content of the host
 1694 directory output/host/, named <TARGET-TUPLE>_sdk-buildroot.tar.gz
 1695 (which can be overriden by setting the environment variable
 1696 BR2_SDK_PREFIX) and located in the output directory output/images/.
 1697 
 1698 This tarball can then be distributed to application developers, when
 1699 they want to develop their applications that are not (yet) packaged
 1700 as a Buildroot package.
 1701 
 1702 Upon extracting the SDK tarball, the user must run the script
 1703 relocate-sdk.sh (located at the top directory of the SDK), to make
 1704 sure all paths are updated with the new location.
 1705 
 1706 Alternatively, if you just want to prepare the SDK without generating
 1707 the tarball (e.g. because you will just be moving the host directory,
 1708 or will be generating the tarball on your own), Buildroot also allows
 1709 you to just prepare the SDK with make prepare-sdk without actually
 1710 generating a tarball.
 1711 
 1712 For your convenience, by selecting the option
 1713 BR2_PACKAGE_HOST_ENVIRONMENT_SETUP, you can get a environment-setup
 1714 script installed in output/host/ and therefore in your SDK. This
 1715 script can be sourced with . your/sdk/path/environment-setup to
 1716 export a number of environment variables that will help cross-compile
 1717 your projects using the Buildroot SDK: the PATH will contain the SDK
 1718 binaries, standard autotools variables will be defined with the
 1719 appropriate values, and CONFIGURE_FLAGS will contain basic ./
 1720 configure options to cross-compile autotools projects. It also
 1721 provides some useful commands. Note however that once this script is
 1722 sourced, the environment is setup only for cross-compilation, and no
 1723 longer for native compilation.
 1724 
 1725 8.14.2. Using gdb in Buildroot
 1726 
 1727 Buildroot allows to do cross-debugging, where the debugger runs on
 1728 the build machine and communicates with gdbserver on the target to
 1729 control the execution of the program.
 1730 
 1731 To achieve this:
 1732 
 1733   * If you are using an internal toolchain (built by Buildroot), you
 1734     must enable BR2_PACKAGE_HOST_GDB, BR2_PACKAGE_GDB and
 1735     BR2_PACKAGE_GDB_SERVER. This ensures that both the cross gdb and
 1736     gdbserver get built, and that gdbserver gets installed to your
 1737     target.
 1738   * If you are using an external toolchain, you should enable
 1739     BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY, which will copy the
 1740     gdbserver included with the external toolchain to the target. If
 1741     your external toolchain does not have a cross gdb or gdbserver,
 1742     it is also possible to let Buildroot build them, by enabling the
 1743     same options as for the internal toolchain backend.
 1744 
 1745 Now, to start debugging a program called foo, you should run on the
 1746 target:
 1747 
 1748 gdbserver :2345 foo
 1749 
 1750 This will cause gdbserver to listen on TCP port 2345 for a connection
 1751 from the cross gdb.
 1752 
 1753 Then, on the host, you should start the cross gdb using the following
 1754 command line:
 1755 
 1756 <buildroot>/output/host/bin/<tuple>-gdb -x <buildroot>/output/staging/usr/share/buildroot/gdbinit foo
 1757 
 1758 Of course, foo must be available in the current directory, built with
 1759 debugging symbols. Typically you start this command from the
 1760 directory where foo is built (and not from output/target/ as the
 1761 binaries in that directory are stripped).
 1762 
 1763 The <buildroot>/output/staging/usr/share/buildroot/gdbinit file will
 1764 tell the cross gdb where to find the libraries of the target.
 1765 
 1766 Finally, to connect to the target from the cross gdb:
 1767 
 1768 (gdb) target remote <target ip address>:2345
 1769 
 1770 8.14.3. Using ccache in Buildroot
 1771 
 1772 ccache [http://ccache.samba.org] is a compiler cache. It stores the
 1773 object files resulting from each compilation process, and is able to
 1774 skip future compilation of the same source file (with same compiler
 1775 and same arguments) by using the pre-existing object files. When
 1776 doing almost identical builds from scratch a number of times, it can
 1777 nicely speed up the build process.
 1778 
 1779 ccache support is integrated in Buildroot. You just have to enable
 1780 Enable compiler cache in Build options. This will automatically build
 1781 ccache and use it for every host and target compilation.
 1782 
 1783 The cache is located in $HOME/.buildroot-ccache. It is stored outside
 1784 of Buildroot output directory so that it can be shared by separate
 1785 Buildroot builds. If you want to get rid of the cache, simply remove
 1786 this directory.
 1787 
 1788 You can get statistics on the cache (its size, number of hits,
 1789 misses, etc.) by running make ccache-stats.
 1790 
 1791 The make target ccache-options and the CCACHE_OPTIONS variable
 1792 provide more generic access to the ccache. For example
 1793 
 1794 # set cache limit size
 1795 make CCACHE_OPTIONS="--max-size=5G" ccache-options
 1796 
 1797 # zero statistics counters
 1798 make CCACHE_OPTIONS="--zero-stats" ccache-options
 1799 
 1800 ccache makes a hash of the source files and of the compiler options.
 1801 If a compiler option is different, the cached object file will not be
 1802 used. Many compiler options, however, contain an absolute path to the
 1803 staging directory. Because of this, building in a different output
 1804 directory would lead to many cache misses.
 1805 
 1806 To avoid this issue, buildroot has the Use relative paths option
 1807 (BR2_CCACHE_USE_BASEDIR). This will rewrite all absolute paths that
 1808 point inside the output directory into relative paths. Thus, changing
 1809 the output directory no longer leads to cache misses.
 1810 
 1811 A disadvantage of the relative paths is that they also end up to be
 1812 relative paths in the object file. Therefore, for example, the
 1813 debugger will no longer find the file, unless you cd to the output
 1814 directory first.
 1815 
 1816 See the ccache manual’s section on "Compiling in different
 1817 directories" [https://ccache.samba.org/manual.html#
 1818 _compiling_in_different_directories] for more details about this
 1819 rewriting of absolute paths.
 1820 
 1821 8.14.4. Location of downloaded packages
 1822 
 1823 The various tarballs that are downloaded by Buildroot are all stored
 1824 in BR2_DL_DIR, which by default is the dl directory. If you want to
 1825 keep a complete version of Buildroot which is known to be working
 1826 with the associated tarballs, you can make a copy of this directory.
 1827 This will allow you to regenerate the toolchain and the target
 1828 filesystem with exactly the same versions.
 1829 
 1830 If you maintain several Buildroot trees, it might be better to have a
 1831 shared download location. This can be achieved by pointing the
 1832 BR2_DL_DIR environment variable to a directory. If this is set, then
 1833 the value of BR2_DL_DIR in the Buildroot configuration is overridden.
 1834 The following line should be added to <~/.bashrc>.
 1835 
 1836  export BR2_DL_DIR=<shared download location>
 1837 
 1838 The download location can also be set in the .config file, with the
 1839 BR2_DL_DIR option. Unlike most options in the .config file, this
 1840 value is overridden by the BR2_DL_DIR environment variable.
 1841 
 1842 8.14.5. Package-specific make targets
 1843 
 1844 Running make <package> builds and installs that particular package
 1845 and its dependencies.
 1846 
 1847 For packages relying on the Buildroot infrastructure, there are
 1848 numerous special make targets that can be called independently like
 1849 this:
 1850 
 1851 make <package>-<target>
 1852 
 1853 The package build targets are (in the order they are executed):
 1854 
 1855 +------------------------------------------------------------+
 1856 |command/target |Description                                 |
 1857 |---------------+--------------------------------------------|
 1858 |    source     |Fetch the source (download the tarball,     |
 1859 |               |clone the source repository, etc)           |
 1860 |---------------+--------------------------------------------|
 1861 |    depends    |Build and install all dependencies required |
 1862 |               |to build the package                        |
 1863 |---------------+--------------------------------------------|
 1864 |    extract    |Put the source in the package build         |
 1865 |               |directory (extract the tarball, copy the    |
 1866 |               |source, etc)                                |
 1867 |---------------+--------------------------------------------|
 1868 |     patch     |Apply the patches, if any                   |
 1869 |---------------+--------------------------------------------|
 1870 |   configure   |Run the configure commands, if any          |
 1871 |---------------+--------------------------------------------|
 1872 |     build     |Run the compilation commands                |
 1873 |---------------+--------------------------------------------|
 1874 |install-staging|target package: Run the installation of the |
 1875 |               |package in the staging directory, if        |
 1876 |               |necessary                                   |
 1877 |---------------+--------------------------------------------|
 1878 |install-target |target package: Run the installation of the |
 1879 |               |package in the target directory, if         |
 1880 |               |necessary                                   |
 1881 |---------------+--------------------------------------------|
 1882 |    install    |target package: Run the 2 previous          |
 1883 |               |installation commands                       |
 1884 |               |                                            |
 1885 |               |host package: Run the installation of the   |
 1886 |               |package in the host directory               |
 1887 +------------------------------------------------------------+
 1888 
 1889 Additionally, there are some other useful make targets:
 1890 
 1891 +------------------------------------------------------------+
 1892 |    command/target     |Description                         |
 1893 |-----------------------+------------------------------------|
 1894 |     show-depends      |Displays the first-order            |
 1895 |                       |dependencies required to build the  |
 1896 |                       |package                             |
 1897 |-----------------------+------------------------------------|
 1898 |show-recursive-depends |Recursively displays the            |
 1899 |                       |dependencies required to build the  |
 1900 |                       |package                             |
 1901 |-----------------------+------------------------------------|
 1902 |     show-rdepends     |Displays the first-order reverse    |
 1903 |                       |dependencies of the package (i.e    |
 1904 |                       |packages that directly depend on it)|
 1905 |-----------------------+------------------------------------|
 1906 |show-recursive-rdepends|Recursively displays the reverse    |
 1907 |                       |dependencies of the package (i.e the|
 1908 |                       |packages that depend on it, directly|
 1909 |                       |or indirectly)                      |
 1910 |-----------------------+------------------------------------|
 1911 |     graph-depends     |Generate a dependency graph of the  |
 1912 |                       |package, in the context of the      |
 1913 |                       |current Buildroot configuration. See|
 1914 |                       |this section for more details about |
 1915 |                       |dependency graphs.                  |
 1916 |-----------------------+------------------------------------|
 1917 |    graph-rdepends     |Generate a graph of this package    |
 1918 |                       |reverse dependencies (i.e the       |
 1919 |                       |packages that depend on it, directly|
 1920 |                       |or indirectly)                      |
 1921 |-----------------------+------------------------------------|
 1922 |       dirclean        |Remove the whole package build      |
 1923 |                       |directory                           |
 1924 |-----------------------+------------------------------------|
 1925 |       reinstall       |Re-run the install commands         |
 1926 |-----------------------+------------------------------------|
 1927 |        rebuild        |Re-run the compilation commands -   |
 1928 |                       |this only makes sense when using the|
 1929 |                       |OVERRIDE_SRCDIR feature or when you |
 1930 |                       |modified a file directly in the     |
 1931 |                       |build directory                     |
 1932 |-----------------------+------------------------------------|
 1933 |      reconfigure      |Re-run the configure commands, then |
 1934 |                       |rebuild - this only makes sense when|
 1935 |                       |using the OVERRIDE_SRCDIR feature or|
 1936 |                       |when you modified a file directly in|
 1937 |                       |the build directory                 |
 1938 +------------------------------------------------------------+
 1939 
 1940 8.14.6. Using Buildroot during development
 1941 
 1942 The normal operation of Buildroot is to download a tarball, extract
 1943 it, configure, compile and install the software component found
 1944 inside this tarball. The source code is extracted in output/build/
 1945 <package>-<version>, which is a temporary directory: whenever make
 1946 clean is used, this directory is entirely removed, and re-created at
 1947 the next make invocation. Even when a Git or Subversion repository is
 1948 used as the input for the package source code, Buildroot creates a
 1949 tarball out of it, and then behaves as it normally does with
 1950 tarballs.
 1951 
 1952 This behavior is well-suited when Buildroot is used mainly as an
 1953 integration tool, to build and integrate all the components of an
 1954 embedded Linux system. However, if one uses Buildroot during the
 1955 development of certain components of the system, this behavior is not
 1956 very convenient: one would instead like to make a small change to the
 1957 source code of one package, and be able to quickly rebuild the system
 1958 with Buildroot.
 1959 
 1960 Making changes directly in output/build/<package>-<version> is not an
 1961 appropriate solution, because this directory is removed on make
 1962 clean.
 1963 
 1964 Therefore, Buildroot provides a specific mechanism for this use case:
 1965 the <pkg>_OVERRIDE_SRCDIR mechanism. Buildroot reads an override
 1966 file, which allows the user to tell Buildroot the location of the
 1967 source for certain packages.
 1968 
 1969 The default location of the override file is $(CONFIG_DIR)/local.mk,
 1970 as defined by the BR2_PACKAGE_OVERRIDE_FILE configuration option. $
 1971 (CONFIG_DIR) is the location of the Buildroot .config file, so
 1972 local.mk by default lives side-by-side with the .config file, which
 1973 means:
 1974 
 1975   * In the top-level Buildroot source directory for in-tree builds
 1976     (i.e., when O= is not used)
 1977   * In the out-of-tree directory for out-of-tree builds (i.e., when O
 1978     = is used)
 1979 
 1980 If a different location than these defaults is required, it can be
 1981 specified through the BR2_PACKAGE_OVERRIDE_FILE configuration option.
 1982 
 1983 In this override file, Buildroot expects to find lines of the form:
 1984 
 1985 <pkg1>_OVERRIDE_SRCDIR = /path/to/pkg1/sources
 1986 <pkg2>_OVERRIDE_SRCDIR = /path/to/pkg2/sources
 1987 
 1988 For example:
 1989 
 1990 LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
 1991 BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/
 1992 
 1993 When Buildroot finds that for a given package, an <pkg>
 1994 _OVERRIDE_SRCDIR has been defined, it will no longer attempt to
 1995 download, extract and patch the package. Instead, it will directly
 1996 use the source code available in the specified directory and make
 1997 clean will not touch this directory. This allows to point Buildroot
 1998 to your own directories, that can be managed by Git, Subversion, or
 1999 any other version control system. To achieve this, Buildroot will use
 2000 rsync to copy the source code of the component from the specified
 2001 <pkg>_OVERRIDE_SRCDIR to output/build/<package>-custom/.
 2002 
 2003 This mechanism is best used in conjunction with the make <pkg>
 2004 -rebuild and make <pkg>-reconfigure targets. A make <pkg>-rebuild all
 2005 sequence will rsync the source code from <pkg>_OVERRIDE_SRCDIR to
 2006 output/build/<package>-custom (thanks to rsync, only the modified
 2007 files are copied), and restart the build process of just this
 2008 package.
 2009 
 2010 In the example of the linux package above, the developer can then
 2011 make a source code change in /home/bob/linux and then run:
 2012 
 2013 make linux-rebuild all
 2014 
 2015 and in a matter of seconds gets the updated Linux kernel image in
 2016 output/images. Similarly, a change can be made to the BusyBox source
 2017 code in /home/bob/busybox, and after:
 2018 
 2019 make busybox-rebuild all
 2020 
 2021 the root filesystem image in output/images contains the updated
 2022 BusyBox.
 2023 
 2024 Source trees for big projects often contain hundreds or thousands of
 2025 files which are not needed for building, but will slow down the
 2026 process of copying the sources with rsync. Optionally, it is possible
 2027 define <pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS to skip syncing certain
 2028 files from the source tree. For example, when working on the
 2029 webkitgtk package, the following will exclude the tests and in-tree
 2030 builds from a local WebKit source tree:
 2031 
 2032 WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
 2033 WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
 2034         --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
 2035         --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
 2036         --exclude WebKit.xcworkspace --exclude Websites --exclude Examples
 2037 
 2038 By default, Buildroot skips syncing of VCS artifacts (e.g., the .git
 2039 and .svn directories). Some packages prefer to have these VCS
 2040 directories available during build, for example for automatically
 2041 determining a precise commit reference for version information. To
 2042 undo this built-in filtering at a cost of a slower speed, add these
 2043 directories back:
 2044 
 2045 LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git
 2046 
 2047 Chapter 9. Project-specific customization
 2048 
 2049 Typical actions you may need to perform for a given project are:
 2050 
 2051   * configuring Buildroot (including build options and toolchain,
 2052     bootloader, kernel, package and filesystem image type selection)
 2053   * configuring other components, like the Linux kernel and BusyBox
 2054   * customizing the generated target filesystem
 2055 
 2056       + adding or overwriting files on the target filesystem (using
 2057         BR2_ROOTFS_OVERLAY)
 2058       + modifying or deleting files on the target filesystem (using
 2059         BR2_ROOTFS_POST_BUILD_SCRIPT)
 2060       + running arbitrary commands prior to generating the filesystem
 2061         image (using BR2_ROOTFS_POST_BUILD_SCRIPT)
 2062       + setting file permissions and ownership (using
 2063         BR2_ROOTFS_DEVICE_TABLE)
 2064       + adding custom devices nodes (using
 2065         BR2_ROOTFS_STATIC_DEVICE_TABLE)
 2066   * adding custom user accounts (using BR2_ROOTFS_USERS_TABLES)
 2067   * running arbitrary commands after generating the filesystem image
 2068     (using BR2_ROOTFS_POST_IMAGE_SCRIPT)
 2069   * adding project-specific patches to some packages (using
 2070     BR2_GLOBAL_PATCH_DIR)
 2071   * adding project-specific packages
 2072 
 2073 An important note regarding such project-specific customizations:
 2074 please carefully consider which changes are indeed project-specific
 2075 and which changes are also useful to developers outside your project.
 2076 The Buildroot community highly recommends and encourages the
 2077 upstreaming of improvements, packages and board support to the
 2078 official Buildroot project. Of course, it is sometimes not possible
 2079 or desirable to upstream because the changes are highly specific or
 2080 proprietary.
 2081 
 2082 This chapter describes how to make such project-specific
 2083 customizations in Buildroot and how to store them in a way that you
 2084 can build the same image in a reproducible way, even after running 
 2085 make clean. By following the recommended strategy, you can even use
 2086 the same Buildroot tree to build multiple distinct projects!
 2087 
 2088 9.1. Recommended directory structure
 2089 
 2090 When customizing Buildroot for your project, you will be creating one
 2091 or more project-specific files that need to be stored somewhere.
 2092 While most of these files could be placed in any location as their
 2093 path is to be specified in the Buildroot configuration, the Buildroot
 2094 developers recommend a specific directory structure which is
 2095 described in this section.
 2096 
 2097 Orthogonal to this directory structure, you can choose where you
 2098 place this structure itself: either inside the Buildroot tree, or
 2099 outside of it using a br2-external tree. Both options are valid, the
 2100 choice is up to you.
 2101 
 2102 +-- board/
 2103 |   +-- <company>/
 2104 |       +-- <boardname>/
 2105 |           +-- linux.config
 2106 |           +-- busybox.config
 2107 |           +-- <other configuration files>
 2108 |           +-- post_build.sh
 2109 |           +-- post_image.sh
 2110 |           +-- rootfs_overlay/
 2111 |           |   +-- etc/
 2112 |           |   +-- <some file>
 2113 |           +-- patches/
 2114 |               +-- foo/
 2115 |               |   +-- <some patch>
 2116 |               +-- libbar/
 2117 |                   +-- <some other patches>
 2118 |
 2119 +-- configs/
 2120 |   +-- <boardname>_defconfig
 2121 |
 2122 +-- package/
 2123 |   +-- <company>/
 2124 |       +-- Config.in (if not using a br2-external tree)
 2125 |       +-- <company>.mk (if not using a br2-external tree)
 2126 |       +-- package1/
 2127 |       |    +-- Config.in
 2128 |       |    +-- package1.mk
 2129 |       +-- package2/
 2130 |           +-- Config.in
 2131 |           +-- package2.mk
 2132 |
 2133 +-- Config.in (if using a br2-external tree)
 2134 +-- external.mk (if using a br2-external tree)
 2135 +-- external.desc (if using a br2-external tree)
 2136 
 2137 Details on the files shown above are given further in this chapter.
 2138 
 2139 Note: if you choose to place this structure outside of the Buildroot
 2140 tree but in a br2-external tree, the <company> and possibly
 2141 <boardname> components may be superfluous and can be left out.
 2142 
 2143 9.1.1. Implementing layered customizations
 2144 
 2145 It is quite common for a user to have several related projects that
 2146 partly need the same customizations. Instead of duplicating these
 2147 customizations for each project, it is recommended to use a layered
 2148 customization approach, as explained in this section.
 2149 
 2150 Almost all of the customization methods available in Buildroot, like
 2151 post-build scripts and root filesystem overlays, accept a
 2152 space-separated list of items. The specified items are always treated
 2153 in order, from left to right. By creating more than one such item,
 2154 one for the common customizations and another one for the really
 2155 project-specific customizations, you can avoid unnecessary
 2156 duplication. Each layer is typically embodied by a separate directory
 2157 inside board/<company>/. Depending on your projects, you could even
 2158 introduce more than two layers.
 2159 
 2160 An example directory structure for where a user has two customization
 2161 layers common and fooboard is:
 2162 
 2163 +-- board/
 2164     +-- <company>/
 2165         +-- common/
 2166         |   +-- post_build.sh
 2167         |   +-- rootfs_overlay/
 2168         |   |   +-- ...
 2169         |   +-- patches/
 2170         |       +-- ...
 2171         |
 2172         +-- fooboard/
 2173             +-- linux.config
 2174             +-- busybox.config
 2175             +-- <other configuration files>
 2176             +-- post_build.sh
 2177             +-- rootfs_overlay/
 2178             |   +-- ...
 2179             +-- patches/
 2180                 +-- ...
 2181 
 2182 For example, if the user has the BR2_GLOBAL_PATCH_DIR configuration
 2183 option set as:
 2184 
 2185 BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"
 2186 
 2187 then first the patches from the common layer would be applied,
 2188 followed by the patches from the fooboard layer.
 2189 
 2190 9.2. Keeping customizations outside of Buildroot
 2191 
 2192 As already briefly mentioned in Section 9.1, “Recommended directory
 2193 structure”, you can place project-specific customizations in two
 2194 locations:
 2195 
 2196   * directly within the Buildroot tree, typically maintaining them
 2197     using branches in a version control system so that upgrading to a
 2198     newer Buildroot release is easy.
 2199   * outside of the Buildroot tree, using the br2-external mechanism.
 2200     This mechanism allows to keep package recipes, board support and
 2201     configuration files outside of the Buildroot tree, while still
 2202     having them nicely integrated in the build logic. We call this
 2203     location a br2-external tree. This section explains how to use
 2204     the br2-external mechanism and what to provide in a br2-external
 2205     tree.
 2206 
 2207 One can tell Buildroot to use one or more br2-external trees by
 2208 setting the BR2_EXTERNAL make variable set to the path(s) of the
 2209 br2-external tree(s) to use. It can be passed to any Buildroot make
 2210 invocation. It is automatically saved in the hidden .br2-external.mk
 2211 file in the output directory. Thanks to this, there is no need to
 2212 pass BR2_EXTERNAL at every make invocation. It can however be changed
 2213 at any time by passing a new value, and can be removed by passing an
 2214 empty value.
 2215 
 2216 Note. The path to a br2-external tree can be either absolute or
 2217 relative. If it is passed as a relative path, it is important to note
 2218 that it is interpreted relative to the main Buildroot source
 2219 directory, not to the Buildroot output directory.
 2220 
 2221 Note: If using an br2-external tree from before Buildroot 2016.11,
 2222 you need to convert it before you can use it with Buildroot 2016.11
 2223 onward. See Section 27.1, “Migrating to 2016.11” for help on doing
 2224 so.
 2225 
 2226 Some examples:
 2227 
 2228 buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig
 2229 
 2230 From now on, definitions from the /path/to/foo br2-external tree will
 2231 be used:
 2232 
 2233 buildroot/ $ make
 2234 buildroot/ $ make legal-info
 2235 
 2236 We can switch to another br2-external tree at any time:
 2237 
 2238 buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig
 2239 
 2240 We can also use multiple br2-external trees:
 2241 
 2242 buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig
 2243 
 2244 Or disable the usage of any br2-external tree:
 2245 
 2246 buildroot/ $ make BR2_EXTERNAL= xconfig
 2247 
 2248 9.2.1. Layout of a br2-external tree
 2249 
 2250 A br2-external tree must contain at least those three files,
 2251 described in the following chapters:
 2252 
 2253   * external.desc
 2254   * external.mk
 2255   * Config.in
 2256 
 2257 Apart from those mandatory files, there may be additional and
 2258 optional content that may be present in a br2-external tree, like the
 2259 configs/ or provides/ directories. They are described in the
 2260 following chapters as well.
 2261 
 2262 A complete example br2-external tree layout is also described later.
 2263 
 2264 9.2.1.1. The external.desc file
 2265 
 2266 That file describes the br2-external tree: the name and description
 2267 for that br2-external tree.
 2268 
 2269 The format for this file is line based, with each line starting by a
 2270 keyword, followed by a colon and one or more spaces, followed by the
 2271 value assigned to that keyword. There are two keywords currently
 2272 recognised:
 2273 
 2274   * name, mandatory, defines the name for that br2-external tree.
 2275     That name must only use ASCII characters in the set [A-Za-z0-9_];
 2276     any other character is forbidden. Buildroot sets the variable
 2277     BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the
 2278     br2-external tree, so that you can use it to refer to your
 2279     br2-external tree. This variable is available both in Kconfig, so
 2280     you can use it to source your Kconfig files (see below) and in
 2281     the Makefile, so that you can use it to include other Makefiles
 2282     (see below) or refer to other files (like data files) from your
 2283     br2-external tree.
 2284 
 2285     Note: Since it is possible to use multiple br2-external trees at
 2286     once, this name is used by Buildroot to generate variables for
 2287     each of those trees. That name is used to identify your
 2288     br2-external tree, so try to come up with a name that really
 2289     describes your br2-external tree, in order for it to be
 2290     relatively unique, so that it does not clash with another name
 2291     from another br2-external tree, especially if you are planning on
 2292     somehow sharing your br2-external tree with third parties or
 2293     using br2-external trees from third parties.
 2294 
 2295   * desc, optional, provides a short description for that
 2296     br2-external tree. It shall fit on a single line, is mostly
 2297     free-form (see below), and is used when displaying information
 2298     about a br2-external tree (e.g. above the list of defconfig
 2299     files, or as the prompt in the menuconfig); as such, it should
 2300     relatively brief (40 chars is probably a good upper limit). The
 2301     description is available in the BR2_EXTERNAL_$(NAME)_DESC
 2302     variable.
 2303 
 2304 Examples of names and the corresponding BR2_EXTERNAL_$(NAME)_PATH
 2305 variables:
 2306 
 2307   * FOO → BR2_EXTERNAL_FOO_PATH
 2308   * BAR_42 → BR2_EXTERNAL_BAR_42_PATH
 2309 
 2310 In the following examples, it is assumed the name to be set to
 2311 BAR_42.
 2312 
 2313 Note: Both BR2_EXTERNAL_$(NAME)_PATH and BR2_EXTERNAL_$(NAME)_DESC
 2314 are available in the Kconfig files and the Makefiles. They are also
 2315 exported in the environment so are available in post-build,
 2316 post-image and in-fakeroot scripts.
 2317 
 2318 9.2.1.2. The Config.in and external.mk files
 2319 
 2320 Those files (which may each be empty) can be used to define package
 2321 recipes (i.e. foo/Config.in and foo/foo.mk like for packages bundled
 2322 in Buildroot itself) or other custom configuration options or make
 2323 logic.
 2324 
 2325 Buildroot automatically includes the Config.in from each br2-external
 2326 tree to make it appear in the top-level configuration menu, and
 2327 includes the external.mk from each br2-external tree with the rest of
 2328 the makefile logic.
 2329 
 2330 The main usage of this is to store package recipes. The recommended
 2331 way to do this is to write a Config.in file that looks like:
 2332 
 2333 source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
 2334 source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"
 2335 
 2336 Then, have an external.mk file that looks like:
 2337 
 2338 include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
 2339 
 2340 And then in $(BR2_EXTERNAL_BAR_42_PATH)/package/package1 and $
 2341 (BR2_EXTERNAL_BAR_42_PATH)/package/package2 create normal Buildroot
 2342 package recipes, as explained in Chapter 18, Adding new packages to
 2343 Buildroot. If you prefer, you can also group the packages in
 2344 subdirectories called <boardname> and adapt the above paths
 2345 accordingly.
 2346 
 2347 You can also define custom configuration options in Config.in and
 2348 custom make logic in external.mk.
 2349 
 2350 9.2.1.3. The configs/ directory
 2351 
 2352 One can store Buildroot defconfigs in the configs subdirectory of the
 2353 br2-external tree. Buildroot will automatically show them in the
 2354 output of make list-defconfigs and allow them to be loaded with the
 2355 normal make <name>_defconfig command. They will be visible in the 
 2356 make list-defconfigs output, below an External configs label that
 2357 contains the name of the br2-external tree they are defined in.
 2358 
 2359 Note: If a defconfig file is present in more than one br2-external
 2360 tree, then the one from the last br2-external tree is used. It is
 2361 thus possible to override a defconfig bundled in Buildroot or another
 2362 br2-external tree.
 2363 
 2364 9.2.1.4. The provides/ directory
 2365 
 2366 For some packages, Buildroot provides a choice between two (or more)
 2367 implementations of API-compatible such packages. For example, there
 2368 is a choice to choose either libjpeg ot jpeg-turbo; there is one
 2369 between openssl or libressl; there is one to select one of the known,
 2370 pre-configured toolchains…
 2371 
 2372 It is possible for a br2-external to extend those choices, by
 2373 providing a set of files that define those alternatives:
 2374 
 2375   * provides/toolchains.in defines the pre-configured toolchains,
 2376     which will then be listed in the toolchain selection;
 2377   * provides/jpeg.in defines the alternative libjpeg implementations;
 2378   * provides/openssl.in defines the alternative openssl
 2379     implementations;
 2380   * provides/skeleton.in defines the alternative skeleton
 2381     implementations;
 2382   * provides/init.in defines the alternative init system
 2383     implementations, this can be used to select a default skeleton
 2384     for your init.
 2385 
 2386 9.2.1.5. Free-form content
 2387 
 2388 One can store all the board-specific configuration files there, such
 2389 as the kernel configuration, the root filesystem overlay, or any
 2390 other configuration file for which Buildroot allows to set the
 2391 location (by using the BR2_EXTERNAL_$(NAME)_PATH variable). For
 2392 example, you could set the paths to a global patch directory, to a
 2393 rootfs overlay and to the kernel configuration file as follows (e.g.
 2394 by running make menuconfig and filling in these options):
 2395 
 2396 BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
 2397 BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/overlay/
 2398 BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/<boardname>/kernel.config
 2399 
 2400 9.2.1.6. Additional Linux kernel extensions
 2401 
 2402 Additional Linux kernel extensions (see Section 18.21.2,
 2403 “linux-kernel-extensions”) can be added by storing them in the linux/
 2404 directory at the root of a br2-external tree.
 2405 
 2406 9.2.1.7. Example layout
 2407 
 2408 Here is an example layout using all features of br2-external (the
 2409 sample content is shown for the file above it, when it is relevant to
 2410 explain the br2-external tree; this is all entirely made up just for
 2411 the sake of illustration, of course):
 2412 
 2413 /path/to/br2-ext-tree/
 2414   |- external.desc
 2415   |     |name: BAR_42
 2416   |     |desc: Example br2-external tree
 2417   |     `----
 2418   |
 2419   |- Config.in
 2420   |     |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
 2421   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
 2422   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
 2423   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
 2424   |     |
 2425   |     |config BAR_42_FLASH_ADDR
 2426   |     |    hex "my-board flash address"
 2427   |     |    default 0x10AD
 2428   |     `----
 2429   |
 2430   |- external.mk
 2431   |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
 2432   |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
 2433   |     |
 2434   |     |flash-my-board:
 2435   |     |    $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
 2436   |     |        --image $(BINARIES_DIR)/image.bin \
 2437   |     |        --address $(BAR_42_FLASH_ADDR)
 2438   |     `----
 2439   |
 2440   |- package/pkg-1/Config.in
 2441   |     |config BR2_PACKAGE_PKG_1
 2442   |     |    bool "pkg-1"
 2443   |     |    help
 2444   |     |      Some help about pkg-1
 2445   |     `----
 2446   |- package/pkg-1/pkg-1.hash
 2447   |- package/pkg-1/pkg-1.mk
 2448   |     |PKG_1_VERSION = 1.2.3
 2449   |     |PKG_1_SITE = /some/where/to/get/pkg-1
 2450   |     |PKG_1_LICENSE = blabla
 2451   |     |
 2452   |     |define PKG_1_INSTALL_INIT_SYSV
 2453   |     |    $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
 2454   |     |                          $(TARGET_DIR)/etc/init.d/S99my-daemon
 2455   |     |endef
 2456   |     |
 2457   |     |$(eval $(autotools-package))
 2458   |     `----
 2459   |- package/pkg-1/S99my-daemon
 2460   |
 2461   |- package/pkg-2/Config.in
 2462   |- package/pkg-2/pkg-2.hash
 2463   |- package/pkg-2/pkg-2.mk
 2464   |
 2465   |- provides/jpeg.in
 2466   |     |config BR2_PACKAGE_MY_JPEG
 2467   |     |    bool "my-jpeg"
 2468   |     `----
 2469   |- package/my-jpeg/Config.in
 2470   |     |config BR2_PACKAGE_PROVIDES_JPEG
 2471   |     |    default "my-jpeg" if BR2_PACKAGE_MY_JPEG
 2472   |     `----
 2473   |- package/my-jpeg/my-jpeg.mk
 2474   |     |# This is a normal package .mk file
 2475   |     |MY_JPEG_VERSION = 1.2.3
 2476   |     |MY_JPEG_SITE = https://example.net/some/place
 2477   |     |MY_JPEG_PROVIDES = jpeg
 2478   |     |$(eval $(autotools-package))
 2479   |     `----
 2480   |
 2481   |- provides/init.in
 2482   |     |config BR2_INIT_MINE
 2483   |     |    bool "my custom init"
 2484   |     |    select BR2_PACKAGE_MY_INIT
 2485   |     |    select BR2_PACKAGE_SKELETON_INIT_MINE if BR2_ROOTFS_SKELETON_DEFAULT
 2486   |     `----
 2487   |
 2488   |- provides/skeleton.in
 2489   |     |config BR2_ROOTFS_SKELETON_MINE
 2490   |     |    bool "my custom skeleton"
 2491   |     |    select BR2_PACKAGE_SKELETON_MINE
 2492   |     `----
 2493   |- package/skeleton-mine/Config.in
 2494   |     |config BR2_PACKAGE_SKELETON_MINE
 2495   |     |    bool
 2496   |     |    select BR2_PACKAGE_HAS_SKELETON
 2497   |     |
 2498   |     |config BR2_PACKAGE_PROVIDES_SKELETON
 2499   |     |    default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
 2500   |     `----
 2501   |- package/skeleton-mine/skeleton-mine.mk
 2502   |     |SKELETON_MINE_ADD_TOOLCHAIN_DEPENDENCY = NO
 2503   |     |SKELETON_MINE_ADD_SKELETON_DEPENDENCY = NO
 2504   |     |SKELETON_MINE_PROVIDES = skeleton
 2505   |     |SKELETON_MINE_INSTALL_STAGING = YES
 2506   |     |$(eval $(generic-package))
 2507   |     `----
 2508   |
 2509   |- provides/toolchains.in
 2510   |     |config BR2_TOOLCHAIN_EXTERNAL_MINE
 2511   |     |    bool "my custom toolchain"
 2512   |     |    depends on BR2_some_arch
 2513   |     |    select BR2_INSTALL_LIBSTDCPP
 2514   |     `----
 2515   |- toolchain/toolchain-external-mine/Config.in.options
 2516   |     |if BR2_TOOLCHAIN_EXTERNAL_MINE
 2517   |     |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
 2518   |     |    default "arch-mine-linux-gnu"
 2519   |     |config BR2_PACKAGE_PROVIDES_TOOLCHAIN_EXTERNAL
 2520   |     |    default "toolchain-external-mine"
 2521   |     |endif
 2522   |     `----
 2523   |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
 2524   |     |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
 2525   |     |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
 2526   |     |$(eval $(toolchain-external-package))
 2527   |     `----
 2528   |
 2529   |- linux/Config.ext.in
 2530   |     |config BR2_LINUX_KERNEL_EXT_EXAMPLE_DRIVER
 2531   |     |    bool "example-external-driver"
 2532   |     |    help
 2533   |     |      Example external driver
 2534   |     |---
 2535   |- linux/linux-ext-example-driver.mk
 2536   |
 2537   |- configs/my-board_defconfig
 2538   |     |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
 2539   |     |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
 2540   |     |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
 2541   |     |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
 2542   |     `----
 2543   |
 2544   |- patches/linux/0001-some-change.patch
 2545   |- patches/linux/0002-some-other-change.patch
 2546   |- patches/busybox/0001-fix-something.patch
 2547   |
 2548   |- board/my-board/kernel.config
 2549   |- board/my-board/overlay/var/www/index.html
 2550   |- board/my-board/overlay/var/www/my.css
 2551   |- board/my-board/flash-image
 2552   `- board/my-board/post-image.sh
 2553         |#!/bin/sh
 2554         |generate-my-binary-image \
 2555         |    --root ${BINARIES_DIR}/rootfs.tar \
 2556         |    --kernel ${BINARIES_DIR}/zImage \
 2557         |    --dtb ${BINARIES_DIR}/my-board.dtb \
 2558         |    --output ${BINARIES_DIR}/image.bin
 2559         `----
 2560 
 2561 The br2-external tree will then be visible in the menuconfig (with
 2562 the layout expanded):
 2563 
 2564 External options  --->
 2565     *** Example br2-external tree (in /path/to/br2-ext-tree/)
 2566     [ ] pkg-1
 2567     [ ] pkg-2
 2568     (0x10AD) my-board flash address
 2569 
 2570 If you are using more than one br2-external tree, it would look like
 2571 (with the layout expanded and the second one with name FOO_27 but no
 2572 desc: field in external.desc):
 2573 
 2574 External options  --->
 2575     Example br2-external tree  --->
 2576         *** Example br2-external tree (in /path/to/br2-ext-tree)
 2577         [ ] pkg-1
 2578         [ ] pkg-2
 2579         (0x10AD) my-board flash address
 2580     FOO_27  --->
 2581         *** FOO_27 (in /path/to/another-br2-ext)
 2582         [ ] foo
 2583         [ ] bar
 2584 
 2585 Additionally, the jpeg provider will be visible in the jpeg choice:
 2586 
 2587 Target packages  --->
 2588     Libraries  --->
 2589         Graphics  --->
 2590             [*] jpeg support
 2591                 jpeg variant ()  --->
 2592                     ( ) jpeg
 2593                     ( ) jpeg-turbo
 2594                         *** jpeg from: Example br2-external tree ***
 2595                     (X) my-jpeg
 2596                         *** jpeg from: FOO_27 ***
 2597                     ( ) another-jpeg
 2598 
 2599 And similarly for the toolchains:
 2600 
 2601 Toolchain  --->
 2602     Toolchain ()  --->
 2603         ( ) Custom toolchain
 2604             *** Toolchains from: Example br2-external tree ***
 2605         (X) my custom toolchain
 2606 
 2607 Note. The toolchain options in toolchain/toolchain-external-mine/
 2608 Config.in.options will not appear in the Toolchain menu. They must be
 2609 explicitly included from within the br2-external’s top-level
 2610 Config.in and will thus appear in the External options menu.
 2611 
 2612 9.3. Storing the Buildroot configuration
 2613 
 2614 The Buildroot configuration can be stored using the command make
 2615 savedefconfig.
 2616 
 2617 This strips the Buildroot configuration down by removing
 2618 configuration options that are at their default value. The result is
 2619 stored in a file called defconfig. If you want to save it in another
 2620 place, change the BR2_DEFCONFIG option in the Buildroot configuration
 2621 itself, or call make with make savedefconfig BR2_DEFCONFIG=
 2622 <path-to-defconfig>.
 2623 
 2624 The recommended place to store this defconfig is configs/<boardname>
 2625 _defconfig. If you follow this recommendation, the configuration will
 2626 be listed in make help and can be set again by running make
 2627 <boardname>_defconfig.
 2628 
 2629 Alternatively, you can copy the file to any other place and rebuild
 2630 with make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>.
 2631 
 2632 9.4. Storing the configuration of other components
 2633 
 2634 The configuration files for BusyBox, the Linux kernel, Barebox,
 2635 U-Boot and uClibc should be stored as well if changed. For each of
 2636 these components, a Buildroot configuration option exists to point to
 2637 an input configuration file, e.g.
 2638 BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. To store their configuration,
 2639 set these configuration options to a path where you want to save the
 2640 configuration files, and then use the helper targets described below
 2641 to actually store the configuration.
 2642 
 2643 As explained in Section 9.1, “Recommended directory structure”, the
 2644 recommended path to store these configuration files is board/
 2645 <company>/<boardname>/foo.config.
 2646 
 2647 Make sure that you create a configuration file before changing the
 2648 BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE etc. options. Otherwise,
 2649 Buildroot will try to access this config file, which doesn’t exist
 2650 yet, and will fail. You can create the configuration file by running
 2651 make linux-menuconfig etc.
 2652 
 2653 Buildroot provides a few helper targets to make the saving of
 2654 configuration files easier.
 2655 
 2656   * make linux-update-defconfig saves the linux configuration to the
 2657     path specified by BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE. It
 2658     simplifies the config file by removing default values. However,
 2659     this only works with kernels starting from 2.6.33. For earlier
 2660     kernels, use make linux-update-config.
 2661   * make busybox-update-config saves the busybox configuration to the
 2662     path specified by BR2_PACKAGE_BUSYBOX_CONFIG.
 2663   * make uclibc-update-config saves the uClibc configuration to the
 2664     path specified by BR2_UCLIBC_CONFIG.
 2665   * make barebox-update-defconfig saves the barebox configuration to
 2666     the path specified by BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE.
 2667   * make uboot-update-defconfig saves the U-Boot configuration to the
 2668     path specified by BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE.
 2669   * For at91bootstrap3, no helper exists so you have to copy the
 2670     config file manually to
 2671     BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE.
 2672 
 2673 9.5. Customizing the generated target filesystem
 2674 
 2675 Besides changing the configuration through make *config, there are a
 2676 few other ways to customize the resulting target filesystem.
 2677 
 2678 The two recommended methods, which can co-exist, are root filesystem
 2679 overlay(s) and post build script(s).
 2680 
 2681 Root filesystem overlays (BR2_ROOTFS_OVERLAY)
 2682 
 2683     A filesystem overlay is a tree of files that is copied directly
 2684     over the target filesystem after it has been built. To enable
 2685     this feature, set config option BR2_ROOTFS_OVERLAY (in the System
 2686     configuration menu) to the root of the overlay. You can even
 2687     specify multiple overlays, space-separated. If you specify a
 2688     relative path, it will be relative to the root of the Buildroot
 2689     tree. Hidden directories of version control systems, like .git,
 2690     .svn, .hg, etc., files called .empty and files ending in ~ are
 2691     excluded from the copy.
 2692 
 2693     When BR2_ROOTFS_MERGED_USR is enabled, then the overlay must not
 2694     contain the /bin, /lib or /sbin directories, as Buildroot will
 2695     create them as symbolic links to the relevant folders in /usr. In
 2696     such a situation, should the overlay have any programs or
 2697     libraries, they should be placed in /usr/bin, /usr/sbin and /usr/
 2698     lib.
 2699 
 2700     As shown in Section 9.1, “Recommended directory structure”, the
 2701     recommended path for this overlay is board/<company>/<boardname>/
 2702     rootfs-overlay.
 2703 
 2704 Post-build scripts (BR2_ROOTFS_POST_BUILD_SCRIPT)
 2705 
 2706     Post-build scripts are shell scripts called after Buildroot
 2707     builds all the selected software, but before the rootfs images
 2708     are assembled. To enable this feature, specify a space-separated
 2709     list of post-build scripts in config option
 2710     BR2_ROOTFS_POST_BUILD_SCRIPT (in the System configuration menu).
 2711     If you specify a relative path, it will be relative to the root
 2712     of the Buildroot tree.
 2713 
 2714     Using post-build scripts, you can remove or modify any file in
 2715     your target filesystem. You should, however, use this feature
 2716     with care. Whenever you find that a certain package generates
 2717     wrong or unneeded files, you should fix that package rather than
 2718     work around it with some post-build cleanup scripts.
 2719 
 2720     As shown in Section 9.1, “Recommended directory structure”, the
 2721     recommended path for this script is board/<company>/<boardname>/
 2722     post_build.sh.
 2723 
 2724     The post-build scripts are run with the main Buildroot tree as
 2725     current working directory. The path to the target filesystem is
 2726     passed as the first argument to each script. If the config option
 2727     BR2_ROOTFS_POST_SCRIPT_ARGS is not empty, these arguments will be
 2728     passed to the script too. All the scripts will be passed the
 2729     exact same set of arguments, it is not possible to pass different
 2730     sets of arguments to each script.
 2731 
 2732     In addition, you may also use these environment variables:
 2733 
 2734       + BR2_CONFIG: the path to the Buildroot .config file
 2735       + CONFIG_DIR: the directory containing the .config file, and
 2736         therefore the top-level Buildroot Makefile to use (which is
 2737         correct for both in-tree and out-of-tree builds)
 2738       + HOST_DIR, STAGING_DIR, TARGET_DIR: see Section 18.5.2,
 2739         “generic-package reference”
 2740       + BUILD_DIR: the directory where packages are extracted and
 2741         built
 2742       + BINARIES_DIR: the place where all binary files (aka images)
 2743         are stored
 2744       + BASE_DIR: the base output directory
 2745 
 2746 Below three more methods of customizing the target filesystem are
 2747 described, but they are not recommended.
 2748 
 2749 Direct modification of the target filesystem
 2750 
 2751     For temporary modifications, you can modify the target filesystem
 2752     directly and rebuild the image. The target filesystem is
 2753     available under output/target/. After making your changes, run
 2754     make to rebuild the target filesystem image.
 2755 
 2756     This method allows you to do anything to the target filesystem,
 2757     but if you need to clean your Buildroot tree using make clean,
 2758     these changes will be lost. Such cleaning is necessary in several
 2759     cases, refer to Section 8.2, “Understanding when a full rebuild
 2760     is necessary” for details. This solution is therefore only useful
 2761     for quick tests: changes do not survive the make clean command.
 2762     Once you have validated your changes, you should make sure that
 2763     they will persist after a make clean, using a root filesystem
 2764     overlay or a post-build script.
 2765 
 2766 Custom target skeleton (BR2_ROOTFS_SKELETON_CUSTOM)
 2767 
 2768     The root filesystem image is created from a target skeleton, on
 2769     top of which all packages install their files. The skeleton is
 2770     copied to the target directory output/target before any package
 2771     is built and installed. The default target skeleton provides the
 2772     standard Unix filesystem layout and some basic init scripts and
 2773     configuration files.
 2774 
 2775     If the default skeleton (available under system/skeleton) does
 2776     not match your needs, you would typically use a root filesystem
 2777     overlay or post-build script to adapt it. However, if the default
 2778     skeleton is entirely different than what you need, using a custom
 2779     skeleton may be more suitable.
 2780 
 2781     To enable this feature, enable config option
 2782     BR2_ROOTFS_SKELETON_CUSTOM and set
 2783     BR2_ROOTFS_SKELETON_CUSTOM_PATH to the path of your custom
 2784     skeleton. Both options are available in the System configuration
 2785     menu. If you specify a relative path, it will be relative to the
 2786     root of the Buildroot tree.
 2787 
 2788     Custom skeletons don’t need to contain the /bin, /lib or /sbin
 2789     directories, since they are created automatically during the
 2790     build. When BR2_ROOTFS_MERGED_USR is enabled, then the custom
 2791     skeleton must not contain the /bin, /lib or /sbin directories, as
 2792     Buildroot will create them as symbolic links to the relevant
 2793     folders in /usr. In such a situation, should the skeleton have
 2794     any programs or libraries, they should be placed in /usr/bin, /
 2795     usr/sbin and /usr/lib.
 2796 
 2797     This method is not recommended because it duplicates the entire
 2798     skeleton, which prevents taking advantage of the fixes or
 2799     improvements brought to the default skeleton in later Buildroot
 2800     releases.
 2801 
 2802 Post-fakeroot scripts (BR2_ROOTFS_POST_FAKEROOT_SCRIPT)
 2803 
 2804     When aggregating the final images, some parts of the process
 2805     requires root rights: creating device nodes in /dev, setting
 2806     permissions or ownership to files and directories… To avoid
 2807     requiring actual root rights, Buildroot uses fakeroot to simulate
 2808     root rights. This is not a complete substitute for actually being
 2809     root, but is enough for what Buildroot needs.
 2810 
 2811     Post-fakeroot scripts are shell scripts that are called at the 
 2812     end of the fakeroot phase, right before the filesystem image
 2813     generator is called. As such, they are called in the fakeroot
 2814     context.
 2815 
 2816     Post-fakeroot scripts can be useful in case you need to tweak the
 2817     filesystem to do modifications that are usually only available to
 2818     the root user.
 2819 
 2820     Note: It is recommended to use the existing mechanisms to set
 2821     file permissions or create entries in /dev (see Section 9.5.1,
 2822     “Setting file permissions and ownership and adding custom devices
 2823     nodes”) or to create users (see Section 9.6, “Adding custom user
 2824     accounts”)
 2825 
 2826     Note: The difference between post-build scripts (above) and
 2827     fakeroot scripts, is that post-build scripts are not called in
 2828     the fakeroot context.
 2829 
 2830     Note: Using fakeroot is not an absolute substitute for actually
 2831     being root. fakeroot only ever fakes the file access rights and
 2832     types (regular, block-or-char device…) and uid/gid; these are
 2833     emulated in-memory.
 2834 
 2835 9.5.1. Setting file permissions and ownership and adding custom
 2836 devices nodes
 2837 
 2838 Sometimes it is needed to set specific permissions or ownership on
 2839 files or device nodes. For example, certain files may need to be
 2840 owned by root. Since the post-build scripts are not run as root, you
 2841 cannot do such changes from there unless you use an explicit fakeroot
 2842 from the post-build script.
 2843 
 2844 Instead, Buildroot provides support for so-called permission tables.
 2845 To use this feature, set config option BR2_ROOTFS_DEVICE_TABLE to a
 2846 space-separated list of permission tables, regular text files
 2847 following the makedev syntax.
 2848 
 2849 If you are using a static device table (i.e. not using devtmpfs,
 2850 mdev, or (e)udev) then you can add device nodes using the same
 2851 syntax, in so-called device tables. To use this feature, set config
 2852 option BR2_ROOTFS_STATIC_DEVICE_TABLE to a space-separated list of
 2853 device tables.
 2854 
 2855 As shown in Section 9.1, “Recommended directory structure”, the
 2856 recommended location for such files is board/<company>/<boardname>/.
 2857 
 2858 It should be noted that if the specific permissions or device nodes
 2859 are related to a specific application, you should set variables
 2860 FOO_PERMISSIONS and FOO_DEVICES in the package’s .mk file instead
 2861 (see Section 18.5.2, “generic-package reference”).
 2862 
 2863 9.6. Adding custom user accounts
 2864 
 2865 Sometimes it is needed to add specific users in the target system. To
 2866 cover this requirement, Buildroot provides support for so-called 
 2867 users tables. To use this feature, set config option
 2868 BR2_ROOTFS_USERS_TABLES to a space-separated list of users tables,
 2869 regular text files following the makeusers syntax.
 2870 
 2871 As shown in Section 9.1, “Recommended directory structure”, the
 2872 recommended location for such files is board/<company>/<boardname>/.
 2873 
 2874 It should be noted that if the custom users are related to a specific
 2875 application, you should set variable FOO_USERS in the package’s .mk
 2876 file instead (see Section 18.5.2, “generic-package reference”).
 2877 
 2878 9.7. Customization after the images have been created
 2879 
 2880 While post-build scripts (Section 9.5, “Customizing the generated
 2881 target filesystem”) are run before building the filesystem image,
 2882 kernel and bootloader, post-image scripts can be used to perform some
 2883 specific actions after all images have been created.
 2884 
 2885 Post-image scripts can for example be used to automatically extract
 2886 your root filesystem tarball in a location exported by your NFS
 2887 server, or to create a special firmware image that bundles your root
 2888 filesystem and kernel image, or any other custom action required for
 2889 your project.
 2890 
 2891 To enable this feature, specify a space-separated list of post-image
 2892 scripts in config option BR2_ROOTFS_POST_IMAGE_SCRIPT (in the System
 2893 configuration menu). If you specify a relative path, it will be
 2894 relative to the root of the Buildroot tree.
 2895 
 2896 Just like post-build scripts, post-image scripts are run with the
 2897 main Buildroot tree as current working directory. The path to the
 2898 images output directory is passed as the first argument to each
 2899 script. If the config option BR2_ROOTFS_POST_SCRIPT_ARGS is not
 2900 empty, these arguments will be passed to the script too. All the
 2901 scripts will be passed the exact same set of arguments, it is not
 2902 possible to pass different sets of arguments to each script.
 2903 
 2904 Again just like for the post-build scripts, the scripts have access
 2905 to the environment variables BR2_CONFIG, HOST_DIR, STAGING_DIR,
 2906 TARGET_DIR, BUILD_DIR, BINARIES_DIR, CONFIG_DIR and BASE_DIR.
 2907 
 2908 The post-image scripts will be executed as the user that executes
 2909 Buildroot, which should normally not be the root user. Therefore, any
 2910 action requiring root permissions in one of these scripts will
 2911 require special handling (usage of fakeroot or sudo), which is left
 2912 to the script developer.
 2913 
 2914 9.8. Adding project-specific patches
 2915 
 2916 It is sometimes useful to apply extra patches to packages - on top of
 2917 those provided in Buildroot. This might be used to support custom
 2918 features in a project, for example, or when working on a new
 2919 architecture.
 2920 
 2921 The BR2_GLOBAL_PATCH_DIR configuration option can be used to specify
 2922 a space separated list of one or more directories containing package
 2923 patches.
 2924 
 2925 For a specific version <packageversion> of a specific package
 2926 <packagename>, patches are applied from BR2_GLOBAL_PATCH_DIR as
 2927 follows:
 2928 
 2929  1. For every directory - <global-patch-dir> - that exists in
 2930     BR2_GLOBAL_PATCH_DIR, a <package-patch-dir> will be determined as
 2931     follows:
 2932 
 2933       + <global-patch-dir>/<packagename>/<packageversion>/ if the
 2934         directory exists.
 2935       + Otherwise, <global-patch-dir>/<packagename> if the directory
 2936         exists.
 2937  2. Patches will then be applied from a <package-patch-dir> as
 2938     follows:
 2939 
 2940       + If a series file exists in the package directory, then
 2941         patches are applied according to the series file;
 2942       + Otherwise, patch files matching *.patch are applied in
 2943         alphabetical order. So, to ensure they are applied in the
 2944         right order, it is highly recommended to name the patch files
 2945         like this: <number>-<description>.patch, where <number>
 2946         refers to the apply order.
 2947 
 2948 For information about how patches are applied for a package, see
 2949 Section 19.2, “How patches are applied”
 2950 
 2951 The BR2_GLOBAL_PATCH_DIR option is the preferred method for
 2952 specifying a custom patch directory for packages. It can be used to
 2953 specify a patch directory for any package in buildroot. It should
 2954 also be used in place of the custom patch directory options that are
 2955 available for packages such as U-Boot and Barebox. By doing this, it
 2956 will allow a user to manage their patches from one top-level
 2957 directory.
 2958 
 2959 The exception to BR2_GLOBAL_PATCH_DIR being the preferred method for
 2960 specifying custom patches is BR2_LINUX_KERNEL_PATCH.
 2961 BR2_LINUX_KERNEL_PATCH should be used to specify kernel patches that
 2962 are available at a URL. Note: BR2_LINUX_KERNEL_PATCH specifies kernel
 2963 patches that are applied after patches available in
 2964 BR2_GLOBAL_PATCH_DIR, as it is done from a post-patch hook of the
 2965 Linux package.
 2966 
 2967 9.9. Adding project-specific packages
 2968 
 2969 In general, any new package should be added directly in the package
 2970 directory and submitted to the Buildroot upstream project. How to add
 2971 packages to Buildroot in general is explained in full detail in
 2972 Chapter 18, Adding new packages to Buildroot and will not be repeated
 2973 here. However, your project may need some proprietary packages that
 2974 cannot be upstreamed. This section will explain how you can keep such
 2975 project-specific packages in a project-specific directory.
 2976 
 2977 As shown in Section 9.1, “Recommended directory structure”, the
 2978 recommended location for project-specific packages is package/
 2979 <company>/. If you are using the br2-external tree feature (see
 2980 Section 9.2, “Keeping customizations outside of Buildroot”) the
 2981 recommended location is to put them in a sub-directory named package/
 2982 in your br2-external tree.
 2983 
 2984 However, Buildroot will not be aware of the packages in this
 2985 location, unless we perform some additional steps. As explained in
 2986 Chapter 18, Adding new packages to Buildroot, a package in Buildroot
 2987 basically consists of two files: a .mk file (describing how to build
 2988 the package) and a Config.in file (describing the configuration
 2989 options for this package).
 2990 
 2991 Buildroot will automatically include the .mk files in first-level
 2992 subdirectories of the package directory (using the pattern package/*/
 2993 *.mk). If we want Buildroot to include .mk files from deeper
 2994 subdirectories (like package/<company>/package1/) then we simply have
 2995 to add a .mk file in a first-level subdirectory that includes these
 2996 additional .mk files. Therefore, create a file package/<company>/
 2997 <company>.mk with following contents (assuming you have only one
 2998 extra directory level below package/<company>/):
 2999 
 3000 include $(sort $(wildcard package/<company>/*/*.mk))
 3001 
 3002 For the Config.in files, create a file package/<company>/Config.in
 3003 that includes the Config.in files of all your packages. An exhaustive
 3004 list has to be provided since wildcards are not supported in the
 3005 source command of kconfig. For example:
 3006 
 3007 source "package/<company>/package1/Config.in"
 3008 source "package/<company>/package2/Config.in"
 3009 
 3010 Include this new file package/<company>/Config.in from package/
 3011 Config.in, preferably in a company-specific menu to make merges with
 3012 future Buildroot versions easier.
 3013 
 3014 If using a br2-external tree, refer to Section 9.2, “Keeping
 3015 customizations outside of Buildroot” for how to fill in those files.
 3016 
 3017 9.10. Quick guide to storing your project-specific customizations
 3018 
 3019 Earlier in this chapter, the different methods for making
 3020 project-specific customizations have been described. This section
 3021 will now summarize all this by providing step-by-step instructions to
 3022 storing your project-specific customizations. Clearly, the steps that
 3023 are not relevant to your project can be skipped.
 3024 
 3025  1. make menuconfig to configure toolchain, packages and kernel.
 3026  2. make linux-menuconfig to update the kernel config, similar for
 3027     other configuration like busybox, uclibc, …
 3028  3. mkdir -p board/<manufacturer>/<boardname>
 3029  4. Set the following options to board/<manufacturer>/<boardname>/
 3030     <package>.config (as far as they are relevant):
 3031 
 3032       + BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE
 3033       + BR2_PACKAGE_BUSYBOX_CONFIG
 3034       + BR2_UCLIBC_CONFIG
 3035       + BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE
 3036       + BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE
 3037       + BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE
 3038  5. Write the configuration files:
 3039 
 3040       + make linux-update-defconfig
 3041       + make busybox-update-config
 3042       + make uclibc-update-config
 3043       + cp <output>/build/at91bootstrap3-*/.config board/
 3044         <manufacturer>/<boardname>/at91bootstrap3.config
 3045       + make barebox-update-defconfig
 3046       + make uboot-update-defconfig
 3047  6. Create board/<manufacturer>/<boardname>/rootfs-overlay/ and fill
 3048     it with additional files you need on your rootfs, e.g. board/
 3049     <manufacturer>/<boardname>/rootfs-overlay/etc/inittab. Set
 3050     BR2_ROOTFS_OVERLAY to board/<manufacturer>/<boardname>/
 3051     rootfs-overlay.
 3052  7. Create a post-build script board/<manufacturer>/<boardname>/
 3053     post_build.sh. Set BR2_ROOTFS_POST_BUILD_SCRIPT to board/
 3054     <manufacturer>/<boardname>/post_build.sh
 3055  8. If additional setuid permissions have to be set or device nodes
 3056     have to be created, create board/<manufacturer>/<boardname>/
 3057     device_table.txt and add that path to BR2_ROOTFS_DEVICE_TABLE.
 3058  9. If additional user accounts have to be created, create board/
 3059     <manufacturer>/<boardname>/users_table.txt and add that path to
 3060     BR2_ROOTFS_USERS_TABLES.
 3061 10. To add custom patches to certain packages, set
 3062     BR2_GLOBAL_PATCH_DIR to board/<manufacturer>/<boardname>/patches/
 3063     and add your patches for each package in a subdirectory named
 3064     after the package. Each patch should be called <packagename>-
 3065     <num>-<description>.patch.
 3066 11. Specifically for the Linux kernel, there also exists the option
 3067     BR2_LINUX_KERNEL_PATCH with as main advantage that it can also
 3068     download patches from a URL. If you do not need this,
 3069     BR2_GLOBAL_PATCH_DIR is preferred. U-Boot, Barebox, at91bootstrap
 3070     and at91bootstrap3 also have separate options, but these do not
 3071     provide any advantage over BR2_GLOBAL_PATCH_DIR and will likely
 3072     be removed in the future.
 3073 12. If you need to add project-specific packages, create package/
 3074     <manufacturer>/ and place your packages in that directory. Create
 3075     an overall <manufacturer>.mk file that includes the .mk files of
 3076     all your packages. Create an overall Config.in file that sources
 3077     the Config.in files of all your packages. Include this Config.in
 3078     file from Buildroot’s package/Config.in file.
 3079 13. make savedefconfig to save the buildroot configuration.
 3080 14. cp defconfig configs/<boardname>_defconfig
 3081 
 3082 Chapter 10. Using SELinux in Buildroot
 3083 
 3084 SELinux [https://selinuxproject.org] is a Linux kernel security
 3085 module enforcing access control policies. In addition to the
 3086 traditional file permissions and access control lists, SELinux allows
 3087 to write rules for users or processes to access specific functions of
 3088 resources (files, sockets…).
 3089 
 3090 SELinux has three modes of operation:
 3091 
 3092   * Disabled: the policy is not applied
 3093   * Permissive: the policy is applied, and non-authorized actions are
 3094     simply logged. This mode is often used for troubleshooting
 3095     SELinux issues.
 3096   * Enforcing: the policy is applied, and non-authorized actions are
 3097     denied
 3098 
 3099 In Buildroot the mode of operation is controlled by the
 3100 BR2_PACKAGE_REFPOLICY_POLICY_STATE_* configuration options. The Linux
 3101 kernel also has various configuration options that affect how SELinux
 3102 is enabled (see security/selinux/Kconfig in the Linux kernel
 3103 sources).
 3104 
 3105 By default in Buildroot the SELinux policy is provided by the
 3106 upstream refpolicy [https://github.com/SELinuxProject/refpolicy]
 3107 project, enabled with BR2_PACKAGE_REFPOLICY.
 3108 
 3109 10.1. Enabling SELinux support
 3110 
 3111 To have proper support for SELinux in a Buildroot generated system,
 3112 the following configuration options must be enabled:
 3113 
 3114   * BR2_PACKAGE_LIBSELINUX
 3115   * BR2_PACKAGE_REFPOLICY
 3116 
 3117 In addition, your filesystem image format must support extended
 3118 attributes.
 3119 
 3120 10.2. SELinux policy tweaking
 3121 
 3122 The SELinux refpolicy contains modules that can be enabled or
 3123 disabled when being built. Each module provide a number of SELinux
 3124 rules. In Buildroot the non-base modules are disabled by default and
 3125 several ways to enable such modules are provided:
 3126 
 3127   * Packages can enable a list of SELinux modules within the
 3128     refpolicy using the <packagename>_SELINUX_MODULES variable.
 3129   * Packages can provide additional SELinux modules by putting them
 3130     (.fc, .if and .te files) in package/<packagename>/selinux/.
 3131   * Extra SELinux modules can be added in directories pointed by the
 3132     BR2_REFPOLICY_EXTRA_MODULES_DIRS configuration option.
 3133   * Additional modules in the refpolicy can be enabled if listed in
 3134     the BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES configuration
 3135     option.
 3136 
 3137 Buildroot also allows to completely override the refpolicy. This
 3138 allows to provide a full custom policy designed specifically for a
 3139 given system. When going this way, all of the above mechanisms are
 3140 disabled: no extra SElinux module is added to the policy, and all the
 3141 available modules within the custom policy are enabled and built into
 3142 the final binary policy. The custom policy must be a fork of the
 3143 official refpolicy [https://github.com/SELinuxProject/refpolicy].
 3144 
 3145 In order to fully override the refpolicy the following configuration
 3146 variables have to be set:
 3147 
 3148   * BR2_PACKAGE_REFPOLICY_CUSTOM_GIT
 3149   * BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL
 3150   * BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION
 3151 
 3152 Chapter 11. Frequently Asked Questions & Troubleshooting
 3153 
 3154 11.1. The boot hangs after Starting network…
 3155 
 3156 If the boot process seems to hang after the following messages
 3157 (messages not necessarily exactly similar, depending on the list of
 3158 packages selected):
 3159 
 3160 Freeing init memory: 3972K
 3161 Initializing random number generator... done.
 3162 Starting network...
 3163 Starting dropbear sshd: generating rsa key... generating dsa key... OK
 3164 
 3165 then it means that your system is running, but didn’t start a shell
 3166 on the serial console. In order to have the system start a shell on
 3167 your serial console, you have to go into the Buildroot configuration,
 3168 in System configuration, modify Run a getty (login prompt) after boot
 3169 and set the appropriate port and baud rate in the getty options
 3170 submenu. This will automatically tune the /etc/inittab file of the
 3171 generated system so that a shell starts on the correct serial port.
 3172 
 3173 11.2. Why is there no compiler on the target?
 3174 
 3175 It has been decided that support for the native compiler on the
 3176 target would be stopped from the Buildroot-2012.11 release because:
 3177 
 3178   * this feature was neither maintained nor tested, and often broken;
 3179   * this feature was only available for Buildroot toolchains;
 3180   * Buildroot mostly targets small or very small target hardware with
 3181     limited resource onboard (CPU, ram, mass-storage), for which
 3182     compiling on the target does not make much sense;
 3183   * Buildroot aims at easing the cross-compilation, making native
 3184     compilation on the target unnecessary.
 3185 
 3186 If you need a compiler on your target anyway, then Buildroot is not
 3187 suitable for your purpose. In such case, you need a real distribution
 3188 and you should opt for something like:
 3189 
 3190   * openembedded [http://www.openembedded.org]
 3191   * yocto [https://www.yoctoproject.org]
 3192   * emdebian [http://www.emdebian.org]
 3193   * Fedora [https://fedoraproject.org/wiki/Architectures]
 3194   * openSUSE ARM [http://en.opensuse.org/Portal:ARM]
 3195   * Arch Linux ARM [http://archlinuxarm.org]
 3196   * …
 3197 
 3198 11.3. Why are there no development files on the target?
 3199 
 3200 Since there is no compiler available on the target (see Section 11.2,
 3201 “Why is there no compiler on the target?”), it does not make sense to
 3202 waste space with headers or static libraries.
 3203 
 3204 Therefore, those files are always removed from the target since the
 3205 Buildroot-2012.11 release.
 3206 
 3207 11.4. Why is there no documentation on the target?
 3208 
 3209 Because Buildroot mostly targets small or very small target hardware
 3210 with limited resource onboard (CPU, ram, mass-storage), it does not
 3211 make sense to waste space with the documentation data.
 3212 
 3213 If you need documentation data on your target anyway, then Buildroot
 3214 is not suitable for your purpose, and you should look for a real
 3215 distribution (see: Section 11.2, “Why is there no compiler on the
 3216 target?”).
 3217 
 3218 11.5. Why are some packages not visible in the Buildroot config menu?
 3219 
 3220 If a package exists in the Buildroot tree and does not appear in the
 3221 config menu, this most likely means that some of the package’s
 3222 dependencies are not met.
 3223 
 3224 To know more about the dependencies of a package, search for the
 3225 package symbol in the config menu (see Section 8.1, “make tips”).
 3226 
 3227 Then, you may have to recursively enable several options (which
 3228 correspond to the unmet dependencies) to finally be able to select
 3229 the package.
 3230 
 3231 If the package is not visible due to some unmet toolchain options,
 3232 then you should certainly run a full rebuild (see Section 8.1, “make
 3233 tips” for more explanations).
 3234 
 3235 11.6. Why not use the target directory as a chroot directory?
 3236 
 3237 There are plenty of reasons to not use the target directory a chroot
 3238 one, among these:
 3239 
 3240   * file ownerships, modes and permissions are not correctly set in
 3241     the target directory;
 3242   * device nodes are not created in the target directory.
 3243 
 3244 For these reasons, commands run through chroot, using the target
 3245 directory as the new root, will most likely fail.
 3246 
 3247 If you want to run the target filesystem inside a chroot, or as an
 3248 NFS root, then use the tarball image generated in images/ and extract
 3249 it as root.
 3250 
 3251 11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?
 3252 
 3253 One feature that is often discussed on the Buildroot list is the
 3254 general topic of "package management". To summarize, the idea would
 3255 be to add some tracking of which Buildroot package installs what
 3256 files, with the goals of:
 3257 
 3258   * being able to remove files installed by a package when this
 3259     package gets unselected from the menuconfig;
 3260   * being able to generate binary packages (ipk or other format) that
 3261     can be installed on the target without re-generating a new root
 3262     filesystem image.
 3263 
 3264 In general, most people think it is easy to do: just track which
 3265 package installed what and remove it when the package is unselected.
 3266 However, it is much more complicated than that:
 3267 
 3268   * It is not only about the target/ directory, but also the sysroot
 3269     in host/<tuple>/sysroot and the host/ directory itself. All files
 3270     installed in those directories by various packages must be
 3271     tracked.
 3272   * When a package is unselected from the configuration, it is not
 3273     sufficient to remove just the files it installed. One must also
 3274     remove all its reverse dependencies (i.e. packages relying on it)
 3275     and rebuild all those packages. For example, package A depends
 3276     optionally on the OpenSSL library. Both are selected, and
 3277     Buildroot is built. Package A is built with crypto support using
 3278     OpenSSL. Later on, OpenSSL gets unselected from the
 3279     configuration, but package A remains (since OpenSSL is an
 3280     optional dependency, this is possible.) If only OpenSSL files are
 3281     removed, then the files installed by package A are broken: they
 3282     use a library that is no longer present on the target. Although
 3283     this is technically doable, it adds a lot of complexity to
 3284     Buildroot, which goes against the simplicity we try to stick to.
 3285   * In addition to the previous problem, there is the case where the
 3286     optional dependency is not even known to Buildroot. For example,
 3287     package A in version 1.0 never used OpenSSL, but in version 2.0
 3288     it automatically uses OpenSSL if available. If the Buildroot .mk
 3289     file hasn’t been updated to take this into account, then package
 3290     A will not be part of the reverse dependencies of OpenSSL and
 3291     will not be removed and rebuilt when OpenSSL is removed. For
 3292     sure, the .mk file of package A should be fixed to mention this
 3293     optional dependency, but in the mean time, you can have
 3294     non-reproducible behaviors.
 3295   * The request is to also allow changes in the menuconfig to be
 3296     applied on the output directory without having to rebuild
 3297     everything from scratch. However, this is very difficult to
 3298     achieve in a reliable way: what happens when the suboptions of a
 3299     package are changed (we would have to detect this, and rebuild
 3300     the package from scratch and potentially all its reverse
 3301     dependencies), what happens if toolchain options are changed,
 3302     etc. At the moment, what Buildroot does is clear and simple so
 3303     its behaviour is very reliable and it is easy to support users.
 3304     If configuration changes done in menuconfig are applied after the
 3305     next make, then it has to work correctly and properly in all
 3306     situations, and not have some bizarre corner cases. The risk is
 3307     to get bug reports like "I have enabled package A, B and C, then
 3308     ran make, then disabled package C and enabled package D and ran
 3309     make, then re-enabled package C and enabled package E and then
 3310     there is a build failure". Or worse "I did some configuration,
 3311     then built, then did some changes, built, some more changes,
 3312     built, some more changes, built, and now it fails, but I don’t
 3313     remember all the changes I did and in which order". This will be
 3314     impossible to support.
 3315 
 3316 For all these reasons, the conclusion is that adding tracking of
 3317 installed files to remove them when the package is unselected, or to
 3318 generate a repository of binary packages, is something that is very
 3319 hard to achieve reliably and will add a lot of complexity.
 3320 
 3321 On this matter, the Buildroot developers make this position
 3322 statement:
 3323 
 3324   * Buildroot strives to make it easy to generate a root filesystem
 3325     (hence the name, by the way.) That is what we want to make
 3326     Buildroot good at: building root filesystems.
 3327   * Buildroot is not meant to be a distribution (or rather, a
 3328     distribution generator.) It is the opinion of most Buildroot
 3329     developers that this is not a goal we should pursue. We believe
 3330     that there are other tools better suited to generate a distro
 3331     than Buildroot is. For example, Open Embedded [http://
 3332     openembedded.org/], or openWRT [https://openwrt.org/], are such
 3333     tools.
 3334   * We prefer to push Buildroot in a direction that makes it easy (or
 3335     even easier) to generate complete root filesystems. This is what
 3336     makes Buildroot stands out in the crowd (among other things, of
 3337     course!)
 3338   * We believe that for most embedded Linux systems, binary packages
 3339     are not necessary, and potentially harmful. When binary packages
 3340     are used, it means that the system can be partially upgraded,
 3341     which creates an enormous number of possible combinations of
 3342     package versions that should be tested before doing the upgrade
 3343     on the embedded device. On the other hand, by doing complete
 3344     system upgrades by upgrading the entire root filesystem image at
 3345     once, the image deployed to the embedded system is guaranteed to
 3346     really be the one that has been tested and validated.
 3347 
 3348 11.8. How to speed-up the build process?
 3349 
 3350 Since Buildroot often involves doing full rebuilds of the entire
 3351 system that can be quite long, we provide below a number of tips to
 3352 help reduce the build time:
 3353 
 3354   * Use a pre-built external toolchain instead of the default
 3355     Buildroot internal toolchain. By using a pre-built Linaro
 3356     toolchain (on ARM) or a Sourcery CodeBench toolchain (for ARM,
 3357     x86, x86-64, MIPS, etc.), you will save the build time of the
 3358     toolchain at each complete rebuild, approximately 15 to 20
 3359     minutes. Note that temporarily using an external toolchain does
 3360     not prevent you to switch back to an internal toolchain (that may
 3361     provide a higher level of customization) once the rest of your
 3362     system is working;
 3363   * Use the ccache compiler cache (see: Section 8.14.3, “Using ccache
 3364     in Buildroot”);
 3365   * Learn about rebuilding only the few packages you actually care
 3366     about (see Section 8.3, “Understanding how to rebuild packages”),
 3367     but beware that sometimes full rebuilds are anyway necessary (see
 3368     Section 8.2, “Understanding when a full rebuild is necessary”);
 3369   * Make sure you are not using a virtual machine for the Linux
 3370     system used to run Buildroot. Most of the virtual machine
 3371     technologies are known to cause a significant performance impact
 3372     on I/O, which is really important for building source code;
 3373   * Make sure that you’re using only local files: do not attempt to
 3374     do a build over NFS, which significantly slows down the build.
 3375     Having the Buildroot download folder available locally also helps
 3376     a bit.
 3377   * Buy new hardware. SSDs and lots of RAM are key to speeding up the
 3378     builds.
 3379   * Experiment with top-level parallel build, see Section 8.12,
 3380     “Top-level parallel build”.
 3381 
 3382 Chapter 12. Known issues
 3383 
 3384   * It is not possible to pass extra linker options via
 3385     BR2_TARGET_LDFLAGS if such options contain a $ sign. For example,
 3386     the following is known to break: BR2_TARGET_LDFLAGS="-Wl,-rpath=
 3387     '$ORIGIN/../lib'"
 3388   * The libffi package is not supported on the SuperH 2 and ARC
 3389     architectures.
 3390   * The prboom package triggers a compiler failure with the SuperH 4
 3391     compiler from Sourcery CodeBench, version 2012.09.
 3392 
 3393 Chapter 13. Legal notice and licensing
 3394 
 3395 13.1. Complying with open source licenses
 3396 
 3397 All of the end products of Buildroot (toolchain, root filesystem,
 3398 kernel, bootloaders) contain open source software, released under
 3399 various licenses.
 3400 
 3401 Using open source software gives you the freedom to build rich
 3402 embedded systems, choosing from a wide range of packages, but also
 3403 imposes some obligations that you must know and honour. Some licenses
 3404 require you to publish the license text in the documentation of your
 3405 product. Others require you to redistribute the source code of the
 3406 software to those that receive your product.
 3407 
 3408 The exact requirements of each license are documented in each
 3409 package, and it is your responsibility (or that of your legal office)
 3410 to comply with those requirements. To make this easier for you,
 3411 Buildroot can collect for you some material you will probably need.
 3412 To produce this material, after you have configured Buildroot with
 3413 make menuconfig, make xconfig or make gconfig, run:
 3414 
 3415 make legal-info
 3416 
 3417 Buildroot will collect legally-relevant material in your output
 3418 directory, under the legal-info/ subdirectory. There you will find:
 3419 
 3420   * A README file, that summarizes the produced material and contains
 3421     warnings about material that Buildroot could not produce.
 3422   * buildroot.config: this is the Buildroot configuration file that
 3423     is usually produced with make menuconfig, and which is necessary
 3424     to reproduce the build.
 3425   * The source code for all packages; this is saved in the sources/
 3426     and host-sources/ subdirectories for target and host packages
 3427     respectively. The source code for packages that set <PKG>
 3428     _REDISTRIBUTE = NO will not be saved. Patches that were applied
 3429     are also saved, along with a file named series that lists the
 3430     patches in the order they were applied. Patches are under the
 3431     same license as the files that they modify. Note: Buildroot
 3432     applies additional patches to Libtool scripts of autotools-based
 3433     packages. These patches can be found under support/libtool in the
 3434     Buildroot source and, due to technical limitations, are not saved
 3435     with the package sources. You may need to collect them manually.
 3436   * A manifest file (one for host and one for target packages)
 3437     listing the configured packages, their version, license and
 3438     related information. Some of this information might not be
 3439     defined in Buildroot; such items are marked as "unknown".
 3440   * The license texts of all packages, in the licenses/ and
 3441     host-licenses/ subdirectories for target and host packages
 3442     respectively. If the license file(s) are not defined in
 3443     Buildroot, the file is not produced and a warning in the README
 3444     indicates this.
 3445 
 3446 Please note that the aim of the legal-info feature of Buildroot is to
 3447 produce all the material that is somehow relevant for legal
 3448 compliance with the package licenses. Buildroot does not try to
 3449 produce the exact material that you must somehow make public.
 3450 Certainly, more material is produced than is needed for a strict
 3451 legal compliance. For example, it produces the source code for
 3452 packages released under BSD-like licenses, that you are not required
 3453 to redistribute in source form.
 3454 
 3455 Moreover, due to technical limitations, Buildroot does not produce
 3456 some material that you will or may need, such as the toolchain source
 3457 code for some of the external toolchains and the Buildroot source
 3458 code itself. When you run make legal-info, Buildroot produces
 3459 warnings in the README file to inform you of relevant material that
 3460 could not be saved.
 3461 
 3462 Finally, keep in mind that the output of make legal-info is based on
 3463 declarative statements in each of the packages recipes. The Buildroot
 3464 developers try to do their best to keep those declarative statements
 3465 as accurate as possible, to the best of their knowledge. However, it
 3466 is very well possible that those declarative statements are not all
 3467 fully accurate nor exhaustive. You (or your legal department) have to
 3468 check the output of make legal-info before using it as your own
 3469 compliance delivery. See the NO WARRANTY clauses (clauses 11 and 12)
 3470 in the COPYING file at the root of the Buildroot distribution.
 3471 
 3472 13.2. Complying with the Buildroot license
 3473 
 3474 Buildroot itself is an open source software, released under the GNU
 3475 General Public License, version 2 [http://www.gnu.org/licenses/
 3476 old-licenses/gpl-2.0.html] or (at your option) any later version,
 3477 with the exception of the package patches detailed below. However,
 3478 being a build system, it is not normally part of the end product: if
 3479 you develop the root filesystem, kernel, bootloader or toolchain for
 3480 a device, the code of Buildroot is only present on the development
 3481 machine, not in the device storage.
 3482 
 3483 Nevertheless, the general view of the Buildroot developers is that
 3484 you should release the Buildroot source code along with the source
 3485 code of other packages when releasing a product that contains
 3486 GPL-licensed software. This is because the GNU GPL [http://
 3487 www.gnu.org/licenses/old-licenses/gpl-2.0.html] defines the "complete
 3488 source code" for an executable work as "all the source code for all
 3489 modules it contains, plus any associated interface definition files,
 3490 plus the scripts used to control compilation and installation of the
 3491 executable". Buildroot is part of the scripts used to control
 3492 compilation and installation of the executable, and as such it is
 3493 considered part of the material that must be redistributed.
 3494 
 3495 Keep in mind that this is only the Buildroot developers' opinion, and
 3496 you should consult your legal department or lawyer in case of any
 3497 doubt.
 3498 
 3499 13.2.1. Patches to packages
 3500 
 3501 Buildroot also bundles patch files, which are applied to the sources
 3502 of the various packages. Those patches are not covered by the license
 3503 of Buildroot. Instead, they are covered by the license of the
 3504 software to which the patches are applied. When said software is
 3505 available under multiple licenses, the Buildroot patches are only
 3506 provided under the publicly accessible licenses.
 3507 
 3508 See Chapter 19, Patching a package for the technical details.
 3509 
 3510 Chapter 14. Beyond Buildroot
 3511 
 3512 14.1. Boot the generated images
 3513 
 3514 14.1.1. NFS boot
 3515 
 3516 To achieve NFS-boot, enable tar root filesystem in the Filesystem
 3517 images menu.
 3518 
 3519 After a complete build, just run the following commands to setup the
 3520 NFS-root directory:
 3521 
 3522 sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir
 3523 
 3524 Remember to add this path to /etc/exports.
 3525 
 3526 Then, you can execute a NFS-boot from your target.
 3527 
 3528 14.1.2. Live CD
 3529 
 3530 To build a live CD image, enable the iso image option in the 
 3531 Filesystem images menu. Note that this option is only available on
 3532 the x86 and x86-64 architectures, and if you are building your kernel
 3533 with Buildroot.
 3534 
 3535 You can build a live CD image with either IsoLinux, Grub or Grub 2 as
 3536 a bootloader, but only Isolinux supports making this image usable
 3537 both as a live CD and live USB (through the Build hybrid image
 3538 option).
 3539 
 3540 You can test your live CD image using QEMU:
 3541 
 3542 qemu-system-i386 -cdrom output/images/rootfs.iso9660
 3543 
 3544 Or use it as a hard-drive image if it is a hybrid ISO:
 3545 
 3546 qemu-system-i386 -hda output/images/rootfs.iso9660
 3547 
 3548 It can be easily flashed to a USB drive with dd:
 3549 
 3550 dd if=output/images/rootfs.iso9660 of=/dev/sdb
 3551 
 3552 14.2. Chroot
 3553 
 3554 If you want to chroot in a generated image, then there are few thing
 3555 you should be aware of:
 3556 
 3557   * you should setup the new root from the tar root filesystem image;
 3558   * either the selected target architecture is compatible with your
 3559     host machine, or you should use some qemu-* binary and correctly
 3560     set it within the binfmt properties to be able to run the
 3561     binaries built for the target on your host machine;
 3562   * Buildroot does not currently provide host-qemu and binfmt
 3563     correctly built and set for that kind of use.
 3564 
 3565 Part III. Developer guide
 3566 
 3567 Table of Contents
 3568 
 3569 15. How Buildroot works
 3570 16. Coding style
 3571 
 3572     16.1. Config.in file
 3573     16.2. The .mk file
 3574     16.3. The documentation
 3575     16.4. Support scripts
 3576 
 3577 17. Adding support for a particular board
 3578 18. Adding new packages to Buildroot
 3579 
 3580     18.1. Package directory
 3581     18.2. Config files
 3582     18.3. The .mk file
 3583     18.4. The .hash file
 3584     18.5. Infrastructure for packages with specific build systems
 3585     18.6. Infrastructure for autotools-based packages
 3586     18.7. Infrastructure for CMake-based packages
 3587     18.8. Infrastructure for Python packages
 3588     18.9. Infrastructure for LuaRocks-based packages
 3589     18.10. Infrastructure for Perl/CPAN packages
 3590     18.11. Infrastructure for virtual packages
 3591     18.12. Infrastructure for packages using kconfig for
 3592         configuration files
 3593     18.13. Infrastructure for rebar-based packages
 3594     18.14. Infrastructure for Waf-based packages
 3595     18.15. Infrastructure for Meson-based packages
 3596     18.16. Integration of Cargo-based packages
 3597     18.17. Infrastructure for Go packages
 3598     18.18. Infrastructure for QMake-based packages
 3599     18.19. Infrastructure for packages building kernel modules
 3600     18.20. Infrastructure for asciidoc documents
 3601     18.21. Infrastructure specific to the Linux kernel package
 3602     18.22. Hooks available in the various build steps
 3603     18.23. Gettext integration and interaction with packages
 3604     18.24. Tips and tricks
 3605     18.25. Conclusion
 3606 
 3607 19. Patching a package
 3608 
 3609     19.1. Providing patches
 3610     19.2. How patches are applied
 3611     19.3. Format and licensing of the package patches
 3612     19.4. Integrating patches found on the Web
 3613 
 3614 20. Download infrastructure
 3615 21. Debugging Buildroot
 3616 22. Contributing to Buildroot
 3617 
 3618     22.1. Reproducing, analyzing and fixing bugs
 3619     22.2. Analyzing and fixing autobuild failures
 3620     22.3. Reviewing and testing patches
 3621     22.4. Work on items from the TODO list
 3622     22.5. Submitting patches
 3623     22.6. Reporting issues/bugs or getting help
 3624     22.7. Using the run-tests framework
 3625 
 3626 23. DEVELOPERS file and get-developers
 3627 24. Release Engineering
 3628 
 3629     24.1. Releases
 3630     24.2. Development
 3631 
 3632 Chapter 15. How Buildroot works
 3633 
 3634 As mentioned above, Buildroot is basically a set of Makefiles that
 3635 download, configure, and compile software with the correct options.
 3636 It also includes patches for various software packages - mainly the
 3637 ones involved in the cross-compilation toolchain (gcc, binutils and
 3638 uClibc).
 3639 
 3640 There is basically one Makefile per software package, and they are
 3641 named with the .mk extension. Makefiles are split into many different
 3642 parts.
 3643 
 3644   * The toolchain/ directory contains the Makefiles and associated
 3645     files for all software related to the cross-compilation
 3646     toolchain: binutils, gcc, gdb, kernel-headers and uClibc.
 3647   * The arch/ directory contains the definitions for all the
 3648     processor architectures that are supported by Buildroot.
 3649   * The package/ directory contains the Makefiles and associated
 3650     files for all user-space tools and libraries that Buildroot can
 3651     compile and add to the target root filesystem. There is one
 3652     sub-directory per package.
 3653   * The linux/ directory contains the Makefiles and associated files
 3654     for the Linux kernel.
 3655   * The boot/ directory contains the Makefiles and associated files
 3656     for the bootloaders supported by Buildroot.
 3657   * The system/ directory contains support for system integration,
 3658     e.g. the target filesystem skeleton and the selection of an init
 3659     system.
 3660   * The fs/ directory contains the Makefiles and associated files for
 3661     software related to the generation of the target root filesystem
 3662     image.
 3663 
 3664 Each directory contains at least 2 files:
 3665 
 3666   * something.mk is the Makefile that downloads, configures, compiles
 3667     and installs the package something.
 3668   * Config.in is a part of the configuration tool description file.
 3669     It describes the options related to the package.
 3670 
 3671 The main Makefile performs the following steps (once the
 3672 configuration is done):
 3673 
 3674   * Create all the output directories: staging, target, build, etc.
 3675     in the output directory (output/ by default, another value can be
 3676     specified using O=)
 3677   * Generate the toolchain target. When an internal toolchain is
 3678     used, this means generating the cross-compilation toolchain. When
 3679     an external toolchain is used, this means checking the features
 3680     of the external toolchain and importing it into the Buildroot
 3681     environment.
 3682   * Generate all the targets listed in the TARGETS variable. This
 3683     variable is filled by all the individual components' Makefiles.
 3684     Generating these targets will trigger the compilation of the
 3685     userspace packages (libraries, programs), the kernel, the
 3686     bootloader and the generation of the root filesystem images,
 3687     depending on the configuration.
 3688 
 3689 Chapter 16. Coding style
 3690 
 3691 Overall, these coding style rules are here to help you to add new
 3692 files in Buildroot or refactor existing ones.
 3693 
 3694 If you slightly modify some existing file, the important thing is to
 3695 keep the consistency of the whole file, so you can:
 3696 
 3697   * either follow the potentially deprecated coding style used in
 3698     this file,
 3699   * or entirely rework it in order to make it comply with these
 3700     rules.
 3701 
 3702 16.1. Config.in file
 3703 
 3704 Config.in files contain entries for almost anything configurable in
 3705 Buildroot.
 3706 
 3707 An entry has the following pattern:
 3708 
 3709 config BR2_PACKAGE_LIBFOO
 3710         bool "libfoo"
 3711         depends on BR2_PACKAGE_LIBBAZ
 3712         select BR2_PACKAGE_LIBBAR
 3713         help
 3714           This is a comment that explains what libfoo is. The help text
 3715           should be wrapped.
 3716 
 3717           http://foosoftware.org/libfoo/
 3718 
 3719   * The bool, depends on, select and help lines are indented with one
 3720     tab.
 3721   * The help text itself should be indented with one tab and two
 3722     spaces.
 3723   * The help text should be wrapped to fit 72 columns, where tab
 3724     counts for 8, so 62 characters in the text itself.
 3725 
 3726 The Config.in files are the input for the configuration tool used in
 3727 Buildroot, which is the regular Kconfig. For further details about
 3728 the Kconfig language, refer to http://kernel.org/doc/Documentation/
 3729 kbuild/kconfig-language.txt.
 3730 
 3731 16.2. The .mk file
 3732 
 3733   * Header: The file starts with a header. It contains the module
 3734     name, preferably in lowercase, enclosed between separators made
 3735     of 80 hashes. A blank line is mandatory after the header:
 3736 
 3737     ################################################################################
 3738     #
 3739     # libfoo
 3740     #
 3741     ################################################################################
 3742 
 3743   * Assignment: use = preceded and followed by one space:
 3744 
 3745     LIBFOO_VERSION = 1.0
 3746     LIBFOO_CONF_OPTS += --without-python-support
 3747 
 3748     Do not align the = signs.
 3749 
 3750   * Indentation: use tab only:
 3751 
 3752     define LIBFOO_REMOVE_DOC
 3753             $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
 3754                     $(TARGET_DIR)/usr/share/man/man3/libfoo*
 3755     endef
 3756 
 3757     Note that commands inside a define block should always start with
 3758     a tab, so make recognizes them as commands.
 3759 
 3760   * Optional dependency:
 3761 
 3762       + Prefer multi-line syntax.
 3763 
 3764         YES:
 3765 
 3766         ifeq ($(BR2_PACKAGE_PYTHON),y)
 3767         LIBFOO_CONF_OPTS += --with-python-support
 3768         LIBFOO_DEPENDENCIES += python
 3769         else
 3770         LIBFOO_CONF_OPTS += --without-python-support
 3771         endif
 3772 
 3773         NO:
 3774 
 3775         LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
 3776         LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
 3777 
 3778       + Keep configure options and dependencies close together.
 3779   * Optional hooks: keep hook definition and assignment together in
 3780     one if block.
 3781 
 3782     YES:
 3783 
 3784     ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 3785     define LIBFOO_REMOVE_DATA
 3786             $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 3787     endef
 3788     LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 3789     endif
 3790 
 3791     NO:
 3792 
 3793     define LIBFOO_REMOVE_DATA
 3794             $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 3795     endef
 3796 
 3797     ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 3798     LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 3799     endif
 3800 
 3801 16.3. The documentation
 3802 
 3803 The documentation uses the asciidoc [http://www.methods.co.nz/
 3804 asciidoc/] format.
 3805 
 3806 For further details about the asciidoc syntax, refer to http://
 3807 www.methods.co.nz/asciidoc/userguide.html.
 3808 
 3809 16.4. Support scripts
 3810 
 3811 Some scripts in the support/ and utils/ directories are written in
 3812 Python and should follow the PEP8 Style Guide for Python Code [https:
 3813 //www.python.org/dev/peps/pep-0008/].
 3814 
 3815 Chapter 17. Adding support for a particular board
 3816 
 3817 Buildroot contains basic configurations for several publicly
 3818 available hardware boards, so that users of such a board can easily
 3819 build a system that is known to work. You are welcome to add support
 3820 for other boards to Buildroot too.
 3821 
 3822 To do so, you need to create a normal Buildroot configuration that
 3823 builds a basic system for the hardware: (internal) toolchain, kernel,
 3824 bootloader, filesystem and a simple BusyBox-only userspace. No
 3825 specific package should be selected: the configuration should be as
 3826 minimal as possible, and should only build a working basic BusyBox
 3827 system for the target platform. You can of course use more
 3828 complicated configurations for your internal projects, but the
 3829 Buildroot project will only integrate basic board configurations.
 3830 This is because package selections are highly application-specific.
 3831 
 3832 Once you have a known working configuration, run make savedefconfig.
 3833 This will generate a minimal defconfig file at the root of the
 3834 Buildroot source tree. Move this file into the configs/ directory,
 3835 and rename it <boardname>_defconfig. If the configuration is a bit
 3836 more complicated, it is nice to manually reformat it and separate it
 3837 into sections, with a comment before each section. Typical sections
 3838 are Architecture, Toolchain options (typically just linux headers
 3839 version), Firmware, Bootloader, Kernel, and Filesystem.
 3840 
 3841 Always use fixed versions or commit hashes for the different
 3842 components, not the "latest" version. For example, set
 3843 BR2_LINUX_KERNEL_CUSTOM_VERSION=y and
 3844 BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE to the kernel version you
 3845 tested with.
 3846 
 3847 It is recommended to use as much as possible upstream versions of the
 3848 Linux kernel and bootloaders, and to use as much as possible default
 3849 kernel and bootloader configurations. If they are incorrect for your
 3850 board, or no default exists, we encourage you to send fixes to the
 3851 corresponding upstream projects.
 3852 
 3853 However, in the mean time, you may want to store kernel or bootloader
 3854 configuration or patches specific to your target platform. To do so,
 3855 create a directory board/<manufacturer> and a subdirectory board/
 3856 <manufacturer>/<boardname>. You can then store your patches and
 3857 configurations in these directories, and reference them from the main
 3858 Buildroot configuration. Refer to Chapter 9, Project-specific
 3859 customization for more details.
 3860 
 3861 Chapter 18. Adding new packages to Buildroot
 3862 
 3863 This section covers how new packages (userspace libraries or
 3864 applications) can be integrated into Buildroot. It also shows how
 3865 existing packages are integrated, which is needed for fixing issues
 3866 or tuning their configuration.
 3867 
 3868 When you add a new package, be sure to test it in various conditions
 3869 (see Section 18.24.3, “How to test your package”) and also check it
 3870 for coding style (see Section 18.24.2, “How to check the coding
 3871 style”).
 3872 
 3873 18.1. Package directory
 3874 
 3875 First of all, create a directory under the package directory for your
 3876 software, for example libfoo.
 3877 
 3878 Some packages have been grouped by topic in a sub-directory: x11r7,
 3879 qt5 and gstreamer. If your package fits in one of these categories,
 3880 then create your package directory in these. New subdirectories are
 3881 discouraged, however.
 3882 
 3883 18.2. Config files
 3884 
 3885 For the package to be displayed in the configuration tool, you need
 3886 to create a Config file in your package directory. There are two
 3887 types: Config.in and Config.in.host.
 3888 
 3889 18.2.1. Config.in file
 3890 
 3891 For packages used on the target, create a file named Config.in. This
 3892 file will contain the option descriptions related to our libfoo
 3893 software that will be used and displayed in the configuration tool.
 3894 It should basically contain:
 3895 
 3896 config BR2_PACKAGE_LIBFOO
 3897         bool "libfoo"
 3898         help
 3899           This is a comment that explains what libfoo is. The help text
 3900           should be wrapped.
 3901 
 3902           http://foosoftware.org/libfoo/
 3903 
 3904 The bool line, help line and other metadata information about the
 3905 configuration option must be indented with one tab. The help text
 3906 itself should be indented with one tab and two spaces, lines should
 3907 be wrapped to fit 72 columns, where tab counts for 8, so 62
 3908 characters in the text itself. The help text must mention the
 3909 upstream URL of the project after an empty line.
 3910 
 3911 As a convention specific to Buildroot, the ordering of the attributes
 3912 is as follows:
 3913 
 3914  1. The type of option: bool, string… with the prompt
 3915  2. If needed, the default value(s)
 3916  3. Any dependencies on the target in depends on form
 3917  4. Any dependencies on the toolchain in depends on form
 3918  5. Any dependencies on other packages in depends on form
 3919  6. Any dependency of the select form
 3920  7. The help keyword and help text.
 3921 
 3922 You can add other sub-options into a if BR2_PACKAGE_LIBFOO…endif
 3923 statement to configure particular things in your software. You can
 3924 look at examples in other packages. The syntax of the Config.in file
 3925 is the same as the one for the kernel Kconfig file. The documentation
 3926 for this syntax is available at http://kernel.org/doc/Documentation/
 3927 kbuild/kconfig-language.txt
 3928 
 3929 Finally you have to add your new libfoo/Config.in to package/
 3930 Config.in (or in a category subdirectory if you decided to put your
 3931 package in one of the existing categories). The files included there
 3932 are sorted alphabetically per category and are NOT supposed to
 3933 contain anything but the bare name of the package.
 3934 
 3935 source "package/libfoo/Config.in"
 3936 
 3937 18.2.2. Config.in.host file
 3938 
 3939 Some packages also need to be built for the host system. There are
 3940 two options here:
 3941 
 3942   * The host package is only required to satisfy build-time
 3943     dependencies of one or more target packages. In this case, add
 3944     host-foo to the target package’s BAR_DEPENDENCIES variable. No
 3945     Config.in.host file should be created.
 3946   * The host package should be explicitly selectable by the user from
 3947     the configuration menu. In this case, create a Config.in.host
 3948     file for that host package:
 3949 
 3950     config BR2_PACKAGE_HOST_FOO
 3951             bool "host foo"
 3952             help
 3953               This is a comment that explains what foo for the host is.
 3954 
 3955               http://foosoftware.org/foo/
 3956 
 3957     The same coding style and options as for the Config.in file are
 3958     valid.
 3959 
 3960     Finally you have to add your new libfoo/Config.in.host to package
 3961     /Config.in.host. The files included there are sorted
 3962     alphabetically and are NOT supposed to contain anything but the 
 3963     bare name of the package.
 3964 
 3965     source "package/foo/Config.in.host"
 3966 
 3967     The host package will then be available from the Host utilities
 3968     menu.
 3969 
 3970 18.2.3. Choosing depends on or select
 3971 
 3972 The Config.in file of your package must also ensure that dependencies
 3973 are enabled. Typically, Buildroot uses the following rules:
 3974 
 3975   * Use a select type of dependency for dependencies on libraries.
 3976     These dependencies are generally not obvious and it therefore
 3977     make sense to have the kconfig system ensure that the
 3978     dependencies are selected. For example, the libgtk2 package uses
 3979     select BR2_PACKAGE_LIBGLIB2 to make sure this library is also
 3980     enabled. The select keyword expresses the dependency with a
 3981     backward semantic.
 3982   * Use a depends on type of dependency when the user really needs to
 3983     be aware of the dependency. Typically, Buildroot uses this type
 3984     of dependency for dependencies on target architecture, MMU
 3985     support and toolchain options (see Section 18.2.4, “Dependencies
 3986     on target and toolchain options”), or for dependencies on "big"
 3987     things, such as the X.org system. The depends on keyword
 3988     expresses the dependency with a forward semantic.
 3989 
 3990 Note. The current problem with the kconfig language is that these two
 3991 dependency semantics are not internally linked. Therefore, it may be
 3992 possible to select a package, whom one of its dependencies/
 3993 requirement is not met.
 3994 
 3995 An example illustrates both the usage of select and depends on.
 3996 
 3997 config BR2_PACKAGE_RRDTOOL
 3998         bool "rrdtool"
 3999         depends on BR2_USE_WCHAR
 4000         select BR2_PACKAGE_FREETYPE
 4001         select BR2_PACKAGE_LIBART
 4002         select BR2_PACKAGE_LIBPNG
 4003         select BR2_PACKAGE_ZLIB
 4004         help
 4005           RRDtool is the OpenSource industry standard, high performance
 4006           data logging and graphing system for time series data.
 4007 
 4008           http://oss.oetiker.ch/rrdtool/
 4009 
 4010 comment "rrdtool needs a toolchain w/ wchar"
 4011         depends on !BR2_USE_WCHAR
 4012 
 4013 Note that these two dependency types are only transitive with the
 4014 dependencies of the same kind.
 4015 
 4016 This means, in the following example:
 4017 
 4018 config BR2_PACKAGE_A
 4019         bool "Package A"
 4020 
 4021 config BR2_PACKAGE_B
 4022         bool "Package B"
 4023         depends on BR2_PACKAGE_A
 4024 
 4025 config BR2_PACKAGE_C
 4026         bool "Package C"
 4027         depends on BR2_PACKAGE_B
 4028 
 4029 config BR2_PACKAGE_D
 4030         bool "Package D"
 4031         select BR2_PACKAGE_B
 4032 
 4033 config BR2_PACKAGE_E
 4034         bool "Package E"
 4035         select BR2_PACKAGE_D
 4036 
 4037   * Selecting Package C will be visible if Package B has been
 4038     selected, which in turn is only visible if Package A has been
 4039     selected.
 4040   * Selecting Package E will select Package D, which will select
 4041     Package B, it will not check for the dependencies of Package B,
 4042     so it will not select Package A.
 4043   * Since Package B is selected but Package A is not, this violates
 4044     the dependency of Package B on Package A. Therefore, in such a
 4045     situation, the transitive dependency has to be added explicitly:
 4046 
 4047 config BR2_PACKAGE_D
 4048         bool "Package D"
 4049         select BR2_PACKAGE_B
 4050         depends on BR2_PACKAGE_A
 4051 
 4052 config BR2_PACKAGE_E
 4053         bool "Package E"
 4054         select BR2_PACKAGE_D
 4055         depends on BR2_PACKAGE_A
 4056 
 4057 Overall, for package library dependencies, select should be
 4058 preferred.
 4059 
 4060 Note that such dependencies will ensure that the dependency option is
 4061 also enabled, but not necessarily built before your package. To do
 4062 so, the dependency also needs to be expressed in the .mk file of the
 4063 package.
 4064 
 4065 Further formatting details: see the coding style.
 4066 
 4067 18.2.4. Dependencies on target and toolchain options
 4068 
 4069 Many packages depend on certain options of the toolchain: the choice
 4070 of C library, C++ support, thread support, RPC support, wchar
 4071 support, or dynamic library support. Some packages can only be built
 4072 on certain target architectures, or if an MMU is available in the
 4073 processor.
 4074 
 4075 These dependencies have to be expressed with the appropriate depends
 4076 on statements in the Config.in file. Additionally, for dependencies
 4077 on toolchain options, a comment should be displayed when the option
 4078 is not enabled, so that the user knows why the package is not
 4079 available. Dependencies on target architecture or MMU support should
 4080 not be made visible in a comment: since it is unlikely that the user
 4081 can freely choose another target, it makes little sense to show these
 4082 dependencies explicitly.
 4083 
 4084 The comment should only be visible if the config option itself would
 4085 be visible when the toolchain option dependencies are met. This means
 4086 that all other dependencies of the package (including dependencies on
 4087 target architecture and MMU support) have to be repeated on the
 4088 comment definition. To keep it clear, the depends on statement for
 4089 these non-toolchain option should be kept separate from the depends
 4090 on statement for the toolchain options. If there is a dependency on a
 4091 config option in that same file (typically the main package) it is
 4092 preferable to have a global if … endif construct rather than
 4093 repeating the depends on statement on the comment and other config
 4094 options.
 4095 
 4096 The general format of a dependency comment for package foo is:
 4097 
 4098 foo needs a toolchain w/ featA, featB, featC
 4099 
 4100 for example:
 4101 
 4102 mpd needs a toolchain w/ C++, threads, wchar
 4103 
 4104 or
 4105 
 4106 crda needs a toolchain w/ threads
 4107 
 4108 Note that this text is kept brief on purpose, so that it will fit on
 4109 a 80-character terminal.
 4110 
 4111 The rest of this section enumerates the different target and
 4112 toolchain options, the corresponding config symbols to depend on, and
 4113 the text to use in the comment.
 4114 
 4115   * Target architecture
 4116 
 4117       + Dependency symbol: BR2_powerpc, BR2_mips, … (see arch/
 4118         Config.in)
 4119       + Comment string: no comment to be added
 4120   * MMU support
 4121 
 4122       + Dependency symbol: BR2_USE_MMU
 4123       + Comment string: no comment to be added
 4124   * Gcc _sync* built-ins used for atomic operations. They are
 4125     available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
 4126     bytes. Since different architectures support atomic operations on
 4127     different sizes, one dependency symbol is available for each
 4128     size:
 4129 
 4130       + Dependency symbol: BR2_TOOLCHAIN_HAS_SYNC_1 for 1 byte,
 4131         BR2_TOOLCHAIN_HAS_SYNC_2 for 2 bytes,
 4132         BR2_TOOLCHAIN_HAS_SYNC_4 for 4 bytes,
 4133         BR2_TOOLCHAIN_HAS_SYNC_8 for 8 bytes.
 4134       + Comment string: no comment to be added
 4135   * Gcc _atomic* built-ins used for atomic operations.
 4136 
 4137       + Dependency symbol: BR2_TOOLCHAIN_HAS_ATOMIC.
 4138       + Comment string: no comment to be added
 4139   * Kernel headers
 4140 
 4141       + Dependency symbol: BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y,
 4142         (replace X_Y with the proper version, see toolchain/
 4143         Config.in)
 4144       + Comment string: headers >= X.Y and/or headers <= X.Y (replace
 4145         X.Y with the proper version)
 4146   * GCC version
 4147 
 4148       + Dependency symbol: BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y, (replace
 4149         X_Y with the proper version, see toolchain/Config.in)
 4150       + Comment string: gcc >= X.Y and/or gcc <= X.Y (replace X.Y
 4151         with the proper version)
 4152   * Host GCC version
 4153 
 4154       + Dependency symbol: BR2_HOST_GCC_AT_LEAST_X_Y, (replace X_Y
 4155         with the proper version, see Config.in)
 4156       + Comment string: no comment to be added
 4157       + Note that it is usually not the package itself that has a
 4158         minimum host GCC version, but rather a host-package on which
 4159         it depends.
 4160   * C library
 4161 
 4162       + Dependency symbol: BR2_TOOLCHAIN_USES_GLIBC,
 4163         BR2_TOOLCHAIN_USES_MUSL, BR2_TOOLCHAIN_USES_UCLIBC
 4164       + Comment string: for the C library, a slightly different
 4165         comment text is used: foo needs a glibc toolchain, or foo
 4166         needs a glibc toolchain w/ C++
 4167   * C++ support
 4168 
 4169       + Dependency symbol: BR2_INSTALL_LIBSTDCPP
 4170       + Comment string: C++
 4171   * D support
 4172 
 4173       + Dependency symbol: BR2_TOOLCHAIN_HAS_DLANG
 4174       + Comment string: Dlang
 4175   * Fortran support
 4176 
 4177       + Dependency symbol: BR2_TOOLCHAIN_HAS_FORTRAN
 4178       + Comment string: fortran
 4179   * thread support
 4180 
 4181       + Dependency symbol: BR2_TOOLCHAIN_HAS_THREADS
 4182       + Comment string: threads (unless
 4183         BR2_TOOLCHAIN_HAS_THREADS_NPTL is also needed, in which case,
 4184         specifying only NPTL is sufficient)
 4185   * NPTL thread support
 4186 
 4187       + Dependency symbol: BR2_TOOLCHAIN_HAS_THREADS_NPTL
 4188       + Comment string: NPTL
 4189   * RPC support
 4190 
 4191       + Dependency symbol: BR2_TOOLCHAIN_HAS_NATIVE_RPC
 4192       + Comment string: RPC
 4193   * wchar support
 4194 
 4195       + Dependency symbol: BR2_USE_WCHAR
 4196       + Comment string: wchar
 4197   * dynamic library
 4198 
 4199       + Dependency symbol: !BR2_STATIC_LIBS
 4200       + Comment string: dynamic library
 4201 
 4202 18.2.5. Dependencies on a Linux kernel built by buildroot
 4203 
 4204 Some packages need a Linux kernel to be built by buildroot. These are
 4205 typically kernel modules or firmware. A comment should be added in
 4206 the Config.in file to express this dependency, similar to
 4207 dependencies on toolchain options. The general format is:
 4208 
 4209 foo needs a Linux kernel to be built
 4210 
 4211 If there is a dependency on both toolchain options and the Linux
 4212 kernel, use this format:
 4213 
 4214 foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built
 4215 
 4216 18.2.6. Dependencies on udev /dev management
 4217 
 4218 If a package needs udev /dev management, it should depend on symbol
 4219 BR2_PACKAGE_HAS_UDEV, and the following comment should be added:
 4220 
 4221 foo needs udev /dev management
 4222 
 4223 If there is a dependency on both toolchain options and udev /dev
 4224 management, use this format:
 4225 
 4226 foo needs udev /dev management and a toolchain w/ featA, featB, featC
 4227 
 4228 18.2.7. Dependencies on features provided by virtual packages
 4229 
 4230 Some features can be provided by more than one package, such as the
 4231 openGL libraries.
 4232 
 4233 See Section 18.11, “Infrastructure for virtual packages” for more on
 4234 the virtual packages.
 4235 
 4236 18.3. The .mk file
 4237 
 4238 Finally, here’s the hardest part. Create a file named libfoo.mk. It
 4239 describes how the package should be downloaded, configured, built,
 4240 installed, etc.
 4241 
 4242 Depending on the package type, the .mk file must be written in a
 4243 different way, using different infrastructures:
 4244 
 4245   * Makefiles for generic packages (not using autotools or CMake):
 4246     These are based on an infrastructure similar to the one used for
 4247     autotools-based packages, but require a little more work from the
 4248     developer. They specify what should be done for the
 4249     configuration, compilation and installation of the package. This
 4250     infrastructure must be used for all packages that do not use the
 4251     autotools as their build system. In the future, other specialized
 4252     infrastructures might be written for other build systems. We
 4253     cover them through in a tutorial and a reference.
 4254   * Makefiles for autotools-based software (autoconf, automake,
 4255     etc.): We provide a dedicated infrastructure for such packages,
 4256     since autotools is a very common build system. This
 4257     infrastructure must be used for new packages that rely on the
 4258     autotools as their build system. We cover them through a tutorial
 4259     and reference.
 4260   * Makefiles for cmake-based software: We provide a dedicated
 4261     infrastructure for such packages, as CMake is a more and more
 4262     commonly used build system and has a standardized behaviour. This
 4263     infrastructure must be used for new packages that rely on CMake.
 4264     We cover them through a tutorial and reference.
 4265   * Makefiles for Python modules: We have a dedicated infrastructure
 4266     for Python modules that use either the distutils or the
 4267     setuptools mechanism. We cover them through a tutorial and a
 4268     reference.
 4269   * Makefiles for Lua modules: We have a dedicated infrastructure for
 4270     Lua modules available through the LuaRocks web site. We cover
 4271     them through a tutorial and a reference.
 4272 
 4273 Further formatting details: see the writing rules.
 4274 
 4275 18.4. The .hash file
 4276 
 4277 When possible, you must add a third file, named libfoo.hash, that
 4278 contains the hashes of the downloaded files for the libfoo package.
 4279 The only reason for not adding a .hash file is when hash checking is
 4280 not possible due to how the package is downloaded.
 4281 
 4282 When a package has a version selection choice, then the hash file may
 4283 be stored in a subdirectory named after the version, e.g. package/
 4284 libfoo/1.2.3/libfoo.hash. This is especially important if the
 4285 different versions have different licensing terms, but they are
 4286 stored in the same file. Otherwise, the hash file should stay in the
 4287 package’s directory.
 4288 
 4289 The hashes stored in that file are used to validate the integrity of
 4290 the downloaded files and of the license files.
 4291 
 4292 The format of this file is one line for each file for which to check
 4293 the hash, each line with the following three fields separated by two
 4294 spaces:
 4295 
 4296   * the type of hash, one of:
 4297 
 4298       + md5, sha1, sha224, sha256, sha384, sha512, none
 4299   * the hash of the file:
 4300 
 4301       + for none, one or more non-space chars, usually just the
 4302         string xxx
 4303       + for md5, 32 hexadecimal characters
 4304       + for sha1, 40 hexadecimal characters
 4305       + for sha224, 56 hexadecimal characters
 4306       + for sha256, 64 hexadecimal characters
 4307       + for sha384, 96 hexadecimal characters
 4308       + for sha512, 128 hexadecimal characters
 4309   * the name of the file:
 4310 
 4311       + for a source archive: the basename of the file, without any
 4312         directory component,
 4313       + for a license file: the path as it appears in
 4314         FOO_LICENSE_FILES.
 4315 
 4316 Lines starting with a # sign are considered comments, and ignored.
 4317 Empty lines are ignored.
 4318 
 4319 There can be more than one hash for a single file, each on its own
 4320 line. In this case, all hashes must match.
 4321 
 4322 Note. Ideally, the hashes stored in this file should match the hashes
 4323 published by upstream, e.g. on their website, in the e-mail
 4324 announcement… If upstream provides more than one type of hash (e.g.
 4325 sha1 and sha512), then it is best to add all those hashes in the
 4326 .hash file. If upstream does not provide any hash, or only provides
 4327 an md5 hash, then compute at least one strong hash yourself
 4328 (preferably sha256, but not md5), and mention this in a comment line
 4329 above the hashes.
 4330 
 4331 Note. The hashes for license files are used to detect a license
 4332 change when a package version is bumped. The hashes are checked
 4333 during the make legal-info target run. For a package with multiple
 4334 versions (like Qt5), create the hash file in a subdirectory
 4335 <packageversion> of that package (see also Section 19.2, “How patches
 4336 are applied”).
 4337 
 4338 The none hash type is reserved to those archives downloaded from a
 4339 repository, like a git clone, a subversion checkout…
 4340 
 4341 The example below defines a sha1 and a sha256 published by upstream
 4342 for the main libfoo-1.2.3.tar.bz2 tarball, an md5 from upstream and a
 4343 locally-computed sha256 hashes for a binary blob, a sha256 for a
 4344 downloaded patch, and an archive with no hash:
 4345 
 4346 # Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
 4347 sha1  486fb55c3efa71148fe07895fd713ea3a5ae343a  libfoo-1.2.3.tar.bz2
 4348 sha256  efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369  libfoo-1.2.3.tar.bz2
 4349 
 4350 # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
 4351 md5  2d608f3c318c6b7557d551a5a09314f03452f1a1  libfoo-data.bin
 4352 sha256  01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b  libfoo-data.bin
 4353 
 4354 # Locally computed:
 4355 sha256  ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9  libfoo-fix-blabla.patch
 4356 
 4357 # No hash for 1234:
 4358 none  xxx  libfoo-1234.tar.gz
 4359 
 4360 # Hash for license files:
 4361 sha256  a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8  COPYING
 4362 sha256  01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55  doc/COPYING.LGPL
 4363 
 4364 If the .hash file is present, and it contains one or more hashes for
 4365 a downloaded file, the hash(es) computed by Buildroot (after
 4366 download) must match the hash(es) stored in the .hash file. If one or
 4367 more hashes do not match, Buildroot considers this an error, deletes
 4368 the downloaded file, and aborts.
 4369 
 4370 If the .hash file is present, but it does not contain a hash for a
 4371 downloaded file, Buildroot considers this an error and aborts.
 4372 However, the downloaded file is left in the download directory since
 4373 this typically indicates that the .hash file is wrong but the
 4374 downloaded file is probably OK.
 4375 
 4376 Hashes are currently checked for files fetched from http/ftp servers,
 4377 Git repositories, files copied using scp and local files. Hashes are
 4378 not checked for other version control systems (such as Subversion,
 4379 CVS, etc.) because Buildroot currently does not generate reproducible
 4380 tarballs when source code is fetched from such version control
 4381 systems.
 4382 
 4383 Hashes should only be added in .hash files for files that are
 4384 guaranteed to be stable. For example, patches auto-generated by
 4385 Github are not guaranteed to be stable, and therefore their hashes
 4386 can change over time. Such patches should not be downloaded, and
 4387 instead be added locally to the package folder.
 4388 
 4389 If the .hash file is missing, then no check is done at all.
 4390 
 4391 18.5. Infrastructure for packages with specific build systems
 4392 
 4393 By packages with specific build systems we mean all the packages
 4394 whose build system is not one of the standard ones, such as autotools
 4395 or CMake. This typically includes packages whose build system is
 4396 based on hand-written Makefiles or shell scripts.
 4397 
 4398 18.5.1. generic-package tutorial
 4399 
 4400 01: ################################################################################
 4401 02: #
 4402 03: # libfoo
 4403 04: #
 4404 05: ################################################################################
 4405 06:
 4406 07: LIBFOO_VERSION = 1.0
 4407 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 4408 09: LIBFOO_SITE = http://www.foosoftware.org/download
 4409 10: LIBFOO_LICENSE = GPL-3.0+
 4410 11: LIBFOO_LICENSE_FILES = COPYING
 4411 12: LIBFOO_INSTALL_STAGING = YES
 4412 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
 4413 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
 4414 15:
 4415 16: define LIBFOO_BUILD_CMDS
 4416 17:     $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
 4417 18: endef
 4418 19:
 4419 20: define LIBFOO_INSTALL_STAGING_CMDS
 4420 21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
 4421 22:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
 4422 23:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
 4423 24: endef
 4424 25:
 4425 26: define LIBFOO_INSTALL_TARGET_CMDS
 4426 27:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
 4427 28:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
 4428 29: endef
 4429 30:
 4430 31: define LIBFOO_USERS
 4431 32:     foo -1 libfoo -1 * - - - LibFoo daemon
 4432 33: endef
 4433 34:
 4434 35: define LIBFOO_DEVICES
 4435 36:     /dev/foo  c  666  0  0  42  0  -  -  -
 4436 37: endef
 4437 38:
 4438 39: define LIBFOO_PERMISSIONS
 4439 40:     /bin/foo  f  4755  foo  libfoo   -  -  -  -  -
 4440 41: endef
 4441 42:
 4442 43: $(eval $(generic-package))
 4443 
 4444 The Makefile begins on line 7 to 11 with metadata information: the
 4445 version of the package (LIBFOO_VERSION), the name of the tarball
 4446 containing the package (LIBFOO_SOURCE) (xz-ed tarball recommended)
 4447 the Internet location at which the tarball can be downloaded from
 4448 (LIBFOO_SITE), the license (LIBFOO_LICENSE) and file with the license
 4449 text (LIBFOO_LICENSE_FILES). All variables must start with the same
 4450 prefix, LIBFOO_ in this case. This prefix is always the uppercased
 4451 version of the package name (see below to understand where the
 4452 package name is defined).
 4453 
 4454 On line 12, we specify that this package wants to install something
 4455 to the staging space. This is often needed for libraries, since they
 4456 must install header files and other development files in the staging
 4457 space. This will ensure that the commands listed in the
 4458 LIBFOO_INSTALL_STAGING_CMDS variable will be executed.
 4459 
 4460 On line 13, we specify that there is some fixing to be done to some
 4461 of the libfoo-config files that were installed during
 4462 LIBFOO_INSTALL_STAGING_CMDS phase. These *-config files are
 4463 executable shell script files that are located in $(STAGING_DIR)/usr/
 4464 bin directory and are executed by other 3rd party packages to find
 4465 out the location and the linking flags of this particular package.
 4466 
 4467 The problem is that all these *-config files by default give wrong,
 4468 host system linking flags that are unsuitable for cross-compiling.
 4469 
 4470 For example: -I/usr/include instead of -I$(STAGING_DIR)/usr/include
 4471 or: -L/usr/lib instead of -L$(STAGING_DIR)/usr/lib
 4472 
 4473 So some sed magic is done to these scripts to make them give correct
 4474 flags. The argument to be given to LIBFOO_CONFIG_SCRIPTS is the file
 4475 name(s) of the shell script(s) needing fixing. All these names are
 4476 relative to $(STAGING_DIR)/usr/bin and if needed multiple names can
 4477 be given.
 4478 
 4479 In addition, the scripts listed in LIBFOO_CONFIG_SCRIPTS are removed
 4480 from $(TARGET_DIR)/usr/bin, since they are not needed on the target.
 4481 
 4482 Example 18.1. Config script: divine package
 4483 
 4484 Package divine installs shell script $(STAGING_DIR)/usr/bin/
 4485 divine-config.
 4486 
 4487 So its fixup would be:
 4488 
 4489 DIVINE_CONFIG_SCRIPTS = divine-config
 4490 
 4491 
 4492 Example 18.2. Config script: imagemagick package:
 4493 
 4494 Package imagemagick installs the following scripts: $(STAGING_DIR)/
 4495 usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config
 4496 
 4497 So it’s fixup would be:
 4498 
 4499 IMAGEMAGICK_CONFIG_SCRIPTS = \
 4500    Magick-config Magick++-config \
 4501    MagickCore-config MagickWand-config Wand-config
 4502 
 4503 
 4504 On line 14, we specify the list of dependencies this package relies
 4505 on. These dependencies are listed in terms of lower-case package
 4506 names, which can be packages for the target (without the host-
 4507 prefix) or packages for the host (with the host-) prefix). Buildroot
 4508 will ensure that all these packages are built and installed before
 4509 the current package starts its configuration.
 4510 
 4511 The rest of the Makefile, lines 16..29, defines what should be done
 4512 at the different steps of the package configuration, compilation and
 4513 installation. LIBFOO_BUILD_CMDS tells what steps should be performed
 4514 to build the package. LIBFOO_INSTALL_STAGING_CMDS tells what steps
 4515 should be performed to install the package in the staging space.
 4516 LIBFOO_INSTALL_TARGET_CMDS tells what steps should be performed to
 4517 install the package in the target space.
 4518 
 4519 All these steps rely on the $(@D) variable, which contains the
 4520 directory where the source code of the package has been extracted.
 4521 
 4522 On lines 31..33, we define a user that is used by this package (e.g.
 4523 to run a daemon as non-root) (LIBFOO_USERS).
 4524 
 4525 On line 35..37, we define a device-node file used by this package
 4526 (LIBFOO_DEVICES).
 4527 
 4528 On line 39..41, we define the permissions to set to specific files
 4529 installed by this package (LIBFOO_PERMISSIONS).
 4530 
 4531 Finally, on line 43, we call the generic-package function, which
 4532 generates, according to the variables defined previously, all the
 4533 Makefile code necessary to make your package working.
 4534 
 4535 18.5.2. generic-package reference
 4536 
 4537 There are two variants of the generic target. The generic-package
 4538 macro is used for packages to be cross-compiled for the target. The
 4539 host-generic-package macro is used for host packages, natively
 4540 compiled for the host. It is possible to call both of them in a
 4541 single .mk file: once to create the rules to generate a target
 4542 package and once to create the rules to generate a host package:
 4543 
 4544 $(eval $(generic-package))
 4545 $(eval $(host-generic-package))
 4546 
 4547 This might be useful if the compilation of the target package
 4548 requires some tools to be installed on the host. If the package name
 4549 is libfoo, then the name of the package for the target is also
 4550 libfoo, while the name of the package for the host is host-libfoo.
 4551 These names should be used in the DEPENDENCIES variables of other
 4552 packages, if they depend on libfoo or host-libfoo.
 4553 
 4554 The call to the generic-package and/or host-generic-package macro 
 4555 must be at the end of the .mk file, after all variable definitions.
 4556 The call to host-generic-package must be after the call to
 4557 generic-package, if any.
 4558 
 4559 For the target package, the generic-package uses the variables
 4560 defined by the .mk file and prefixed by the uppercased package name:
 4561 LIBFOO_*. host-generic-package uses the HOST_LIBFOO_* variables. For 
 4562 some variables, if the HOST_LIBFOO_ prefixed variable doesn’t exist,
 4563 the package infrastructure uses the corresponding variable prefixed
 4564 by LIBFOO_. This is done for variables that are likely to have the
 4565 same value for both the target and host packages. See below for
 4566 details.
 4567 
 4568 The list of variables that can be set in a .mk file to give metadata
 4569 information is (assuming the package name is libfoo) :
 4570 
 4571   * LIBFOO_VERSION, mandatory, must contain the version of the
 4572     package. Note that if HOST_LIBFOO_VERSION doesn’t exist, it is
 4573     assumed to be the same as LIBFOO_VERSION. It can also be a
 4574     revision number or a tag for packages that are fetched directly
 4575     from their version control system. Examples:
 4576 
 4577       + a version for a release tarball: LIBFOO_VERSION = 0.1.2
 4578       + a sha1 for a git tree: LIBFOO_VERSION =
 4579         cb9d6aa9429e838f0e54faa3d455bcbab5eef057
 4580       + a tag for a git tree LIBFOO_VERSION = v0.1.2
 4581 
 4582         Note: Using a branch name as FOO_VERSION is not supported,
 4583         because it does not and can not work as people would expect
 4584         it should:
 4585 
 4586          1. due to local caching, Buildroot will not re-fetch the
 4587             repository, so people who expect to be able to follow the
 4588             remote repository would be quite surprised and
 4589             disappointed;
 4590          2. because two builds can never be perfectly simultaneous,
 4591             and because the remote repository may get new commits on
 4592             the branch anytime, two users, using the same Buildroot
 4593             tree and building the same configuration, may get
 4594             different source, thus rendering the build non
 4595             reproducible, and people would be quite surprised and
 4596             disappointed.
 4597   * LIBFOO_SOURCE may contain the name of the tarball of the package,
 4598     which Buildroot will use to download the tarball from
 4599     LIBFOO_SITE. If HOST_LIBFOO_SOURCE is not specified, it defaults
 4600     to LIBFOO_SOURCE. If none are specified, then the value is
 4601     assumed to be libfoo-$(LIBFOO_VERSION).tar.gz. Example:
 4602     LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2
 4603   * LIBFOO_PATCH may contain a space-separated list of patch file
 4604     names, that Buildroot will download and apply to the package
 4605     source code. If an entry contains ://, then Buildroot will assume
 4606     it is a full URL and download the patch from this location.
 4607     Otherwise, Buildroot will assume that the patch should be
 4608     downloaded from LIBFOO_SITE. If HOST_LIBFOO_PATCH is not
 4609     specified, it defaults to LIBFOO_PATCH. Note that patches that
 4610     are included in Buildroot itself use a different mechanism: all
 4611     files of the form *.patch present in the package directory inside
 4612     Buildroot will be applied to the package after extraction (see
 4613     patching a package). Finally, patches listed in the LIBFOO_PATCH
 4614     variable are applied before the patches stored in the Buildroot
 4615     package directory.
 4616   * LIBFOO_SITE provides the location of the package, which can be a
 4617     URL or a local filesystem path. HTTP, FTP and SCP are supported
 4618     URL types for retrieving package tarballs. In these cases don’t
 4619     include a trailing slash: it will be added by Buildroot between
 4620     the directory and the filename as appropriate. Git, Subversion,
 4621     Mercurial, and Bazaar are supported URL types for retrieving
 4622     packages directly from source code management systems. There is a
 4623     helper function to make it easier to download source tarballs
 4624     from GitHub (refer to Section 18.24.4, “How to add a package from
 4625     GitHub” for details). A filesystem path may be used to specify
 4626     either a tarball or a directory containing the package source
 4627     code. See LIBFOO_SITE_METHOD below for more details on how
 4628     retrieval works. Note that SCP URLs should be of the form scp://
 4629     [user@]host:filepath, and that filepath is relative to the user’s
 4630     home directory, so you may want to prepend the path with a slash
 4631     for absolute paths: scp://[user@]host:/absolutepath. If
 4632     HOST_LIBFOO_SITE is not specified, it defaults to LIBFOO_SITE.
 4633     Examples: LIBFOO_SITE=http://www.libfoosoftware.org/libfoo
 4634     LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor LIBFOO_SITE=/opt/
 4635     software/libfoo.tar.gz LIBFOO_SITE=$(TOPDIR)/../src/libfoo
 4636   * LIBFOO_DL_OPTS is a space-separated list of additional options to
 4637     pass to the downloader. Useful for retrieving documents with
 4638     server-side checking for user logins and passwords, or to use a
 4639     proxy. All download methods valid for LIBFOO_SITE_METHOD are
 4640     supported; valid options depend on the download method (consult
 4641     the man page for the respective download utilities).
 4642   * LIBFOO_EXTRA_DOWNLOADS is a space-separated list of additional
 4643     files that Buildroot should download. If an entry contains ://
 4644     then Buildroot will assume it is a complete URL and will download
 4645     the file using this URL. Otherwise, Buildroot will assume the
 4646     file to be downloaded is located at LIBFOO_SITE. Buildroot will
 4647     not do anything with those additional files, except download
 4648     them: it will be up to the package recipe to use them from $
 4649     (LIBFOO_DL_DIR).
 4650   * LIBFOO_SITE_METHOD determines the method used to fetch or copy
 4651     the package source code. In many cases, Buildroot guesses the
 4652     method from the contents of LIBFOO_SITE and setting
 4653     LIBFOO_SITE_METHOD is unnecessary. When HOST_LIBFOO_SITE_METHOD
 4654     is not specified, it defaults to the value of LIBFOO_SITE_METHOD.
 4655     The possible values of LIBFOO_SITE_METHOD are:
 4656 
 4657       + wget for normal FTP/HTTP downloads of tarballs. Used by
 4658         default when LIBFOO_SITE begins with http://, https:// or
 4659         ftp://.
 4660       + scp for downloads of tarballs over SSH with scp. Used by
 4661         default when LIBFOO_SITE begins with scp://.
 4662       + svn for retrieving source code from a Subversion repository.
 4663         Used by default when LIBFOO_SITE begins with svn://. When a
 4664         http:// Subversion repository URL is specified in
 4665         LIBFOO_SITE, one must specify LIBFOO_SITE_METHOD=svn.
 4666         Buildroot performs a checkout which is preserved as a tarball
 4667         in the download cache; subsequent builds use the tarball
 4668         instead of performing another checkout.
 4669       + cvs for retrieving source code from a CVS repository. Used by
 4670         default when LIBFOO_SITE begins with cvs://. The downloaded
 4671         source code is cached as with the svn method. Anonymous
 4672         pserver mode is assumed otherwise explicitly defined on
 4673         LIBFOO_SITE. Both LIBFOO_SITE=cvs://libfoo.net:/cvsroot/
 4674         libfoo and LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo
 4675         are accepted, on the former anonymous pserver access mode is
 4676         assumed. LIBFOO_SITE must contain the source URL as well as
 4677         the remote repository directory. The module is the package
 4678         name. LIBFOO_VERSION is mandatory and must be a tag, a
 4679         branch, or a date (e.g. "2014-10-20", "2014-10-20 13:45",
 4680         "2014-10-20 13:45+01" see "man cvs" for further details).
 4681       + git for retrieving source code from a Git repository. Used by
 4682         default when LIBFOO_SITE begins with git://. The downloaded
 4683         source code is cached as with the svn method.
 4684       + hg for retrieving source code from a Mercurial repository.
 4685         One must specify LIBFOO_SITE_METHOD=hg when LIBFOO_SITE
 4686         contains a Mercurial repository URL. The downloaded source
 4687         code is cached as with the svn method.
 4688       + bzr for retrieving source code from a Bazaar repository. Used
 4689         by default when LIBFOO_SITE begins with bzr://. The
 4690         downloaded source code is cached as with the svn method.
 4691       + file for a local tarball. One should use this when
 4692         LIBFOO_SITE specifies a package tarball as a local filename.
 4693         Useful for software that isn’t available publicly or in
 4694         version control.
 4695       + local for a local source code directory. One should use this
 4696         when LIBFOO_SITE specifies a local directory path containing
 4697         the package source code. Buildroot copies the contents of the
 4698         source directory into the package’s build directory. Note
 4699         that for local packages, no patches are applied. If you need
 4700         to still patch the source code, use LIBFOO_POST_RSYNC_HOOKS,
 4701         see Section 18.22.1, “Using the POST_RSYNC hook”.
 4702   * LIBFOO_GIT_SUBMODULES can be set to YES to create an archive with
 4703     the git submodules in the repository. This is only available for
 4704     packages downloaded with git (i.e. when LIBFOO_SITE_METHOD=git).
 4705     Note that we try not to use such git submodules when they contain
 4706     bundled libraries, in which case we prefer to use those libraries
 4707     from their own package.
 4708   * LIBFOO_STRIP_COMPONENTS is the number of leading components
 4709     (directories) that tar must strip from file names on extraction.
 4710     The tarball for most packages has one leading component named "
 4711     <pkg-name>-<pkg-version>", thus Buildroot passes
 4712     --strip-components=1 to tar to remove it. For non-standard
 4713     packages that don’t have this component, or that have more than
 4714     one leading component to strip, set this variable with the value
 4715     to be passed to tar. Default: 1.
 4716   * LIBFOO_EXCLUDES is a space-separated list of patterns to exclude
 4717     when extracting the archive. Each item from that list is passed
 4718     as a tar’s --exclude option. By default, empty.
 4719   * LIBFOO_DEPENDENCIES lists the dependencies (in terms of package
 4720     name) that are required for the current target package to
 4721     compile. These dependencies are guaranteed to be compiled and
 4722     installed before the configuration of the current package starts.
 4723     However, modifications to configuration of these dependencies
 4724     will not force a rebuild of the current package. In a similar
 4725     way, HOST_LIBFOO_DEPENDENCIES lists the dependencies for the
 4726     current host package.
 4727   * LIBFOO_EXTRACT_DEPENDENCIES lists the dependencies (in terms of
 4728     package name) that are required for the current target package to
 4729     be extracted. These dependencies are guaranteed to be compiled
 4730     and installed before the extract step of the current package
 4731     starts. This is only used internally by the package
 4732     infrastructure, and should typically not be used directly by
 4733     packages.
 4734   * LIBFOO_PATCH_DEPENDENCIES lists the dependencies (in terms of
 4735     package name) that are required for the current package to be
 4736     patched. These dependencies are guaranteed to be extracted and
 4737     patched (but not necessarily built) before the current package is
 4738     patched. In a similar way, HOST_LIBFOO_PATCH_DEPENDENCIES lists
 4739     the dependencies for the current host package. This is seldom
 4740     used; usually, LIBFOO_DEPENDENCIES is what you really want to
 4741     use.
 4742   * LIBFOO_PROVIDES lists all the virtual packages libfoo is an
 4743     implementation of. See Section 18.11, “Infrastructure for virtual
 4744     packages”.
 4745   * LIBFOO_INSTALL_STAGING can be set to YES or NO (default). If set
 4746     to YES, then the commands in the LIBFOO_INSTALL_STAGING_CMDS
 4747     variables are executed to install the package into the staging
 4748     directory.
 4749   * LIBFOO_INSTALL_TARGET can be set to YES (default) or NO. If set
 4750     to YES, then the commands in the LIBFOO_INSTALL_TARGET_CMDS
 4751     variables are executed to install the package into the target
 4752     directory.
 4753   * LIBFOO_INSTALL_IMAGES can be set to YES or NO (default). If set
 4754     to YES, then the commands in the LIBFOO_INSTALL_IMAGES_CMDS
 4755     variable are executed to install the package into the images
 4756     directory.
 4757   * LIBFOO_CONFIG_SCRIPTS lists the names of the files in $
 4758     (STAGING_DIR)/usr/bin that need some special fixing to make them
 4759     cross-compiling friendly. Multiple file names separated by space
 4760     can be given and all are relative to $(STAGING_DIR)/usr/bin. The
 4761     files listed in LIBFOO_CONFIG_SCRIPTS are also removed from $
 4762     (TARGET_DIR)/usr/bin since they are not needed on the target.
 4763   * LIBFOO_DEVICES lists the device files to be created by Buildroot
 4764     when using the static device table. The syntax to use is the
 4765     makedevs one. You can find some documentation for this syntax in
 4766     the Chapter 25, Makedev syntax documentation. This variable is
 4767     optional.
 4768   * LIBFOO_PERMISSIONS lists the changes of permissions to be done at
 4769     the end of the build process. The syntax is once again the
 4770     makedevs one. You can find some documentation for this syntax in
 4771     the Chapter 25, Makedev syntax documentation. This variable is
 4772     optional.
 4773   * LIBFOO_USERS lists the users to create for this package, if it
 4774     installs a program you want to run as a specific user (e.g. as a
 4775     daemon, or as a cron-job). The syntax is similar in spirit to the
 4776     makedevs one, and is described in the Chapter 26, Makeusers
 4777     syntax documentation. This variable is optional.
 4778   * LIBFOO_LICENSE defines the license (or licenses) under which the
 4779     package is released. This name will appear in the manifest file
 4780     produced by make legal-info. If the license appears in the SPDX
 4781     License List [https://spdx.org/licenses/], use the SPDX short
 4782     identifier to make the manifest file uniform. Otherwise, describe
 4783     the license in a precise and concise way, avoiding ambiguous
 4784     names such as BSD which actually name a family of licenses. This
 4785     variable is optional. If it is not defined, unknown will appear
 4786     in the license field of the manifest file for this package. The
 4787     expected format for this variable must comply with the following
 4788     rules:
 4789 
 4790       + If different parts of the package are released under
 4791         different licenses, then comma separate licenses (e.g.
 4792         LIBFOO_LICENSE = GPL-2.0+, LGPL-2.1+). If there is clear
 4793         distinction between which component is licensed under what
 4794         license, then annotate the license with that component,
 4795         between parenthesis (e.g. LIBFOO_LICENSE = GPL-2.0+
 4796         (programs), LGPL-2.1+ (libraries)).
 4797       + If some licenses are conditioned on a sub-option being
 4798         enabled, append the conditional licenses with a comma (e.g.:
 4799         FOO_LICENSE += , GPL-2.0+ (programs)); the infrastructure
 4800         will internally remove the space before the comma.
 4801       + If the package is dual licensed, then separate licenses with
 4802         the or keyword (e.g. LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+).
 4803   * LIBFOO_LICENSE_FILES is a space-separated list of files in the
 4804     package tarball that contain the license(s) under which the
 4805     package is released. make legal-info copies all of these files in
 4806     the legal-info directory. See Chapter 13, Legal notice and
 4807     licensing for more information. This variable is optional. If it
 4808     is not defined, a warning will be produced to let you know, and
 4809     not saved will appear in the license files field of the manifest
 4810     file for this package.
 4811   * LIBFOO_ACTUAL_SOURCE_TARBALL only applies to packages whose
 4812     LIBFOO_SITE / LIBFOO_SOURCE pair points to an archive that does
 4813     not actually contain source code, but binary code. This a very
 4814     uncommon case, only known to apply to external toolchains which
 4815     come already compiled, although theoretically it might apply to
 4816     other packages. In such cases a separate tarball is usually
 4817     available with the actual source code. Set
 4818     LIBFOO_ACTUAL_SOURCE_TARBALL to the name of the actual source
 4819     code archive and Buildroot will download it and use it when you
 4820     run make legal-info to collect legally-relevant material. Note
 4821     this file will not be downloaded during regular builds nor by
 4822     make source.
 4823   * LIBFOO_ACTUAL_SOURCE_SITE provides the location of the actual
 4824     source tarball. The default value is LIBFOO_SITE, so you don’t
 4825     need to set this variable if the binary and source archives are
 4826     hosted on the same directory. If LIBFOO_ACTUAL_SOURCE_TARBALL is
 4827     not set, it doesn’t make sense to define
 4828     LIBFOO_ACTUAL_SOURCE_SITE.
 4829   * LIBFOO_REDISTRIBUTE can be set to YES (default) or NO to indicate
 4830     if the package source code is allowed to be redistributed. Set it
 4831     to NO for non-opensource packages: Buildroot will not save the
 4832     source code for this package when collecting the legal-info.
 4833   * LIBFOO_FLAT_STACKSIZE defines the stack size of an application
 4834     built into the FLAT binary format. The application stack size on
 4835     the NOMMU architecture processors can’t be enlarged at run time.
 4836     The default stack size for the FLAT binary format is only 4k
 4837     bytes. If the application consumes more stack, append the
 4838     required number here.
 4839   * LIBFOO_BIN_ARCH_EXCLUDE is a space-separated list of paths
 4840     (relative to the target directory) to ignore when checking that
 4841     the package installs correctly cross-compiled binaries. You
 4842     seldom need to set this variable, unless the package installs
 4843     binary blobs outside the default locations, /lib/firmware, /usr/
 4844     lib/firmware, /lib/modules, /usr/lib/modules, and /usr/share,
 4845     which are automatically excluded.
 4846   * LIBFOO_IGNORE_CVES is a space-separated list of CVEs that tells
 4847     Buildroot CVE tracking tools which CVEs should be ignored for
 4848     this package. This is typically used when the CVE is fixed by a
 4849     patch in the package, or when the CVE for some reason does not
 4850     affect the Buildroot package. A Makefile comment must always
 4851     precede the addition of a CVE to this variable. Example:
 4852 
 4853 # 0001-fix-cve-2020-12345.patch
 4854 LIBFOO_IGNORE_CVES += CVE-2020-12345
 4855 # only when built with libbaz, which Buildroot doesn't support
 4856 LIBFOO_IGNORE_CVES += CVE-2020-54321
 4857 
 4858   * LIBFOO_CPE_ID_* variables is a set of variables that allows the
 4859     package to define its CPE identifier [https://nvd.nist.gov/
 4860     products/cpe]. The available variables are:
 4861 
 4862       + LIBFOO_CPE_ID_PREFIX, specifies the prefix of the CPE
 4863         identifier, i.e the first three fields. When not defined, the
 4864         default value is cpe:2.3:a.
 4865       + LIBFOO_CPE_ID_VENDOR, specifies the vendor part of the CPE
 4866         identifier. When not defined, the default value is <pkgname>
 4867         _project.
 4868       + LIBFOO_CPE_ID_PRODUCT, specifies the product part of the CPE
 4869         identifier. When not defined, the default value is <pkgname>.
 4870       + LIBFOO_CPE_ID_VERSION, specifies the version part of the CPE
 4871         identifier. When not defined the default value is $
 4872         (LIBFOO_VERSION).
 4873       + LIBFOO_CPE_ID_UPDATE specifies the update part of the CPE
 4874         identifier. When not defined the default value is *.
 4875 
 4876     If any of those variables is defined, then the generic package
 4877     infrastructure assumes the package provides valid CPE
 4878     information. In this case, the generic package infrastructure
 4879     will define LIBFOO_CPE_ID.
 4880 
 4881     For a host package, if its LIBFOO_CPE_ID_* variables are not
 4882     defined, it inherits the value of those variables from the
 4883     corresponding target package.
 4884 
 4885 The recommended way to define these variables is to use the following
 4886 syntax:
 4887 
 4888 LIBFOO_VERSION = 2.32
 4889 
 4890 Now, the variables that define what should be performed at the
 4891 different steps of the build process.
 4892 
 4893   * LIBFOO_EXTRACT_CMDS lists the actions to be performed to extract
 4894     the package. This is generally not needed as tarballs are
 4895     automatically handled by Buildroot. However, if the package uses
 4896     a non-standard archive format, such as a ZIP or RAR file, or has
 4897     a tarball with a non-standard organization, this variable allows
 4898     to override the package infrastructure default behavior.
 4899   * LIBFOO_CONFIGURE_CMDS lists the actions to be performed to
 4900     configure the package before its compilation.
 4901   * LIBFOO_BUILD_CMDS lists the actions to be performed to compile
 4902     the package.
 4903   * HOST_LIBFOO_INSTALL_CMDS lists the actions to be performed to
 4904     install the package, when the package is a host package. The
 4905     package must install its files to the directory given by $
 4906     (HOST_DIR). All files, including development files such as
 4907     headers should be installed, since other packages might be
 4908     compiled on top of this package.
 4909   * LIBFOO_INSTALL_TARGET_CMDS lists the actions to be performed to
 4910     install the package to the target directory, when the package is
 4911     a target package. The package must install its files to the
 4912     directory given by $(TARGET_DIR). Only the files required for 
 4913     execution of the package have to be installed. Header files,
 4914     static libraries and documentation will be removed again when the
 4915     target filesystem is finalized.
 4916   * LIBFOO_INSTALL_STAGING_CMDS lists the actions to be performed to
 4917     install the package to the staging directory, when the package is
 4918     a target package. The package must install its files to the
 4919     directory given by $(STAGING_DIR). All development files should
 4920     be installed, since they might be needed to compile other
 4921     packages.
 4922   * LIBFOO_INSTALL_IMAGES_CMDS lists the actions to be performed to
 4923     install the package to the images directory, when the package is
 4924     a target package. The package must install its files to the
 4925     directory given by $(BINARIES_DIR). Only files that are binary
 4926     images (aka images) that do not belong in the TARGET_DIR but are
 4927     necessary for booting the board should be placed here. For
 4928     example, a package should utilize this step if it has binaries
 4929     which would be similar to the kernel image, bootloader or root
 4930     filesystem images.
 4931   * LIBFOO_INSTALL_INIT_SYSV, LIBFOO_INSTALL_INIT_OPENRC and
 4932     LIBFOO_INSTALL_INIT_SYSTEMD list the actions to install init
 4933     scripts either for the systemV-like init systems (busybox,
 4934     sysvinit, etc.), openrc or for the systemd units. These commands
 4935     will be run only when the relevant init system is installed (i.e.
 4936     if systemd is selected as the init system in the configuration,
 4937     only LIBFOO_INSTALL_INIT_SYSTEMD will be run). The only exception
 4938     is when openrc is chosen as init system and
 4939     LIBFOO_INSTALL_INIT_OPENRC has not been set, in such situation
 4940     LIBFOO_INSTALL_INIT_SYSV will be called, since openrc supports
 4941     sysv init scripts. When systemd is used as the init system,
 4942     buildroot will automatically enable all services using the
 4943     systemctl preset-all command in the final phase of image
 4944     building. You can add preset files to prevent a particular unit
 4945     from being automatically enabled by buildroot.
 4946   * LIBFOO_HELP_CMDS lists the actions to print the package help,
 4947     which is included to the main make help output. These commands
 4948     can print anything in any format. This is seldom used, as
 4949     packages rarely have custom rules. Do not use this variable,
 4950     unless you really know that you need to print help.
 4951   * LIBFOO_LINUX_CONFIG_FIXUPS lists the Linux kernel configuration
 4952     options that are needed to build and use this package, and
 4953     without which the package is fundamentally broken. This shall be
 4954     a set of calls to one of the kconfig tweaking option:
 4955     KCONFIG_ENABLE_OPT, KCONFIG_DISABLE_OPT, or KCONFIG_SET_OPT. This
 4956     is seldom used, as package usually have no strict requirements on
 4957     the kernel options.
 4958 
 4959 The preferred way to define these variables is:
 4960 
 4961 define LIBFOO_CONFIGURE_CMDS
 4962         action 1
 4963         action 2
 4964         action 3
 4965 endef
 4966 
 4967 In the action definitions, you can use the following variables:
 4968 
 4969   * $(LIBFOO_PKGDIR) contains the path to the directory containing
 4970     the libfoo.mk and Config.in files. This variable is useful when
 4971     it is necessary to install a file bundled in Buildroot, like a
 4972     runtime configuration file, a splashscreen image…
 4973   * $(@D), which contains the directory in which the package source
 4974     code has been uncompressed.
 4975   * $(LIBFOO_DL_DIR) contains the path to the directory where all the
 4976     downloads made by Buildroot for libfoo are stored in.
 4977   * $(TARGET_CC), $(TARGET_LD), etc. to get the target
 4978     cross-compilation utilities
 4979   * $(TARGET_CROSS) to get the cross-compilation toolchain prefix
 4980   * Of course the $(HOST_DIR), $(STAGING_DIR) and $(TARGET_DIR)
 4981     variables to install the packages properly. Those variables point
 4982     to the global host, staging and target directories, unless 
 4983     per-package directory support is used, in which case they point
 4984     to the current package host, staging and target directories. In
 4985     both cases, it doesn’t make any difference from the package point
 4986     of view: it should simply use HOST_DIR, STAGING_DIR and
 4987     TARGET_DIR. See Section 8.12, “Top-level parallel build” for more
 4988     details about per-package directory support.
 4989 
 4990 Finally, you can also use hooks. See Section 18.22, “Hooks available
 4991 in the various build steps” for more information.
 4992 
 4993 18.6. Infrastructure for autotools-based packages
 4994 
 4995 18.6.1. autotools-package tutorial
 4996 
 4997 First, let’s see how to write a .mk file for an autotools-based
 4998 package, with an example :
 4999 
 5000 01: ################################################################################
 5001 02: #
 5002 03: # libfoo
 5003 04: #
 5004 05: ################################################################################
 5005 06:
 5006 07: LIBFOO_VERSION = 1.0
 5007 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 5008 09: LIBFOO_SITE = http://www.foosoftware.org/download
 5009 10: LIBFOO_INSTALL_STAGING = YES
 5010 11: LIBFOO_INSTALL_TARGET = NO
 5011 12: LIBFOO_CONF_OPTS = --disable-shared
 5012 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
 5013 14:
 5014 15: $(eval $(autotools-package))
 5015 
 5016 On line 7, we declare the version of the package.
 5017 
 5018 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 5019 recommended) and the location of the tarball on the Web. Buildroot
 5020 will automatically download the tarball from this location.
 5021 
 5022 On line 10, we tell Buildroot to install the package to the staging
 5023 directory. The staging directory, located in output/staging/ is the
 5024 directory where all the packages are installed, including their
 5025 development files, etc. By default, packages are not installed to the
 5026 staging directory, since usually, only libraries need to be installed
 5027 in the staging directory: their development files are needed to
 5028 compile other libraries or applications depending on them. Also by
 5029 default, when staging installation is enabled, packages are installed
 5030 in this location using the make install command.
 5031 
 5032 On line 11, we tell Buildroot to not install the package to the
 5033 target directory. This directory contains what will become the root
 5034 filesystem running on the target. For purely static libraries, it is
 5035 not necessary to install them in the target directory because they
 5036 will not be used at runtime. By default, target installation is
 5037 enabled; setting this variable to NO is almost never needed. Also by
 5038 default, packages are installed in this location using the make
 5039 install command.
 5040 
 5041 On line 12, we tell Buildroot to pass a custom configure option, that
 5042 will be passed to the ./configure script before configuring and
 5043 building the package.
 5044 
 5045 On line 13, we declare our dependencies, so that they are built
 5046 before the build process of our package starts.
 5047 
 5048 Finally, on line line 15, we invoke the autotools-package macro that
 5049 generates all the Makefile rules that actually allows the package to
 5050 be built.
 5051 
 5052 18.6.2. autotools-package reference
 5053 
 5054 The main macro of the autotools package infrastructure is
 5055 autotools-package. It is similar to the generic-package macro. The
 5056 ability to have target and host packages is also available, with the
 5057 host-autotools-package macro.
 5058 
 5059 Just like the generic infrastructure, the autotools infrastructure
 5060 works by defining a number of variables before calling the
 5061 autotools-package macro.
 5062 
 5063 First, all the package metadata information variables that exist in
 5064 the generic infrastructure also exist in the autotools
 5065 infrastructure: LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH,
 5066 LIBFOO_SITE, LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES,
 5067 LIBFOO_INSTALL_STAGING, LIBFOO_INSTALL_TARGET.
 5068 
 5069 A few additional variables, specific to the autotools infrastructure,
 5070 can also be defined. Many of them are only useful in very specific
 5071 cases, typical packages will therefore only use a few of them.
 5072 
 5073   * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
 5074     package that contains the configure script. This is useful, if
 5075     for example, the main configure script is not at the root of the
 5076     tree extracted by the tarball. If HOST_LIBFOO_SUBDIR is not
 5077     specified, it defaults to LIBFOO_SUBDIR.
 5078   * LIBFOO_CONF_ENV, to specify additional environment variables to
 5079     pass to the configure script. By default, empty.
 5080   * LIBFOO_CONF_OPTS, to specify additional configure options to pass
 5081     to the configure script. By default, empty.
 5082   * LIBFOO_MAKE, to specify an alternate make command. This is
 5083     typically useful when parallel make is enabled in the
 5084     configuration (using BR2_JLEVEL) but that this feature should be
 5085     disabled for the given package, for one reason or another. By
 5086     default, set to $(MAKE). If parallel building is not supported by
 5087     the package, then it should be set to LIBFOO_MAKE=$(MAKE1).
 5088   * LIBFOO_MAKE_ENV, to specify additional environment variables to
 5089     pass to make in the build step. These are passed before the make
 5090     command. By default, empty.
 5091   * LIBFOO_MAKE_OPTS, to specify additional variables to pass to make
 5092     in the build step. These are passed after the make command. By
 5093     default, empty.
 5094   * LIBFOO_AUTORECONF, tells whether the package should be
 5095     autoreconfigured or not (i.e. if the configure script and
 5096     Makefile.in files should be re-generated by re-running autoconf,
 5097     automake, libtool, etc.). Valid values are YES and NO. By
 5098     default, the value is NO
 5099   * LIBFOO_AUTORECONF_ENV, to specify additional environment
 5100     variables to pass to the autoreconf program if LIBFOO_AUTORECONF=
 5101     YES. These are passed in the environment of the autoreconf
 5102     command. By default, empty.
 5103   * LIBFOO_AUTORECONF_OPTS to specify additional options passed to
 5104     the autoreconf program if LIBFOO_AUTORECONF=YES. By default,
 5105     empty.
 5106   * LIBFOO_GETTEXTIZE, tells whether the package should be
 5107     gettextized or not (i.e. if the package uses a different gettext
 5108     version than Buildroot provides, and it is needed to run 
 5109     gettextize.) Only valid when LIBFOO_AUTORECONF=YES. Valid values
 5110     are YES and NO. The default is NO.
 5111   * LIBFOO_GETTEXTIZE_OPTS, to specify additional options passed to
 5112     the gettextize program, if LIBFOO_GETTEXTIZE=YES. You may use
 5113     that if, for example, the .po files are not located in the
 5114     standard place (i.e. in po/ at the root of the package.) By
 5115     default, -f.
 5116   * LIBFOO_LIBTOOL_PATCH tells whether the Buildroot patch to fix
 5117     libtool cross-compilation issues should be applied or not. Valid
 5118     values are YES and NO. By default, the value is YES
 5119   * LIBFOO_INSTALL_STAGING_OPTS contains the make options used to
 5120     install the package to the staging directory. By default, the
 5121     value is DESTDIR=$(STAGING_DIR) install, which is correct for
 5122     most autotools packages. It is still possible to override it.
 5123   * LIBFOO_INSTALL_TARGET_OPTS contains the make options used to
 5124     install the package to the target directory. By default, the
 5125     value is DESTDIR=$(TARGET_DIR) install. The default value is
 5126     correct for most autotools packages, but it is still possible to
 5127     override it if needed.
 5128 
 5129 With the autotools infrastructure, all the steps required to build
 5130 and install the packages are already defined, and they generally work
 5131 well for most autotools-based packages. However, when required, it is
 5132 still possible to customize what is done in any particular step:
 5133 
 5134   * By adding a post-operation hook (after extract, patch, configure,
 5135     build or install). See Section 18.22, “Hooks available in the
 5136     various build steps” for details.
 5137   * By overriding one of the steps. For example, even if the
 5138     autotools infrastructure is used, if the package .mk file defines
 5139     its own LIBFOO_CONFIGURE_CMDS variable, it will be used instead
 5140     of the default autotools one. However, using this method should
 5141     be restricted to very specific cases. Do not use it in the
 5142     general case.
 5143 
 5144 18.7. Infrastructure for CMake-based packages
 5145 
 5146 18.7.1. cmake-package tutorial
 5147 
 5148 First, let’s see how to write a .mk file for a CMake-based package,
 5149 with an example :
 5150 
 5151 01: ################################################################################
 5152 02: #
 5153 03: # libfoo
 5154 04: #
 5155 05: ################################################################################
 5156 06:
 5157 07: LIBFOO_VERSION = 1.0
 5158 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 5159 09: LIBFOO_SITE = http://www.foosoftware.org/download
 5160 10: LIBFOO_INSTALL_STAGING = YES
 5161 11: LIBFOO_INSTALL_TARGET = NO
 5162 12: LIBFOO_CONF_OPTS = -DBUILD_DEMOS=ON
 5163 13: LIBFOO_DEPENDENCIES = libglib2 host-pkgconf
 5164 14:
 5165 15: $(eval $(cmake-package))
 5166 
 5167 On line 7, we declare the version of the package.
 5168 
 5169 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 5170 recommended) and the location of the tarball on the Web. Buildroot
 5171 will automatically download the tarball from this location.
 5172 
 5173 On line 10, we tell Buildroot to install the package to the staging
 5174 directory. The staging directory, located in output/staging/ is the
 5175 directory where all the packages are installed, including their
 5176 development files, etc. By default, packages are not installed to the
 5177 staging directory, since usually, only libraries need to be installed
 5178 in the staging directory: their development files are needed to
 5179 compile other libraries or applications depending on them. Also by
 5180 default, when staging installation is enabled, packages are installed
 5181 in this location using the make install command.
 5182 
 5183 On line 11, we tell Buildroot to not install the package to the
 5184 target directory. This directory contains what will become the root
 5185 filesystem running on the target. For purely static libraries, it is
 5186 not necessary to install them in the target directory because they
 5187 will not be used at runtime. By default, target installation is
 5188 enabled; setting this variable to NO is almost never needed. Also by
 5189 default, packages are installed in this location using the make
 5190 install command.
 5191 
 5192 On line 12, we tell Buildroot to pass custom options to CMake when it
 5193 is configuring the package.
 5194 
 5195 On line 13, we declare our dependencies, so that they are built
 5196 before the build process of our package starts.
 5197 
 5198 Finally, on line line 15, we invoke the cmake-package macro that
 5199 generates all the Makefile rules that actually allows the package to
 5200 be built.
 5201 
 5202 18.7.2. cmake-package reference
 5203 
 5204 The main macro of the CMake package infrastructure is cmake-package.
 5205 It is similar to the generic-package macro. The ability to have
 5206 target and host packages is also available, with the
 5207 host-cmake-package macro.
 5208 
 5209 Just like the generic infrastructure, the CMake infrastructure works
 5210 by defining a number of variables before calling the cmake-package
 5211 macro.
 5212 
 5213 First, all the package metadata information variables that exist in
 5214 the generic infrastructure also exist in the CMake infrastructure:
 5215 LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
 5216 LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
 5217 LIBFOO_INSTALL_TARGET.
 5218 
 5219 A few additional variables, specific to the CMake infrastructure, can
 5220 also be defined. Many of them are only useful in very specific cases,
 5221 typical packages will therefore only use a few of them.
 5222 
 5223   * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
 5224     package that contains the main CMakeLists.txt file. This is
 5225     useful, if for example, the main CMakeLists.txt file is not at
 5226     the root of the tree extracted by the tarball. If
 5227     HOST_LIBFOO_SUBDIR is not specified, it defaults to
 5228     LIBFOO_SUBDIR.
 5229   * LIBFOO_CONF_ENV, to specify additional environment variables to
 5230     pass to CMake. By default, empty.
 5231   * LIBFOO_CONF_OPTS, to specify additional configure options to pass
 5232     to CMake. By default, empty. A number of common CMake options are
 5233     set by the cmake-package infrastructure; so it is normally not
 5234     necessary to set them in the package’s *.mk file unless you want
 5235     to override them:
 5236 
 5237       + CMAKE_BUILD_TYPE is driven by BR2_ENABLE_DEBUG;
 5238       + CMAKE_INSTALL_PREFIX;
 5239       + BUILD_SHARED_LIBS is driven by BR2_STATIC_LIBS;
 5240       + BUILD_DOC, BUILD_DOCS are disabled;
 5241       + BUILD_EXAMPLE, BUILD_EXAMPLES are disabled;
 5242       + BUILD_TEST, BUILD_TESTS, BUILD_TESTING are disabled.
 5243   * LIBFOO_SUPPORTS_IN_SOURCE_BUILD = NO should be set when the
 5244     package cannot be built inside the source tree but needs a
 5245     separate build directory.
 5246   * LIBFOO_MAKE, to specify an alternate make command. This is
 5247     typically useful when parallel make is enabled in the
 5248     configuration (using BR2_JLEVEL) but that this feature should be
 5249     disabled for the given package, for one reason or another. By
 5250     default, set to $(MAKE). If parallel building is not supported by
 5251     the package, then it should be set to LIBFOO_MAKE=$(MAKE1).
 5252   * LIBFOO_MAKE_ENV, to specify additional environment variables to
 5253     pass to make in the build step. These are passed before the make
 5254     command. By default, empty.
 5255   * LIBFOO_MAKE_OPTS, to specify additional variables to pass to make
 5256     in the build step. These are passed after the make command. By
 5257     default, empty.
 5258   * LIBFOO_INSTALL_OPTS contains the make options used to install the
 5259     package to the host directory. By default, the value is install,
 5260     which is correct for most CMake packages. It is still possible to
 5261     override it.
 5262   * LIBFOO_INSTALL_STAGING_OPTS contains the make options used to
 5263     install the package to the staging directory. By default, the
 5264     value is DESTDIR=$(STAGING_DIR) install/fast, which is correct
 5265     for most CMake packages. It is still possible to override it.
 5266   * LIBFOO_INSTALL_TARGET_OPTS contains the make options used to
 5267     install the package to the target directory. By default, the
 5268     value is DESTDIR=$(TARGET_DIR) install/fast. The default value is
 5269     correct for most CMake packages, but it is still possible to
 5270     override it if needed.
 5271 
 5272 With the CMake infrastructure, all the steps required to build and
 5273 install the packages are already defined, and they generally work
 5274 well for most CMake-based packages. However, when required, it is
 5275 still possible to customize what is done in any particular step:
 5276 
 5277   * By adding a post-operation hook (after extract, patch, configure,
 5278     build or install). See Section 18.22, “Hooks available in the
 5279     various build steps” for details.
 5280   * By overriding one of the steps. For example, even if the CMake
 5281     infrastructure is used, if the package .mk file defines its own
 5282     LIBFOO_CONFIGURE_CMDS variable, it will be used instead of the
 5283     default CMake one. However, using this method should be
 5284     restricted to very specific cases. Do not use it in the general
 5285     case.
 5286 
 5287 18.8. Infrastructure for Python packages
 5288 
 5289 This infrastructure applies to Python packages that use the standard
 5290 Python setuptools mechanism as their build system, generally
 5291 recognizable by the usage of a setup.py script.
 5292 
 5293 18.8.1. python-package tutorial
 5294 
 5295 First, let’s see how to write a .mk file for a Python package, with
 5296 an example :
 5297 
 5298 01: ################################################################################
 5299 02: #
 5300 03: # python-foo
 5301 04: #
 5302 05: ################################################################################
 5303 06:
 5304 07: PYTHON_FOO_VERSION = 1.0
 5305 08: PYTHON_FOO_SOURCE = python-foo-$(PYTHON_FOO_VERSION).tar.xz
 5306 09: PYTHON_FOO_SITE = http://www.foosoftware.org/download
 5307 10: PYTHON_FOO_LICENSE = BSD-3-Clause
 5308 11: PYTHON_FOO_LICENSE_FILES = LICENSE
 5309 12: PYTHON_FOO_ENV = SOME_VAR=1
 5310 13: PYTHON_FOO_DEPENDENCIES = libmad
 5311 14: PYTHON_FOO_SETUP_TYPE = distutils
 5312 15:
 5313 16: $(eval $(python-package))
 5314 
 5315 On line 7, we declare the version of the package.
 5316 
 5317 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 5318 recommended) and the location of the tarball on the Web. Buildroot
 5319 will automatically download the tarball from this location.
 5320 
 5321 On line 10 and 11, we give licensing details about the package (its
 5322 license on line 10, and the file containing the license text on line
 5323 11).
 5324 
 5325 On line 12, we tell Buildroot to pass custom options to the Python
 5326 setup.py script when it is configuring the package.
 5327 
 5328 On line 13, we declare our dependencies, so that they are built
 5329 before the build process of our package starts.
 5330 
 5331 On line 14, we declare the specific Python build system being used.
 5332 In this case the distutils Python build system is used. The two
 5333 supported ones are distutils and setuptools.
 5334 
 5335 Finally, on line 16, we invoke the python-package macro that
 5336 generates all the Makefile rules that actually allow the package to
 5337 be built.
 5338 
 5339 18.8.2. python-package reference
 5340 
 5341 As a policy, packages that merely provide Python modules should all
 5342 be named python-<something> in Buildroot. Other packages that use the
 5343 Python build system, but are not Python modules, can freely choose
 5344 their name (existing examples in Buildroot are scons and supervisor).
 5345 
 5346 Packages that are only compatible with one version of Python (as in:
 5347 Python 2 or Python 3) should depend on that version explicitely in
 5348 their Config.in file (BR2_PACKAGE_PYTHON for Python 2,
 5349 BR2_PACKAGE_PYTHON3 for Python 3). Packages that are compatible with
 5350 both versions should not explicitely depend on them in their
 5351 Config.in file, since that condition is already expressed for the
 5352 whole "External python modules" menu.
 5353 
 5354 The main macro of the Python package infrastructure is
 5355 python-package. It is similar to the generic-package macro. It is
 5356 also possible to create Python host packages with the
 5357 host-python-package macro.
 5358 
 5359 Just like the generic infrastructure, the Python infrastructure works
 5360 by defining a number of variables before calling the python-package
 5361 or host-python-package macros.
 5362 
 5363 All the package metadata information variables that exist in the
 5364 generic package infrastructure also exist in the Python
 5365 infrastructure: PYTHON_FOO_VERSION, PYTHON_FOO_SOURCE,
 5366 PYTHON_FOO_PATCH, PYTHON_FOO_SITE, PYTHON_FOO_SUBDIR,
 5367 PYTHON_FOO_DEPENDENCIES, PYTHON_FOO_LICENSE,
 5368 PYTHON_FOO_LICENSE_FILES, PYTHON_FOO_INSTALL_STAGING, etc.
 5369 
 5370 Note that:
 5371 
 5372   * It is not necessary to add python or host-python in the
 5373     PYTHON_FOO_DEPENDENCIES variable of a package, since these basic
 5374     dependencies are automatically added as needed by the Python
 5375     package infrastructure.
 5376   * Similarly, it is not needed to add host-setuptools to
 5377     PYTHON_FOO_DEPENDENCIES for setuptools-based packages, since it’s
 5378     automatically added by the Python infrastructure as needed.
 5379 
 5380 One variable specific to the Python infrastructure is mandatory:
 5381 
 5382   * PYTHON_FOO_SETUP_TYPE, to define which Python build system is
 5383     used by the package. The two supported values are distutils and
 5384     setuptools. If you don’t know which one is used in your package,
 5385     look at the setup.py file in your package source code, and see
 5386     whether it imports things from the distutils module or the
 5387     setuptools module.
 5388 
 5389 A few additional variables, specific to the Python infrastructure,
 5390 can optionally be defined, depending on the package’s needs. Many of
 5391 them are only useful in very specific cases, typical packages will
 5392 therefore only use a few of them, or none.
 5393 
 5394   * PYTHON_FOO_SUBDIR may contain the name of a subdirectory inside
 5395     the package that contains the main setup.py file. This is useful,
 5396     if for example, the main setup.py file is not at the root of the
 5397     tree extracted by the tarball. If HOST_PYTHON_FOO_SUBDIR is not
 5398     specified, it defaults to PYTHON_FOO_SUBDIR.
 5399   * PYTHON_FOO_ENV, to specify additional environment variables to
 5400     pass to the Python setup.py script (for both the build and
 5401     install steps). Note that the infrastructure is automatically
 5402     passing several standard variables, defined in
 5403     PKG_PYTHON_DISTUTILS_ENV (for distutils target packages),
 5404     HOST_PKG_PYTHON_DISTUTILS_ENV (for distutils host packages),
 5405     PKG_PYTHON_SETUPTOOLS_ENV (for setuptools target packages) and
 5406     HOST_PKG_PYTHON_SETUPTOOLS_ENV (for setuptools host packages).
 5407   * PYTHON_FOO_BUILD_OPTS, to specify additional options to pass to
 5408     the Python setup.py script during the build step. For target
 5409     distutils packages, the PKG_PYTHON_DISTUTILS_BUILD_OPTS options
 5410     are already passed automatically by the infrastructure.
 5411   * PYTHON_FOO_INSTALL_TARGET_OPTS, PYTHON_FOO_INSTALL_STAGING_OPTS,
 5412     HOST_PYTHON_FOO_INSTALL_OPTS to specify additional options to
 5413     pass to the Python setup.py script during the target installation
 5414     step, the staging installation step or the host installation,
 5415     respectively. Note that the infrastructure is automatically
 5416     passing some options, defined in
 5417     PKG_PYTHON_DISTUTILS_INSTALL_TARGET_OPTS or
 5418     PKG_PYTHON_DISTUTILS_INSTALL_STAGING_OPTS (for target distutils
 5419     packages), HOST_PKG_PYTHON_DISTUTILS_INSTALL_OPTS (for host
 5420     distutils packages), PKG_PYTHON_SETUPTOOLS_INSTALL_TARGET_OPTS or
 5421     PKG_PYTHON_SETUPTOOLS_INSTALL_STAGING_OPTS (for target setuptools
 5422     packages) and HOST_PKG_PYTHON_SETUPTOOLS_INSTALL_OPTS (for host
 5423     setuptools packages).
 5424   * HOST_PYTHON_FOO_NEEDS_HOST_PYTHON, to define the host python
 5425     interpreter. The usage of this variable is limited to host
 5426     packages. The two supported value are python2 and python3. It
 5427     will ensure the right host python package is available and will
 5428     invoke it for the build. If some build steps are overloaded, the
 5429     right python interpreter must be explicitly called in the
 5430     commands.
 5431 
 5432 With the Python infrastructure, all the steps required to build and
 5433 install the packages are already defined, and they generally work
 5434 well for most Python-based packages. However, when required, it is
 5435 still possible to customize what is done in any particular step:
 5436 
 5437   * By adding a post-operation hook (after extract, patch, configure,
 5438     build or install). See Section 18.22, “Hooks available in the
 5439     various build steps” for details.
 5440   * By overriding one of the steps. For example, even if the Python
 5441     infrastructure is used, if the package .mk file defines its own
 5442     PYTHON_FOO_BUILD_CMDS variable, it will be used instead of the
 5443     default Python one. However, using this method should be
 5444     restricted to very specific cases. Do not use it in the general
 5445     case.
 5446 
 5447 18.8.3. Generating a python-package from a PyPI repository
 5448 
 5449 If the Python package for which you would like to create a Buildroot
 5450 package is available on PyPI, you may want to use the scanpypi tool
 5451 located in utils/ to automate the process.
 5452 
 5453 You can find the list of existing PyPI packages here [https://
 5454 pypi.python.org].
 5455 
 5456 scanpypi requires Python’s setuptools package to be installed on your
 5457 host.
 5458 
 5459 When at the root of your buildroot directory just do :
 5460 
 5461 utils/scanpypi foo bar -o package
 5462 
 5463 This will generate packages python-foo and python-bar in the package
 5464 folder if they exist on https://pypi.python.org.
 5465 
 5466 Find the external python modules menu and insert your package inside.
 5467 Keep in mind that the items inside a menu should be in alphabetical
 5468 order.
 5469 
 5470 Please keep in mind that you’ll most likely have to manually check
 5471 the package for any mistakes as there are things that cannot be
 5472 guessed by the generator (e.g. dependencies on any of the python core
 5473 modules such as BR2_PACKAGE_PYTHON_ZLIB). Also, please take note that
 5474 the license and license files are guessed and must be checked. You
 5475 also need to manually add the package to the package/Config.in file.
 5476 
 5477 If your Buildroot package is not in the official Buildroot tree but
 5478 in a br2-external tree, use the -o flag as follows:
 5479 
 5480 utils/scanpypi foo bar -o other_package_dir
 5481 
 5482 This will generate packages python-foo and python-bar in the
 5483 other_package_directory instead of package.
 5484 
 5485 Option -h will list the available options:
 5486 
 5487 utils/scanpypi -h
 5488 
 5489 18.8.4. python-package CFFI backend
 5490 
 5491 C Foreign Function Interface for Python (CFFI) provides a convenient
 5492 and reliable way to call compiled C code from Python using interface
 5493 declarations written in C. Python packages relying on this backend
 5494 can be identified by the appearance of a cffi dependency in the
 5495 install_requires field of their setup.py file.
 5496 
 5497 Such a package should:
 5498 
 5499   * add python-cffi as a runtime dependency in order to install the
 5500     compiled C library wrapper on the target. This is achieved by
 5501     adding select BR2_PACKAGE_PYTHON_CFFI to the package Config.in.
 5502 
 5503 config BR2_PACKAGE_PYTHON_FOO
 5504         bool "python-foo"
 5505         select BR2_PACKAGE_PYTHON_CFFI # runtime
 5506 
 5507   * add host-python-cffi as a build-time dependency in order to
 5508     cross-compile the C wrapper. This is achieved by adding
 5509     host-python-cffi to the PYTHON_FOO_DEPENDENCIES variable.
 5510 
 5511 ################################################################################
 5512 #
 5513 # python-foo
 5514 #
 5515 ################################################################################
 5516 
 5517 ...
 5518 
 5519 PYTHON_FOO_DEPENDENCIES = host-python-cffi
 5520 
 5521 $(eval $(python-package))
 5522 
 5523 18.9. Infrastructure for LuaRocks-based packages
 5524 
 5525 18.9.1. luarocks-package tutorial
 5526 
 5527 First, let’s see how to write a .mk file for a LuaRocks-based
 5528 package, with an example :
 5529 
 5530 01: ################################################################################
 5531 02: #
 5532 03: # lua-foo
 5533 04: #
 5534 05: ################################################################################
 5535 06:
 5536 07: LUA_FOO_VERSION = 1.0.2-1
 5537 08: LUA_FOO_NAME_UPSTREAM = foo
 5538 09: LUA_FOO_DEPENDENCIES = bar
 5539 10:
 5540 11: LUA_FOO_BUILD_OPTS += BAR_INCDIR=$(STAGING_DIR)/usr/include
 5541 12: LUA_FOO_BUILD_OPTS += BAR_LIBDIR=$(STAGING_DIR)/usr/lib
 5542 13: LUA_FOO_LICENSE = luaFoo license
 5543 14: LUA_FOO_LICENSE_FILES = $(LUA_FOO_SUBDIR)/COPYING
 5544 15:
 5545 16: $(eval $(luarocks-package))
 5546 
 5547 On line 7, we declare the version of the package (the same as in the
 5548 rockspec, which is the concatenation of the upstream version and the
 5549 rockspec revision, separated by a hyphen -).
 5550 
 5551 On line 8, we declare that the package is called "foo" on LuaRocks.
 5552 In Buildroot, we give Lua-related packages a name that starts with
 5553 "lua", so the Buildroot name is different from the upstream name.
 5554 LUA_FOO_NAME_UPSTREAM makes the link between the two names.
 5555 
 5556 On line 9, we declare our dependencies against native libraries, so
 5557 that they are built before the build process of our package starts.
 5558 
 5559 On lines 11-12, we tell Buildroot to pass custom options to LuaRocks
 5560 when it is building the package.
 5561 
 5562 On lines 13-14, we specify the licensing terms for the package.
 5563 
 5564 Finally, on line 16, we invoke the luarocks-package macro that
 5565 generates all the Makefile rules that actually allows the package to
 5566 be built.
 5567 
 5568 Most of these details can be retrieved from the rock and rockspec.
 5569 So, this file and the Config.in file can be generated by running the
 5570 command luarocks buildroot foo lua-foo in the Buildroot directory.
 5571 This command runs a specific Buildroot addon of luarocks that will
 5572 automatically generate a Buildroot package. The result must still be
 5573 manually inspected and possibly modified.
 5574 
 5575   * The package/Config.in file has to be updated manually to include
 5576     the generated Config.in files.
 5577 
 5578 18.9.2. luarocks-package reference
 5579 
 5580 LuaRocks is a deployment and management system for Lua modules, and
 5581 supports various build.type: builtin, make and cmake. In the context
 5582 of Buildroot, the luarocks-package infrastructure only supports the
 5583 builtin mode. LuaRocks packages that use the make or cmake build
 5584 mechanisms should instead be packaged using the generic-package and
 5585 cmake-package infrastructures in Buildroot, respectively.
 5586 
 5587 The main macro of the LuaRocks package infrastructure is
 5588 luarocks-package: like generic-package it works by defining a number
 5589 of variables providing metadata information about the package, and
 5590 then calling luarocks-package.
 5591 
 5592 Just like the generic infrastructure, the LuaRocks infrastructure
 5593 works by defining a number of variables before calling the
 5594 luarocks-package macro.
 5595 
 5596 First, all the package metadata information variables that exist in
 5597 the generic infrastructure also exist in the LuaRocks infrastructure:
 5598 LUA_FOO_VERSION, LUA_FOO_SOURCE, LUA_FOO_SITE, LUA_FOO_DEPENDENCIES,
 5599 LUA_FOO_LICENSE, LUA_FOO_LICENSE_FILES.
 5600 
 5601 Two of them are populated by the LuaRocks infrastructure (for the
 5602 download step). If your package is not hosted on the LuaRocks mirror
 5603 $(BR2_LUAROCKS_MIRROR), you can override them:
 5604 
 5605   * LUA_FOO_SITE, which defaults to $(BR2_LUAROCKS_MIRROR)
 5606   * LUA_FOO_SOURCE, which defaults to $(lowercase
 5607     LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).src.rock
 5608 
 5609 A few additional variables, specific to the LuaRocks infrastructure,
 5610 are also defined. They can be overridden in specific cases.
 5611 
 5612   * LUA_FOO_NAME_UPSTREAM, which defaults to lua-foo, i.e. the
 5613     Buildroot package name
 5614   * LUA_FOO_ROCKSPEC, which defaults to $(lowercase
 5615     LUA_FOO_NAME_UPSTREAM)-$(LUA_FOO_VERSION).rockspec
 5616   * LUA_FOO_SUBDIR, which defaults to $(LUA_FOO_NAME_UPSTREAM)-$
 5617     (LUA_FOO_VERSION_WITHOUT_ROCKSPEC_REVISION)
 5618   * LUA_FOO_BUILD_OPTS contains additional build options for the
 5619     luarocks build call.
 5620 
 5621 18.10. Infrastructure for Perl/CPAN packages
 5622 
 5623 18.10.1. perl-package tutorial
 5624 
 5625 First, let’s see how to write a .mk file for a Perl/CPAN package,
 5626 with an example :
 5627 
 5628 01: ################################################################################
 5629 02: #
 5630 03: # perl-foo-bar
 5631 04: #
 5632 05: ################################################################################
 5633 06:
 5634 07: PERL_FOO_BAR_VERSION = 0.02
 5635 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
 5636 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
 5637 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
 5638 11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
 5639 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
 5640 13: PERL_FOO_BAR_DISTNAME = Foo-Bar
 5641 14:
 5642 15: $(eval $(perl-package))
 5643 
 5644 On line 7, we declare the version of the package.
 5645 
 5646 On line 8 and 9, we declare the name of the tarball and the location
 5647 of the tarball on a CPAN server. Buildroot will automatically
 5648 download the tarball from this location.
 5649 
 5650 On line 10, we declare our dependencies, so that they are built
 5651 before the build process of our package starts.
 5652 
 5653 On line 11 and 12, we give licensing details about the package (its
 5654 license on line 11, and the file containing the license text on line
 5655 12).
 5656 
 5657 On line 13, the name of the distribution as needed by the script
 5658 utils/scancpan (in order to regenerate/upgrade these package files).
 5659 
 5660 Finally, on line 15, we invoke the perl-package macro that generates
 5661 all the Makefile rules that actually allow the package to be built.
 5662 
 5663 Most of these data can be retrieved from https://metacpan.org/. So,
 5664 this file and the Config.in can be generated by running the script
 5665 utils/scancpan Foo-Bar in the Buildroot directory (or in a
 5666 br2-external tree). This script creates a Config.in file and
 5667 foo-bar.mk file for the requested package, and also recursively for
 5668 all dependencies specified by CPAN. You should still manually edit
 5669 the result. In particular, the following things should be checked.
 5670 
 5671   * If the perl module links with a shared library that is provided
 5672     by another (non-perl) package, this dependency is not added
 5673     automatically. It has to be added manually to
 5674     PERL_FOO_BAR_DEPENDENCIES.
 5675   * The package/Config.in file has to be updated manually to include
 5676     the generated Config.in files. As a hint, the scancpan script
 5677     prints out the required source "…" statements, sorted
 5678     alphabetically.
 5679 
 5680 18.10.2. perl-package reference
 5681 
 5682 As a policy, packages that provide Perl/CPAN modules should all be
 5683 named perl-<something> in Buildroot.
 5684 
 5685 This infrastructure handles various Perl build systems :
 5686 ExtUtils-MakeMaker (EUMM), Module-Build (MB) and Module-Build-Tiny.
 5687 Build.PL is preferred by default when a package provides a
 5688 Makefile.PL and a Build.PL.
 5689 
 5690 The main macro of the Perl/CPAN package infrastructure is
 5691 perl-package. It is similar to the generic-package macro. The ability
 5692 to have target and host packages is also available, with the
 5693 host-perl-package macro.
 5694 
 5695 Just like the generic infrastructure, the Perl/CPAN infrastructure
 5696 works by defining a number of variables before calling the
 5697 perl-package macro.
 5698 
 5699 First, all the package metadata information variables that exist in
 5700 the generic infrastructure also exist in the Perl/CPAN
 5701 infrastructure: PERL_FOO_VERSION, PERL_FOO_SOURCE, PERL_FOO_PATCH,
 5702 PERL_FOO_SITE, PERL_FOO_SUBDIR, PERL_FOO_DEPENDENCIES,
 5703 PERL_FOO_INSTALL_TARGET.
 5704 
 5705 Note that setting PERL_FOO_INSTALL_STAGING to YES has no effect
 5706 unless a PERL_FOO_INSTALL_STAGING_CMDS variable is defined. The perl
 5707 infrastructure doesn’t define these commands since Perl modules
 5708 generally don’t need to be installed to the staging directory.
 5709 
 5710 A few additional variables, specific to the Perl/CPAN infrastructure,
 5711 can also be defined. Many of them are only useful in very specific
 5712 cases, typical packages will therefore only use a few of them.
 5713 
 5714   * PERL_FOO_PREFER_INSTALLER/HOST_PERL_FOO_PREFER_INSTALLER,
 5715     specifies the preferred installation method. Possible values are
 5716     EUMM (for Makefile.PL based installation using
 5717     ExtUtils-MakeMaker) and MB (for Build.PL based installation using
 5718     Module-Build). This variable is only used when the package
 5719     provides both installation methods.
 5720   * PERL_FOO_CONF_ENV/HOST_PERL_FOO_CONF_ENV, to specify additional
 5721     environment variables to pass to the perl Makefile.PL or perl
 5722     Build.PL. By default, empty.
 5723   * PERL_FOO_CONF_OPTS/HOST_PERL_FOO_CONF_OPTS, to specify additional
 5724     configure options to pass to the perl Makefile.PL or perl
 5725     Build.PL. By default, empty.
 5726   * PERL_FOO_BUILD_OPTS/HOST_PERL_FOO_BUILD_OPTS, to specify
 5727     additional options to pass to make pure_all or perl Build build
 5728     in the build step. By default, empty.
 5729   * PERL_FOO_INSTALL_TARGET_OPTS, to specify additional options to
 5730     pass to make pure_install or perl Build install in the install
 5731     step. By default, empty.
 5732   * HOST_PERL_FOO_INSTALL_OPTS, to specify additional options to pass
 5733     to make pure_install or perl Build install in the install step.
 5734     By default, empty.
 5735 
 5736 18.11. Infrastructure for virtual packages
 5737 
 5738 In Buildroot, a virtual package is a package whose functionalities
 5739 are provided by one or more packages, referred to as providers. The
 5740 virtual package management is an extensible mechanism allowing the
 5741 user to choose the provider used in the rootfs.
 5742 
 5743 For example, OpenGL ES is an API for 2D and 3D graphics on embedded
 5744 systems. The implementation of this API is different for the 
 5745 Allwinner Tech Sunxi and the Texas Instruments OMAP35xx platforms. So
 5746 libgles will be a virtual package and sunxi-mali and ti-gfx will be
 5747 the providers.
 5748 
 5749 18.11.1. virtual-package tutorial
 5750 
 5751 In the following example, we will explain how to add a new virtual
 5752 package (something-virtual) and a provider for it (some-provider).
 5753 
 5754 First, let’s create the virtual package.
 5755 
 5756 18.11.2. Virtual package’s Config.in file
 5757 
 5758 The Config.in file of virtual package something-virtual should
 5759 contain:
 5760 
 5761 01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
 5762 02:     bool
 5763 03:
 5764 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
 5765 05:     depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
 5766 06:     string
 5767 
 5768 In this file, we declare two options,
 5769 BR2_PACKAGE_HAS_SOMETHING_VIRTUAL and
 5770 BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL, whose values will be used by
 5771 the providers.
 5772 
 5773 18.11.3. Virtual package’s .mk file
 5774 
 5775 The .mk for the virtual package should just evaluate the
 5776 virtual-package macro:
 5777 
 5778 01: ################################################################################
 5779 02: #
 5780 03: # something-virtual
 5781 04: #
 5782 05: ################################################################################
 5783 06:
 5784 07: $(eval $(virtual-package))
 5785 
 5786 The ability to have target and host packages is also available, with
 5787 the host-virtual-package macro.
 5788 
 5789 18.11.4. Provider’s Config.in file
 5790 
 5791 When adding a package as a provider, only the Config.in file requires
 5792 some modifications.
 5793 
 5794 The Config.in file of the package some-provider, which provides the
 5795 functionalities of something-virtual, should contain:
 5796 
 5797 01: config BR2_PACKAGE_SOME_PROVIDER
 5798 02:     bool "some-provider"
 5799 03:     select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
 5800 04:     help
 5801 05:       This is a comment that explains what some-provider is.
 5802 06:
 5803 07:       http://foosoftware.org/some-provider/
 5804 08:
 5805 09: if BR2_PACKAGE_SOME_PROVIDER
 5806 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
 5807 11:     default "some-provider"
 5808 12: endif
 5809 
 5810 On line 3, we select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL, and on line
 5811 11, we set the value of BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL to the
 5812 name of the provider, but only if it is selected.
 5813 
 5814 18.11.5. Provider’s .mk file
 5815 
 5816 The .mk file should also declare an additional variable
 5817 SOME_PROVIDER_PROVIDES to contain the names of all the virtual
 5818 packages it is an implementation of:
 5819 
 5820 01: SOME_PROVIDER_PROVIDES = something-virtual
 5821 
 5822 Of course, do not forget to add the proper build and runtime
 5823 dependencies for this package!
 5824 
 5825 18.11.6. Notes on depending on a virtual package
 5826 
 5827 When adding a package that requires a certain FEATURE provided by a
 5828 virtual package, you have to use depends on BR2_PACKAGE_HAS_FEATURE,
 5829 like so:
 5830 
 5831 config BR2_PACKAGE_HAS_FEATURE
 5832     bool
 5833 
 5834 config BR2_PACKAGE_FOO
 5835     bool "foo"
 5836     depends on BR2_PACKAGE_HAS_FEATURE
 5837 
 5838 18.11.7. Notes on depending on a specific provider
 5839 
 5840 If your package really requires a specific provider, then you’ll have
 5841 to make your package depends on this provider; you can not select a
 5842 provider.
 5843 
 5844 Let’s take an example with two providers for a FEATURE:
 5845 
 5846 config BR2_PACKAGE_HAS_FEATURE
 5847     bool
 5848 
 5849 config BR2_PACKAGE_FOO
 5850     bool "foo"
 5851     select BR2_PACKAGE_HAS_FEATURE
 5852 
 5853 config BR2_PACKAGE_BAR
 5854     bool "bar"
 5855     select BR2_PACKAGE_HAS_FEATURE
 5856 
 5857 And you are adding a package that needs FEATURE as provided by foo,
 5858 but not as provided by bar.
 5859 
 5860 If you were to use select BR2_PACKAGE_FOO, then the user would still
 5861 be able to select BR2_PACKAGE_BAR in the menuconfig. This would
 5862 create a configuration inconsistency, whereby two providers of the
 5863 same FEATURE would be enabled at once, one explicitly set by the
 5864 user, the other implicitly by your select.
 5865 
 5866 Instead, you have to use depends on BR2_PACKAGE_FOO, which avoids any
 5867 implicit configuration inconsistency.
 5868 
 5869 18.12. Infrastructure for packages using kconfig for configuration
 5870 files
 5871 
 5872 A popular way for a software package to handle user-specified
 5873 configuration is kconfig. Among others, it is used by the Linux
 5874 kernel, Busybox, and Buildroot itself. The presence of a .config file
 5875 and a menuconfig target are two well-known symptoms of kconfig being
 5876 used.
 5877 
 5878 Buildroot features an infrastructure for packages that use kconfig
 5879 for their configuration. This infrastructure provides the necessary
 5880 logic to expose the package’s menuconfig target as foo-menuconfig in
 5881 Buildroot, and to handle the copying back and forth of the
 5882 configuration file in a correct way.
 5883 
 5884 The kconfig-package infrastructure is based on the generic-package
 5885 infrastructure. All variables supported by generic-package are
 5886 available in kconfig-package as well. See Section 18.5.2,
 5887 “generic-package reference” for more details.
 5888 
 5889 In order to use the kconfig-package infrastructure for a Buildroot
 5890 package, the minimally required lines in the .mk file, in addition to
 5891 the variables required by the generic-package infrastructure, are:
 5892 
 5893 FOO_KCONFIG_FILE = reference-to-source-configuration-file
 5894 
 5895 $(eval $(kconfig-package))
 5896 
 5897 This snippet creates the following make targets:
 5898 
 5899   * foo-menuconfig, which calls the package’s menuconfig target
 5900   * foo-update-config, which copies the configuration back to the
 5901     source configuration file. It is not possible to use this target
 5902     when fragment files are set.
 5903   * foo-update-defconfig, which copies the configuration back to the
 5904     source configuration file. The configuration file will only list
 5905     the options that differ from the default values. It is not
 5906     possible to use this target when fragment files are set.
 5907   * foo-diff-config, which outputs the differences between the
 5908     current configuration and the one defined in the Buildroot
 5909     configuration for this kconfig package. The output is useful to
 5910     identify the configuration changes that may have to be propagated
 5911     to configuration fragments for example.
 5912 
 5913 and ensures that the source configuration file is copied to the build
 5914 directory at the right moment.
 5915 
 5916 There are two options to specify a configuration file to use, either
 5917 FOO_KCONFIG_FILE (as in the example, above) or FOO_KCONFIG_DEFCONFIG.
 5918 It is mandatory to provide either, but not both:
 5919 
 5920   * FOO_KCONFIG_FILE specifies the path to a defconfig or full-config
 5921     file to be used to configure the package.
 5922   * FOO_KCONFIG_DEFCONFIG specifies the defconfig make rule to call
 5923     to configure the package.
 5924 
 5925 In addition to these minimally required lines, several optional
 5926 variables can be set to suit the needs of the package under
 5927 consideration:
 5928 
 5929   * FOO_KCONFIG_EDITORS: a space-separated list of kconfig editors to
 5930     support, for example menuconfig xconfig. By default, menuconfig.
 5931   * FOO_KCONFIG_FRAGMENT_FILES: a space-separated list of
 5932     configuration fragment files that are merged to the main
 5933     configuration file. Fragment files are typically used when there
 5934     is a desire to stay in sync with an upstream (def)config file,
 5935     with some minor modifications.
 5936   * FOO_KCONFIG_OPTS: extra options to pass when calling the kconfig
 5937     editors. This may need to include $(FOO_MAKE_OPTS), for example.
 5938     By default, empty.
 5939   * FOO_KCONFIG_FIXUP_CMDS: a list of shell commands needed to fixup
 5940     the configuration file after copying it or running a kconfig
 5941     editor. Such commands may be needed to ensure a configuration
 5942     consistent with other configuration of Buildroot, for example. By
 5943     default, empty.
 5944   * FOO_KCONFIG_DOTCONFIG: path (with filename) of the .config file,
 5945     relative to the package source tree. The default, .config, should
 5946     be well suited for all packages that use the standard kconfig
 5947     infrastructure as inherited from the Linux kernel; some packages
 5948     use a derivative of kconfig that use a different location.
 5949   * FOO_KCONFIG_DEPENDENCIES: the list of packages (most probably,
 5950     host packages) that need to be built before this package’s
 5951     kconfig is interpreted. Seldom used. By default, empty.
 5952 
 5953 18.13. Infrastructure for rebar-based packages
 5954 
 5955 18.13.1. rebar-package tutorial
 5956 
 5957 First, let’s see how to write a .mk file for a rebar-based package,
 5958 with an example :
 5959 
 5960 01: ################################################################################
 5961 02: #
 5962 03: # erlang-foobar
 5963 04: #
 5964 05: ################################################################################
 5965 06:
 5966 07: ERLANG_FOOBAR_VERSION = 1.0
 5967 08: ERLANG_FOOBAR_SOURCE = erlang-foobar-$(ERLANG_FOOBAR_VERSION).tar.xz
 5968 09: ERLANG_FOOBAR_SITE = http://www.foosoftware.org/download
 5969 10: ERLANG_FOOBAR_DEPENDENCIES = host-libaaa libbbb
 5970 11:
 5971 12: $(eval $(rebar-package))
 5972 
 5973 On line 7, we declare the version of the package.
 5974 
 5975 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 5976 recommended) and the location of the tarball on the Web. Buildroot
 5977 will automatically download the tarball from this location.
 5978 
 5979 On line 10, we declare our dependencies, so that they are built
 5980 before the build process of our package starts.
 5981 
 5982 Finally, on line 12, we invoke the rebar-package macro that generates
 5983 all the Makefile rules that actually allows the package to be built.
 5984 
 5985 18.13.2. rebar-package reference
 5986 
 5987 The main macro of the rebar package infrastructure is rebar-package.
 5988 It is similar to the generic-package macro. The ability to have host
 5989 packages is also available, with the host-rebar-package macro.
 5990 
 5991 Just like the generic infrastructure, the rebar infrastructure works
 5992 by defining a number of variables before calling the rebar-package
 5993 macro.
 5994 
 5995 First, all the package metadata information variables that exist in
 5996 the generic infrastructure also exist in the rebar infrastructure:
 5997 ERLANG_FOOBAR_VERSION, ERLANG_FOOBAR_SOURCE, ERLANG_FOOBAR_PATCH,
 5998 ERLANG_FOOBAR_SITE, ERLANG_FOOBAR_SUBDIR, ERLANG_FOOBAR_DEPENDENCIES,
 5999 ERLANG_FOOBAR_INSTALL_STAGING, ERLANG_FOOBAR_INSTALL_TARGET,
 6000 ERLANG_FOOBAR_LICENSE and ERLANG_FOOBAR_LICENSE_FILES.
 6001 
 6002 A few additional variables, specific to the rebar infrastructure, can
 6003 also be defined. Many of them are only useful in very specific cases,
 6004 typical packages will therefore only use a few of them.
 6005 
 6006   * ERLANG_FOOBAR_USE_AUTOCONF, to specify that the package uses 
 6007     autoconf at the configuration step. When a package sets this
 6008     variable to YES, the autotools infrastructure is used.
 6009 
 6010     Note. You can also use some of the variables from the autotools
 6011     infrastructure: ERLANG_FOOBAR_CONF_ENV, ERLANG_FOOBAR_CONF_OPTS,
 6012     ERLANG_FOOBAR_AUTORECONF, ERLANG_FOOBAR_AUTORECONF_ENV and
 6013     ERLANG_FOOBAR_AUTORECONF_OPTS.
 6014 
 6015   * ERLANG_FOOBAR_USE_BUNDLED_REBAR, to specify that the package has
 6016     a bundled version of rebar and that it shall be used. Valid
 6017     values are YES or NO (the default).
 6018 
 6019     Note. If the package bundles a rebar utility, but can use the
 6020     generic one that Buildroot provides, just say NO (i.e., do not
 6021     specify this variable). Only set if it is mandatory to use the 
 6022     rebar utility bundled in this package.
 6023 
 6024   * ERLANG_FOOBAR_REBAR_ENV, to specify additional environment
 6025     variables to pass to the rebar utility.
 6026   * ERLANG_FOOBAR_KEEP_DEPENDENCIES, to keep the dependencies
 6027     described in the rebar.config file. Valid values are YES or NO
 6028     (the default). Unless this variable is set to YES, the rebar
 6029     infrastructure removes such dependencies in a post-patch hook to
 6030     ensure rebar does not download nor compile them.
 6031 
 6032 With the rebar infrastructure, all the steps required to build and
 6033 install the packages are already defined, and they generally work
 6034 well for most rebar-based packages. However, when required, it is
 6035 still possible to customize what is done in any particular step:
 6036 
 6037   * By adding a post-operation hook (after extract, patch, configure,
 6038     build or install). See Section 18.22, “Hooks available in the
 6039     various build steps” for details.
 6040   * By overriding one of the steps. For example, even if the rebar
 6041     infrastructure is used, if the package .mk file defines its own
 6042     ERLANG_FOOBAR_BUILD_CMDS variable, it will be used instead of the
 6043     default rebar one. However, using this method should be
 6044     restricted to very specific cases. Do not use it in the general
 6045     case.
 6046 
 6047 18.14. Infrastructure for Waf-based packages
 6048 
 6049 18.14.1. waf-package tutorial
 6050 
 6051 First, let’s see how to write a .mk file for a Waf-based package,
 6052 with an example :
 6053 
 6054 01: ################################################################################
 6055 02: #
 6056 03: # libfoo
 6057 04: #
 6058 05: ################################################################################
 6059 06:
 6060 07: LIBFOO_VERSION = 1.0
 6061 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 6062 09: LIBFOO_SITE = http://www.foosoftware.org/download
 6063 10: LIBFOO_CONF_OPTS = --enable-bar --disable-baz
 6064 11: LIBFOO_DEPENDENCIES = bar
 6065 12:
 6066 13: $(eval $(waf-package))
 6067 
 6068 On line 7, we declare the version of the package.
 6069 
 6070 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 6071 recommended) and the location of the tarball on the Web. Buildroot
 6072 will automatically download the tarball from this location.
 6073 
 6074 On line 10, we tell Buildroot what options to enable for libfoo.
 6075 
 6076 On line 11, we tell Buildroot the dependencies of libfoo.
 6077 
 6078 Finally, on line line 13, we invoke the waf-package macro that
 6079 generates all the Makefile rules that actually allows the package to
 6080 be built.
 6081 
 6082 18.14.2. waf-package reference
 6083 
 6084 The main macro of the Waf package infrastructure is waf-package. It
 6085 is similar to the generic-package macro.
 6086 
 6087 Just like the generic infrastructure, the Waf infrastructure works by
 6088 defining a number of variables before calling the waf-package macro.
 6089 
 6090 First, all the package metadata information variables that exist in
 6091 the generic infrastructure also exist in the Waf infrastructure:
 6092 LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
 6093 LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
 6094 LIBFOO_INSTALL_TARGET.
 6095 
 6096 An additional variable, specific to the Waf infrastructure, can also
 6097 be defined.
 6098 
 6099   * LIBFOO_SUBDIR may contain the name of a subdirectory inside the
 6100     package that contains the main wscript file. This is useful, if
 6101     for example, the main wscript file is not at the root of the tree
 6102     extracted by the tarball. If HOST_LIBFOO_SUBDIR is not specified,
 6103     it defaults to LIBFOO_SUBDIR.
 6104   * LIBFOO_NEEDS_EXTERNAL_WAF can be set to YES or NO to tell
 6105     Buildroot to use the bundled waf executable. If set to NO, the
 6106     default, then Buildroot will use the waf executable provided in
 6107     the package source tree; if set to YES, then Buildroot will
 6108     download, install waf as a host tool and use it to build the
 6109     package.
 6110   * LIBFOO_WAF_OPTS, to specify additional options to pass to the waf
 6111     script at every step of the package build process: configure,
 6112     build and installation. By default, empty.
 6113   * LIBFOO_CONF_OPTS, to specify additional options to pass to the
 6114     waf script for the configuration step. By default, empty.
 6115   * LIBFOO_BUILD_OPTS, to specify additional options to pass to the
 6116     waf script during the build step. By default, empty.
 6117   * LIBFOO_INSTALL_STAGING_OPTS, to specify additional options to
 6118     pass to the waf script during the staging installation step. By
 6119     default, empty.
 6120   * LIBFOO_INSTALL_TARGET_OPTS, to specify additional options to pass
 6121     to the waf script during the target installation step. By
 6122     default, empty.
 6123 
 6124 18.15. Infrastructure for Meson-based packages
 6125 
 6126 18.15.1. meson-package tutorial
 6127 
 6128 Meson [http://mesonbuild.com] is an open source build system meant to
 6129 be both extremely fast, and, even more importantly, as user friendly
 6130 as possible. It uses Ninja [https://ninja-build.org] as a companion
 6131 tool to perform the actual build operations.
 6132 
 6133 Let’s see how to write a .mk file for a Meson-based package, with an
 6134 example:
 6135 
 6136 01: ################################################################################
 6137 02: #
 6138 03: # foo
 6139 04: #
 6140 05: ################################################################################
 6141 06:
 6142 07: FOO_VERSION = 1.0
 6143 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
 6144 09: FOO_SITE = http://www.foosoftware.org/download
 6145 10: FOO_LICENSE = GPL-3.0+
 6146 11: FOO_LICENSE_FILES = COPYING
 6147 12: FOO_INSTALL_STAGING = YES
 6148 13:
 6149 14: FOO_DEPENDENCIES = host-pkgconf bar
 6150 15:
 6151 16: ifeq ($(BR2_PACKAGE_BAZ),y)
 6152 17: FOO_CONF_OPTS += -Dbaz=true
 6153 18: FOO_DEPENDENCIES += baz
 6154 19: else
 6155 20: FOO_CONF_OPTS += -Dbaz=false
 6156 21: endif
 6157 22:
 6158 23: $(eval $(meson-package))
 6159 
 6160 The Makefile starts with the definition of the standard variables for
 6161 package declaration (lines 7 to 11).
 6162 
 6163 On line line 23, we invoke the meson-package macro that generates all
 6164 the Makefile rules that actually allows the package to be built.
 6165 
 6166 In the example, host-pkgconf and bar are declared as dependencies in
 6167 FOO_DEPENDENCIES at line 14 because the Meson build file of foo uses
 6168 pkg-config to determine the compilation flags and libraries of
 6169 package bar.
 6170 
 6171 Note that it is not necessary to add host-meson in the
 6172 FOO_DEPENDENCIES variable of a package, since this basic dependency
 6173 is automatically added as needed by the Meson package infrastructure.
 6174 
 6175 If the "baz" package is selected, then support for the "baz" feature
 6176 in "foo" is activated by adding -Dbaz=true to FOO_CONF_OPTS at line
 6177 17, as specified in the meson_options.txt file in "foo" source tree.
 6178 The "baz" package is also added to FOO_DEPENDENCIES. Note that the
 6179 support for baz is explicitly disabled at line 20, if the package is
 6180 not selected.
 6181 
 6182 To sum it up, to add a new meson-based package, the Makefile example
 6183 can be copied verbatim then edited to replace all occurences of FOO
 6184 with the uppercase name of the new package and update the values of
 6185 the standard variables.
 6186 
 6187 18.15.2. meson-package reference
 6188 
 6189 The main macro of the Meson package infrastructure is meson-package.
 6190 It is similar to the generic-package macro. The ability to have
 6191 target and host packages is also available, with the
 6192 host-meson-package macro.
 6193 
 6194 Just like the generic infrastructure, the Meson infrastructure works
 6195 by defining a number of variables before calling the meson-package
 6196 macro.
 6197 
 6198 First, all the package metadata information variables that exist in
 6199 the generic infrastructure also exist in the Meson infrastructure:
 6200 FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR,
 6201 FOO_DEPENDENCIES, FOO_INSTALL_STAGING, FOO_INSTALL_TARGET.
 6202 
 6203 A few additional variables, specific to the Meson infrastructure, can
 6204 also be defined. Many of them are only useful in very specific cases,
 6205 typical packages will therefore only use a few of them.
 6206 
 6207   * FOO_SUBDIR may contain the name of a subdirectory inside the
 6208     package that contains the main meson.build file. This is useful,
 6209     if for example, the main meson.build file is not at the root of
 6210     the tree extracted by the tarball. If HOST_FOO_SUBDIR is not
 6211     specified, it defaults to FOO_SUBDIR.
 6212   * FOO_CONF_ENV, to specify additional environment variables to pass
 6213     to meson for the configuration step. By default, empty.
 6214   * FOO_CONF_OPTS, to specify additional options to pass to meson for
 6215     the configuration step. By default, empty.
 6216   * FOO_CFLAGS, to specify compiler arguments added to the package
 6217     specific cross-compile.conf file c_args property. By default, the
 6218     value of TARGET_CFLAGS.
 6219   * FOO_CXXFLAGS, to specify compiler arguments added to the package
 6220     specific cross-compile.conf file cpp_args property. By default,
 6221     the value of TARGET_CXXFLAGS.
 6222   * FOO_LDFLAGS, to specify compiler arguments added to the package
 6223     specific cross-compile.conf file c_link_args and cpp_link_args
 6224     properties. By default, the value of TARGET_LDFLAGS.
 6225   * FOO_MESON_EXTRA_BINARIES, to specify a space-separated list of
 6226     programs to add to the [binaries] section of the meson
 6227     cross-compilation.conf configuration file. The format is
 6228     program-name='/path/to/program', with no space around the = sign,
 6229     and with the path of the program between single quotes. By
 6230     default, empty. Note that Buildroot already sets the correct
 6231     values for c, cpp, ar, strip, and pkgconfig.
 6232   * FOO_MESON_EXTRA_PROPERTIES, to specify a space-separated list of
 6233     properties to add to the [properties] section of the meson
 6234     cross-compilation.conf configuration file. The format is
 6235     property-name=<value> with no space around the = sign, and with
 6236     single quotes around string values. By default, empty. Note that
 6237     Buildroot already sets values for needs_exe_wrapper, c_args,
 6238     c_link_args, cpp_args, cpp_link_args, sys_root, and
 6239     pkg_config_libdir.
 6240   * FOO_NINJA_ENV, to specify additional environment variables to
 6241     pass to ninja, meson companion tool in charge of the build
 6242     operations. By default, empty.
 6243   * FOO_NINJA_OPTS, to specify a space-separated list of targets to
 6244     build. By default, empty, to build the default target(s).
 6245 
 6246 18.16. Integration of Cargo-based packages
 6247 
 6248 Cargo is the package manager for the Rust programming language. It
 6249 allows the user to build programs or libraries written in Rust, but
 6250 it also downloads and manages their dependencies, to ensure
 6251 repeatable builds. Cargo packages are called "crates".
 6252 
 6253 18.16.1. Cargo-based package’s Config.in file
 6254 
 6255 The Config.in file of Cargo-based package foo should contain:
 6256 
 6257 01: config BR2_PACKAGE_FOO
 6258 02:     bool "foo"
 6259 03:     depends on BR2_PACKAGE_HOST_RUSTC_TARGET_ARCH_SUPPORTS
 6260 04:     select BR2_PACKAGE_HOST_RUSTC
 6261 05:     help
 6262 06:       This is a comment that explains what foo is.
 6263 07:
 6264 08:       http://foosoftware.org/foo/
 6265 
 6266 18.16.2. Cargo-based package’s .mk file
 6267 
 6268 Buildroot does not (yet) provide a dedicated package infrastructure
 6269 for Cargo-based packages. So, we will explain how to write a .mk file
 6270 for such a package. Let’s start with an example:
 6271 
 6272 01: ################################################################################
 6273 02: #
 6274 03: # foo
 6275 04: #
 6276 05: ################################################################################
 6277 06:
 6278 07: FOO_VERSION = 1.0
 6279 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.gz
 6280 09: FOO_SITE = http://www.foosoftware.org/download
 6281 10: FOO_LICENSE = GPL-3.0+
 6282 11: FOO_LICENSE_FILES = COPYING
 6283 12:
 6284 13: FOO_DEPENDENCIES = host-rustc
 6285 14:
 6286 15: FOO_CARGO_ENV = CARGO_HOME=$(HOST_DIR)/share/cargo
 6287 16:
 6288 17: FOO_BIN_DIR = target/$(RUSTC_TARGET_NAME)/$(FOO_CARGO_MODE)
 6289 18:
 6290 19: FOO_CARGO_OPTS = \
 6291 20:     $(if $(BR2_ENABLE_DEBUG),,--release) \
 6292 21:     --target=$(RUSTC_TARGET_NAME) \
 6293 22:     --manifest-path=$(@D)/Cargo.toml
 6294 23:
 6295 24: define FOO_BUILD_CMDS
 6296 25:     $(TARGET_MAKE_ENV) $(FOO_CARGO_ENV) \
 6297 26:             cargo build $(FOO_CARGO_OPTS)
 6298 27: endef
 6299 28:
 6300 29: define FOO_INSTALL_TARGET_CMDS
 6301 30:     $(INSTALL) -D -m 0755 $(@D)/$(FOO_BIN_DIR)/foo \
 6302 31:             $(TARGET_DIR)/usr/bin/foo
 6303 32: endef
 6304 33:
 6305 34: $(eval $(generic-package))
 6306 
 6307 The Makefile starts with the definition of the standard variables for
 6308 package declaration (lines 7 to 11).
 6309 
 6310 As seen in line 34, it is based on the generic-package infrastructure
 6311 . So, it defines the variables required by this particular
 6312 infrastructure, where Cargo is invoked:
 6313 
 6314   * FOO_BUILD_CMDS: Cargo is invoked to perform the build. The
 6315     options required to configure the cross-compilation of the
 6316     package are passed via FOO_CONF_OPTS.
 6317   * FOO_INSTALL_TARGET_CMDS: The binary executable generated is
 6318     installed on the target.
 6319 
 6320 In order to have Cargo available for the build, FOO_DEPENDENCIES
 6321 needs to contain host-cargo.
 6322 
 6323 To sum it up, to add a new Cargo-based package, the Makefile example
 6324 can be copied verbatim then edited to replace all occurences of FOO
 6325 with the uppercase name of the new package and update the values of
 6326 the standard variables.
 6327 
 6328 18.16.3. About Dependencies Management
 6329 
 6330 A crate can depend on other libraries from crates.io or git
 6331 repositories, listed in its Cargo.toml file. Before starting a build,
 6332 Cargo usually downloads automatically them. This step can also be
 6333 performed independently, via the cargo fetch command.
 6334 
 6335 Cargo maintains a local cache of the registry index and of git
 6336 checkouts of the crates, whose location is given by $CARGO_HOME. As
 6337 seen in the package Makefile example at line 15, this environment
 6338 variable is set to $(HOST_DIR)/share/cargo.
 6339 
 6340 This dependency download mechanism is not convenient when performing
 6341 an offline build, as Cargo will fail to fetch the dependencies. In
 6342 that case, it is advised to generate a tarball of the dependencies
 6343 using the cargo vendor and add it to FOO_EXTRA_DOWNLOADS.
 6344 
 6345 18.17. Infrastructure for Go packages
 6346 
 6347 This infrastructure applies to Go packages that use the standard
 6348 build system and use bundled dependencies.
 6349 
 6350 18.17.1. golang-package tutorial
 6351 
 6352 First, let’s see how to write a .mk file for a go package, with an
 6353 example :
 6354 
 6355 01: ################################################################################
 6356 02: #
 6357 03: # foo
 6358 04: #
 6359 05: ################################################################################
 6360 06:
 6361 07: FOO_VERSION = 1.0
 6362 08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
 6363 09: FOO_LICENSE = BSD-3-Clause
 6364 10: FOO_LICENSE_FILES = LICENSE
 6365 11:
 6366 12: $(eval $(golang-package))
 6367 
 6368 On line 7, we declare the version of the package.
 6369 
 6370 On line 8, we declare the upstream location of the package, here
 6371 fetched from Github, since a large number of Go packages are hosted
 6372 on Github.
 6373 
 6374 On line 9 and 10, we give licensing details about the package.
 6375 
 6376 Finally, on line 12, we invoke the golang-package macro that
 6377 generates all the Makefile rules that actually allow the package to
 6378 be built.
 6379 
 6380 18.17.2. golang-package reference
 6381 
 6382 In their Config.in file, packages using the golang-package
 6383 infrastructure should depend on
 6384 BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS because Buildroot will
 6385 automatically add a dependency on host-go to such packages. If you
 6386 need CGO support in your package, you must add a dependency on
 6387 BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS.
 6388 
 6389 The main macro of the Go package infrastructure is golang-package. It
 6390 is similar to the generic-package macro. The ability to build host
 6391 packages is also available, with the host-golang-package macro. Host
 6392 packages built by host-golang-package macro should depend on
 6393 BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
 6394 
 6395 Just like the generic infrastructure, the Go infrastructure works by
 6396 defining a number of variables before calling the golang-package.
 6397 
 6398 All the package metadata information variables that exist in the
 6399 generic package infrastructure also exist in the Go infrastructure:
 6400 FOO_VERSION, FOO_SOURCE, FOO_PATCH, FOO_SITE, FOO_SUBDIR,
 6401 FOO_DEPENDENCIES, FOO_LICENSE, FOO_LICENSE_FILES,
 6402 FOO_INSTALL_STAGING, etc.
 6403 
 6404 Note that it is not necessary to add host-go in the FOO_DEPENDENCIES
 6405 variable of a package, since this basic dependency is automatically
 6406 added as needed by the Go package infrastructure.
 6407 
 6408 A few additional variables, specific to the Go infrastructure, can
 6409 optionally be defined, depending on the package’s needs. Many of them
 6410 are only useful in very specific cases, typical packages will
 6411 therefore only use a few of them, or none.
 6412 
 6413   * The package must specify its Go module name in the FOO_GOMOD
 6414     variable. If not specified, it defaults to URL-domain/
 6415     1st-part-of-URL/2nd-part-of-URL, e.g FOO_GOMOD will take the
 6416     value github.com/bar/foo for a package that specifies FOO_SITE =
 6417     $(call github,bar,foo,$(FOO_VERSION)). The Go package
 6418     infrastructure will automatically generate a minimal go.mod file
 6419     in the package source tree if it doesn’t exist.
 6420   * FOO_LDFLAGS and FOO_TAGS can be used to pass respectively the
 6421     LDFLAGS or the TAGS to the go build command.
 6422   * FOO_BUILD_TARGETS can be used to pass the list of targets that
 6423     should be built. If FOO_BUILD_TARGETS is not specified, it
 6424     defaults to .. We then have two cases:
 6425 
 6426       + FOO_BUILD_TARGETS is .. In this case, we assume only one
 6427         binary will be produced, and that by default we name it after
 6428         the package name. If that is not appropriate, the name of the
 6429         produced binary can be overridden using FOO_BIN_NAME.
 6430       + FOO_BUILD_TARGETS is not .. In this case, we iterate over the
 6431         values to build each target, and for each produced a binary
 6432         that is the non-directory component of the target. For
 6433         example if FOO_BUILD_TARGETS = cmd/docker cmd/dockerd the
 6434         binaries produced are docker and dockerd.
 6435   * FOO_INSTALL_BINS can be used to pass the list of binaries that
 6436     should be installed in /usr/bin on the target. If
 6437     FOO_INSTALL_BINS is not specified, it defaults to the lower-case
 6438     name of package.
 6439 
 6440 With the Go infrastructure, all the steps required to build and
 6441 install the packages are already defined, and they generally work
 6442 well for most Go-based packages. However, when required, it is still
 6443 possible to customize what is done in any particular step:
 6444 
 6445   * By adding a post-operation hook (after extract, patch, configure,
 6446     build or install). See Section 18.22, “Hooks available in the
 6447     various build steps” for details.
 6448   * By overriding one of the steps. For example, even if the Go
 6449     infrastructure is used, if the package .mk file defines its own
 6450     FOO_BUILD_CMDS variable, it will be used instead of the default
 6451     Go one. However, using this method should be restricted to very
 6452     specific cases. Do not use it in the general case.
 6453 
 6454 18.18. Infrastructure for QMake-based packages
 6455 
 6456 18.18.1. qmake-package tutorial
 6457 
 6458 First, let’s see how to write a .mk file for a QMake-based package,
 6459 with an example :
 6460 
 6461 01: ################################################################################
 6462 02: #
 6463 03: # libfoo
 6464 04: #
 6465 05: ################################################################################
 6466 06:
 6467 07: LIBFOO_VERSION = 1.0
 6468 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 6469 09: LIBFOO_SITE = http://www.foosoftware.org/download
 6470 10: LIBFOO_CONF_OPTS = QT_CONFIG+=bar QT_CONFIG-=baz
 6471 11: LIBFOO_DEPENDENCIES = bar
 6472 12:
 6473 13: $(eval $(qmake-package))
 6474 
 6475 On line 7, we declare the version of the package.
 6476 
 6477 On line 8 and 9, we declare the name of the tarball (xz-ed tarball
 6478 recommended) and the location of the tarball on the Web. Buildroot
 6479 will automatically download the tarball from this location.
 6480 
 6481 On line 10, we tell Buildroot what options to enable for libfoo.
 6482 
 6483 On line 11, we tell Buildroot the dependencies of libfoo.
 6484 
 6485 Finally, on line line 13, we invoke the qmake-package macro that
 6486 generates all the Makefile rules that actually allows the package to
 6487 be built.
 6488 
 6489 18.18.2. qmake-package reference
 6490 
 6491 The main macro of the QMake package infrastructure is qmake-package.
 6492 It is similar to the generic-package macro.
 6493 
 6494 Just like the generic infrastructure, the QMake infrastructure works
 6495 by defining a number of variables before calling the qmake-package
 6496 macro.
 6497 
 6498 First, all the package metadata information variables that exist in
 6499 the generic infrastructure also exist in the QMake infrastructure:
 6500 LIBFOO_VERSION, LIBFOO_SOURCE, LIBFOO_PATCH, LIBFOO_SITE,
 6501 LIBFOO_SUBDIR, LIBFOO_DEPENDENCIES, LIBFOO_INSTALL_STAGING,
 6502 LIBFOO_INSTALL_TARGET.
 6503 
 6504 An additional variable, specific to the QMake infrastructure, can
 6505 also be defined.
 6506 
 6507   * LIBFOO_CONF_ENV, to specify additional environment variables to
 6508     pass to the qmake script for the configuration step. By default,
 6509     empty.
 6510   * LIBFOO_CONF_OPTS, to specify additional options to pass to the
 6511     qmake script for the configuration step. By default, empty.
 6512   * LIBFOO_MAKE_ENV, to specify additional environment variables to
 6513     the make command during the build and install steps. By default,
 6514     empty.
 6515   * LIBFOO_MAKE_OPTS, to specify additional targets to pass to the
 6516     make command during the build step. By default, empty.
 6517   * LIBFOO_INSTALL_STAGING_OPTS, to specify additional targets to
 6518     pass to the make command during the staging installation step. By
 6519     default, install.
 6520   * LIBFOO_INSTALL_TARGET_OPTS, to specify additional targets to pass
 6521     to the make command during the target installation step. By
 6522     default, install.
 6523   * LIBFOO_SYNC_HEADERS, to run syncqt.pl before qmake. Some packages
 6524     need this to have a properly populated include directory before
 6525     running the build.
 6526 
 6527 18.19. Infrastructure for packages building kernel modules
 6528 
 6529 Buildroot offers a helper infrastructure to make it easy to write
 6530 packages that build and install Linux kernel modules. Some packages
 6531 only contain a kernel module, other packages contain programs and
 6532 libraries in addition to kernel modules. Buildroot’s helper
 6533 infrastructure supports either case.
 6534 
 6535 18.19.1. kernel-module tutorial
 6536 
 6537 Let’s start with an example on how to prepare a simple package that
 6538 only builds a kernel module, and no other component:
 6539 
 6540 01: ################################################################################
 6541 02: #
 6542 03: # foo
 6543 04: #
 6544 05: ################################################################################
 6545 06:
 6546 07: FOO_VERSION = 1.2.3
 6547 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
 6548 09: FOO_SITE = http://www.foosoftware.org/download
 6549 10: FOO_LICENSE = GPL-2.0
 6550 11: FOO_LICENSE_FILES = COPYING
 6551 12:
 6552 13: $(eval $(kernel-module))
 6553 14: $(eval $(generic-package))
 6554 
 6555 Lines 7-11 define the usual meta-data to specify the version, archive
 6556 name, remote URI where to find the package source, licensing
 6557 information.
 6558 
 6559 On line 13, we invoke the kernel-module helper infrastructure, that
 6560 generates all the appropriate Makefile rules and variables to build
 6561 that kernel module.
 6562 
 6563 Finally, on line 14, we invoke the generic-package infrastructure.
 6564 
 6565 The dependency on linux is automatically added, so it is not needed
 6566 to specify it in FOO_DEPENDENCIES.
 6567 
 6568 What you may have noticed is that, unlike other package
 6569 infrastructures, we explicitly invoke a second infrastructure. This
 6570 allows a package to build a kernel module, but also, if needed, use
 6571 any one of other package infrastructures to build normal userland
 6572 components (libraries, executables…). Using the kernel-module
 6573 infrastructure on its own is not sufficient; another package
 6574 infrastructure must be used.
 6575 
 6576 Let’s look at a more complex example:
 6577 
 6578 01: ################################################################################
 6579 02: #
 6580 03: # foo
 6581 04: #
 6582 05: ################################################################################
 6583 06:
 6584 07: FOO_VERSION = 1.2.3
 6585 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
 6586 09: FOO_SITE = http://www.foosoftware.org/download
 6587 10: FOO_LICENSE = GPL-2.0
 6588 11: FOO_LICENSE_FILES = COPYING
 6589 12:
 6590 13: FOO_MODULE_SUBDIRS = driver/base
 6591 14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
 6592 15:
 6593 16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
 6594 17: FOO_DEPENDENCIES = libbar
 6595 18: FOO_CONF_OPTS = --enable-bar
 6596 19: FOO_MODULE_SUBDIRS += driver/bar
 6597 20: else
 6598 21: FOO_CONF_OPTS = --disable-bar
 6599 22: endif
 6600 23:
 6601 24: $(eval $(kernel-module))
 6602 26: $(eval $(autotools-package))
 6603 
 6604 Here, we see that we have an autotools-based package, that also
 6605 builds the kernel module located in sub-directory driver/base and, if
 6606 libbar is enabled, the kernel module located in sub-directory driver/
 6607 bar, and defines the variable KVERSION to be passed to the Linux
 6608 buildsystem when building the module(s).
 6609 
 6610 18.19.2. kernel-module reference
 6611 
 6612 The main macro for the kernel module infrastructure is kernel-module.
 6613 Unlike other package infrastructures, it is not stand-alone, and
 6614 requires any of the other *-package macros be called after it.
 6615 
 6616 The kernel-module macro defines post-build and post-target-install
 6617 hooks to build the kernel modules. If the package’s .mk needs access
 6618 to the built kernel modules, it should do so in a post-build hook, 
 6619 registered after the call to kernel-module. Similarly, if the
 6620 package’s .mk needs access to the kernel module after it has been
 6621 installed, it should do so in a post-install hook, registered after
 6622 the call to kernel-module. Here’s an example:
 6623 
 6624 $(eval $(kernel-module))
 6625 
 6626 define FOO_DO_STUFF_WITH_KERNEL_MODULE
 6627     # Do something with it...
 6628 endef
 6629 FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE
 6630 
 6631 $(eval $(generic-package))
 6632 
 6633 Finally, unlike the other package infrastructures, there is no
 6634 host-kernel-module variant to build a host kernel module.
 6635 
 6636 The following additional variables can optionally be defined to
 6637 further configure the build of the kernel module:
 6638 
 6639   * FOO_MODULE_SUBDIRS may be set to one or more sub-directories
 6640     (relative to the package source top-directory) where the kernel
 6641     module sources are. If empty or not set, the sources for the
 6642     kernel module(s) are considered to be located at the top of the
 6643     package source tree.
 6644   * FOO_MODULE_MAKE_OPTS may be set to contain extra variable
 6645     definitions to pass to the Linux buildsystem.
 6646 
 6647 You may also reference (but you may not set!) those variables:
 6648 
 6649   * LINUX_DIR contains the path to where the Linux kernel has been
 6650     extracted and built.
 6651   * LINUX_VERSION contains the version string as configured by the
 6652     user.
 6653   * LINUX_VERSION_PROBED contains the real version string of the
 6654     kernel, retrieved with running make -C $(LINUX_DIR) kernelrelease
 6655   * KERNEL_ARCH contains the name of the current architecture, like
 6656     arm, mips…
 6657 
 6658 18.20. Infrastructure for asciidoc documents
 6659 
 6660 The Buildroot manual, which you are currently reading, is entirely
 6661 written using the AsciiDoc [http://asciidoc.org/] mark-up syntax. The
 6662 manual is then rendered to many formats:
 6663 
 6664   * html
 6665   * split-html
 6666   * pdf
 6667   * epub
 6668   * text
 6669 
 6670 Although Buildroot only contains one document written in AsciiDoc,
 6671 there is, as for packages, an infrastructure for rendering documents
 6672 using the AsciiDoc syntax.
 6673 
 6674 Also as for packages, the AsciiDoc infrastructure is available from a
 6675 br2-external tree. This allows documentation for a br2-external tree
 6676 to match the Buildroot documentation, as it will be rendered to the
 6677 same formats and use the same layout and theme.
 6678 
 6679 18.20.1. asciidoc-document tutorial
 6680 
 6681 Whereas package infrastructures are suffixed with -package, the
 6682 document infrastructures are suffixed with -document. So, the
 6683 AsciiDoc infrastructure is named asciidoc-document.
 6684 
 6685 Here is an example to render a simple AsciiDoc document.
 6686 
 6687 01: ################################################################################
 6688 02: #
 6689 03: # foo-document
 6690 04: #
 6691 05: ################################################################################
 6692 06:
 6693 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
 6694 08: $(eval $(call asciidoc-document))
 6695 
 6696 On line 7, the Makefile declares what the sources of the document
 6697 are. Currently, it is expected that the document’s sources are only
 6698 local; Buildroot will not attempt to download anything to render a
 6699 document. Thus, you must indicate where the sources are. Usually, the
 6700 string above is sufficient for a document with no sub-directory
 6701 structure.
 6702 
 6703 On line 8, we call the asciidoc-document function, which generates
 6704 all the Makefile code necessary to render the document.
 6705 
 6706 18.20.2. asciidoc-document reference
 6707 
 6708 The list of variables that can be set in a .mk file to give metadata
 6709 information is (assuming the document name is foo) :
 6710 
 6711   * FOO_SOURCES, mandatory, defines the source files for the
 6712     document.
 6713   * FOO_RESOURCES, optional, may contain a space-separated list of
 6714     paths to one or more directories containing so-called resources
 6715     (like CSS or images). By default, empty.
 6716   * FOO_DEPENDENCIES, optional, the list of packages (most probably,
 6717     host-packages) that must be built before building this document.
 6718 
 6719 There are also additional hooks (see Section 18.22, “Hooks available
 6720 in the various build steps” for general information on hooks), that a
 6721 document may set to define extra actions to be done at various steps:
 6722 
 6723   * FOO_POST_RSYNC_HOOKS to run additional commands after the sources
 6724     have been copied by Buildroot. This can for example be used to
 6725     generate part of the manual with information extracted from the
 6726     tree. As an example, Buildroot uses this hook to generate the
 6727     tables in the appendices.
 6728   * FOO_CHECK_DEPENDENCIES_HOOKS to run additional tests on required
 6729     components to generate the document. In AsciiDoc, it is possible
 6730     to call filters, that is, programs that will parse an AsciiDoc
 6731     block and render it appropriately (e.g. ditaa [http://
 6732     ditaa.sourceforge.net/] or aafigure [https://pythonhosted.org/
 6733     aafigure/]).
 6734   * FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS, to run additional tests for
 6735     the specified format <FMT> (see the list of rendered formats,
 6736     above).
 6737 
 6738 Here is a complete example that uses all variables and all hooks:
 6739 
 6740 01: ################################################################################
 6741 02: #
 6742 03: # foo-document
 6743 04: #
 6744 05: ################################################################################
 6745 06:
 6746 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
 6747 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
 6748 09:
 6749 10: define FOO_GEN_EXTRA_DOC
 6750 11:     /path/to/generate-script --outdir=$(@D)
 6751 12: endef
 6752 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
 6753 14:
 6754 15: define FOO_CHECK_MY_PROG
 6755 16:     if ! which my-prog >/dev/null 2>&1; then \
 6756 17:         echo "You need my-prog to generate the foo document"; \
 6757 18:         exit 1; \
 6758 19:     fi
 6759 20: endef
 6760 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
 6761 22:
 6762 23: define FOO_CHECK_MY_OTHER_PROG
 6763 24:     if ! which my-other-prog >/dev/null 2>&1; then \
 6764 25:         echo "You need my-other-prog to generate the foo document as PDF"; \
 6765 26:         exit 1; \
 6766 27:     fi
 6767 28: endef
 6768 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
 6769 30:
 6770 31: $(eval $(call asciidoc-document))
 6771 
 6772 18.21. Infrastructure specific to the Linux kernel package
 6773 
 6774 The Linux kernel package can use some specific infrastructures based
 6775 on package hooks for building Linux kernel tools or/and building
 6776 Linux kernel extensions.
 6777 
 6778 18.21.1. linux-kernel-tools
 6779 
 6780 Buildroot offers a helper infrastructure to build some userspace
 6781 tools for the target available within the Linux kernel sources. Since
 6782 their source code is part of the kernel source code, a special
 6783 package, linux-tools, exists and re-uses the sources of the Linux
 6784 kernel that runs on the target.
 6785 
 6786 Let’s look at an example of a Linux tool. For a new Linux tool named
 6787 foo, create a new menu entry in the existing package/linux-tools/
 6788 Config.in. This file will contain the option descriptions related to
 6789 each kernel tool that will be used and displayed in the configuration
 6790 tool. It would basically look like:
 6791 
 6792 01: config BR2_PACKAGE_LINUX_TOOLS_FOO
 6793 02:     bool "foo"
 6794 03:     select BR2_PACKAGE_LINUX_TOOLS
 6795 04:     help
 6796 05:       This is a comment that explains what foo kernel tool is.
 6797 06:
 6798 07:       http://foosoftware.org/foo/
 6799 
 6800 The name of the option starts with the prefix
 6801 BR2_PACKAGE_LINUX_TOOLS_, followed by the uppercase name of the tool
 6802 (like is done for packages).
 6803 
 6804 Note. Unlike other packages, the linux-tools package options appear
 6805 in the linux kernel menu, under the Linux Kernel Tools sub-menu, not
 6806 under the Target packages main menu.
 6807 
 6808 Then for each linux tool, add a new .mk.in file named package/
 6809 linux-tools/linux-tool-foo.mk.in. It would basically look like:
 6810 
 6811 01: ################################################################################
 6812 02: #
 6813 03: # foo
 6814 04: #
 6815 05: ################################################################################
 6816 06:
 6817 07: LINUX_TOOLS += foo
 6818 08:
 6819 09: FOO_DEPENDENCIES = libbbb
 6820 10:
 6821 11: define FOO_BUILD_CMDS
 6822 12:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools foo
 6823 13: endef
 6824 14:
 6825 15: define FOO_INSTALL_STAGING_CMDS
 6826 16:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
 6827 17:             DESTDIR=$(STAGING_DIR) \
 6828 18:             foo_install
 6829 19: endef
 6830 20:
 6831 21: define FOO_INSTALL_TARGET_CMDS
 6832 22:     $(TARGET_MAKE_ENV) $(MAKE) -C $(LINUX_DIR)/tools \
 6833 23:             DESTDIR=$(TARGET_DIR) \
 6834 24:             foo_install
 6835 25: endef
 6836 
 6837 On line 7, we register the Linux tool foo to the list of available
 6838 Linux tools.
 6839 
 6840 On line 9, we specify the list of dependencies this tool relies on.
 6841 These dependencies are added to the Linux package dependencies list
 6842 only when the foo tool is selected.
 6843 
 6844 The rest of the Makefile, lines 11-25 defines what should be done at
 6845 the different steps of the Linux tool build process like for a
 6846 generic package. They will actually be used only when the foo tool is
 6847 selected. The only supported commands are _BUILD_CMDS,
 6848 _INSTALL_STAGING_CMDS and _INSTALL_TARGET_CMDS.
 6849 
 6850 Note. One must not call $(eval $(generic-package)) or any other
 6851 package infrastructure! Linux tools are not packages by themselves,
 6852 they are part of the linux-tools package.
 6853 
 6854 18.21.2. linux-kernel-extensions
 6855 
 6856 Some packages provide new features that require the Linux kernel tree
 6857 to be modified. This can be in the form of patches to be applied on
 6858 the kernel tree, or in the form of new files to be added to the tree.
 6859 The Buildroot’s Linux kernel extensions infrastructure provides a
 6860 simple solution to automatically do this, just after the kernel
 6861 sources are extracted and before the kernel patches are applied.
 6862 Examples of extensions packaged using this mechanism are the
 6863 real-time extensions Xenomai and RTAI, as well as the set of
 6864 out-of-tree LCD screens drivers fbtft.
 6865 
 6866 Let’s look at an example on how to add a new Linux extension foo.
 6867 
 6868 First, create the package foo that provides the extension: this
 6869 package is a standard package; see the previous chapters on how to
 6870 create such a package. This package is in charge of downloading the
 6871 sources archive, checking the hash, defining the licence informations
 6872 and building user space tools if any.
 6873 
 6874 Then create the Linux extension proper: create a new menu entry in
 6875 the existing linux/Config.ext.in. This file contains the option
 6876 descriptions related to each kernel extension that will be used and
 6877 displayed in the configuration tool. It would basically look like:
 6878 
 6879 01: config BR2_LINUX_KERNEL_EXT_FOO
 6880 02:     bool "foo"
 6881 03:     help
 6882 04:       This is a comment that explains what foo kernel extension is.
 6883 05:
 6884 06:       http://foosoftware.org/foo/
 6885 
 6886 Then for each linux extension, add a new .mk file named linux/
 6887 linux-ext-foo.mk. It should basically contain:
 6888 
 6889 01: ################################################################################
 6890 02: #
 6891 03: # foo
 6892 04: #
 6893 05: ################################################################################
 6894 06:
 6895 07: LINUX_EXTENSIONS += foo
 6896 08:
 6897 09: define FOO_PREPARE_KERNEL
 6898 10:     $(FOO_DIR)/prepare-kernel-tree.sh --linux-dir=$(@D)
 6899 11: endef
 6900 
 6901 On line 7, we add the Linux extension foo to the list of available
 6902 Linux extensions.
 6903 
 6904 On line 9-11, we define what should be done by the extension to
 6905 modify the Linux kernel tree; this is specific to the linux extension
 6906 and can use the variables defined by the foo package, like: $
 6907 (FOO_DIR) or $(FOO_VERSION)… as well as all the Linux variables,
 6908 like: $(LINUX_VERSION) or $(LINUX_VERSION_PROBED), $(KERNEL_ARCH)…
 6909 See the definition of those kernel variables.
 6910 
 6911 18.22. Hooks available in the various build steps
 6912 
 6913 The generic infrastructure (and as a result also the derived
 6914 autotools and cmake infrastructures) allow packages to specify hooks.
 6915 These define further actions to perform after existing steps. Most
 6916 hooks aren’t really useful for generic packages, since the .mk file
 6917 already has full control over the actions performed in each step of
 6918 the package construction.
 6919 
 6920 The following hook points are available:
 6921 
 6922   * LIBFOO_PRE_DOWNLOAD_HOOKS
 6923   * LIBFOO_POST_DOWNLOAD_HOOKS
 6924   * LIBFOO_PRE_EXTRACT_HOOKS
 6925   * LIBFOO_POST_EXTRACT_HOOKS
 6926   * LIBFOO_PRE_RSYNC_HOOKS
 6927   * LIBFOO_POST_RSYNC_HOOKS
 6928   * LIBFOO_PRE_PATCH_HOOKS
 6929   * LIBFOO_POST_PATCH_HOOKS
 6930   * LIBFOO_PRE_CONFIGURE_HOOKS
 6931   * LIBFOO_POST_CONFIGURE_HOOKS
 6932   * LIBFOO_PRE_BUILD_HOOKS
 6933   * LIBFOO_POST_BUILD_HOOKS
 6934   * LIBFOO_PRE_INSTALL_HOOKS (for host packages only)
 6935   * LIBFOO_POST_INSTALL_HOOKS (for host packages only)
 6936   * LIBFOO_PRE_INSTALL_STAGING_HOOKS (for target packages only)
 6937   * LIBFOO_POST_INSTALL_STAGING_HOOKS (for target packages only)
 6938   * LIBFOO_PRE_INSTALL_TARGET_HOOKS (for target packages only)
 6939   * LIBFOO_POST_INSTALL_TARGET_HOOKS (for target packages only)
 6940   * LIBFOO_PRE_INSTALL_IMAGES_HOOKS
 6941   * LIBFOO_POST_INSTALL_IMAGES_HOOKS
 6942   * LIBFOO_PRE_LEGAL_INFO_HOOKS
 6943   * LIBFOO_POST_LEGAL_INFO_HOOKS
 6944 
 6945 These variables are lists of variable names containing actions to be
 6946 performed at this hook point. This allows several hooks to be
 6947 registered at a given hook point. Here is an example:
 6948 
 6949 define LIBFOO_POST_PATCH_FIXUP
 6950         action1
 6951         action2
 6952 endef
 6953 
 6954 LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
 6955 
 6956 18.22.1. Using the POST_RSYNC hook
 6957 
 6958 The POST_RSYNC hook is run only for packages that use a local source,
 6959 either through the local site method or the OVERRIDE_SRCDIR
 6960 mechanism. In this case, package sources are copied using rsync from
 6961 the local location into the buildroot build directory. The rsync
 6962 command does not copy all files from the source directory, though.
 6963 Files belonging to a version control system, like the directories
 6964 .git, .hg, etc. are not copied. For most packages this is sufficient,
 6965 but a given package can perform additional actions using the
 6966 POST_RSYNC hook.
 6967 
 6968 In principle, the hook can contain any command you want. One specific
 6969 use case, though, is the intentional copying of the version control
 6970 directory using rsync. The rsync command you use in the hook can,
 6971 among others, use the following variables:
 6972 
 6973   * $(SRCDIR): the path to the overridden source directory
 6974   * $(@D): the path to the build directory
 6975 
 6976 18.22.2. Target-finalize hook
 6977 
 6978 Packages may also register hooks in LIBFOO_TARGET_FINALIZE_HOOKS.
 6979 These hooks are run after all packages are built, but before the
 6980 filesystem images are generated. They are seldom used, and your
 6981 package probably do not need them.
 6982 
 6983 18.23. Gettext integration and interaction with packages
 6984 
 6985 Many packages that support internationalization use the gettext
 6986 library. Dependencies for this library are fairly complicated and
 6987 therefore, deserve some explanation.
 6988 
 6989 The glibc C library integrates a full-blown implementation of gettext
 6990 , supporting translation. Native Language Support is therefore
 6991 built-in in glibc.
 6992 
 6993 On the other hand, the uClibc and musl C libraries only provide a
 6994 stub implementation of the gettext functionality, which allows to
 6995 compile libraries and programs using gettext functions, but without
 6996 providing the translation capabilities of a full-blown gettext
 6997 implementation. With such C libraries, if real Native Language
 6998 Support is necessary, it can be provided by the libintl library of
 6999 the gettext package.
 7000 
 7001 Due to this, and in order to make sure that Native Language Support
 7002 is properly handled, packages in Buildroot that can use NLS support
 7003 should:
 7004 
 7005  1. Ensure NLS support is enabled when BR2_SYSTEM_ENABLE_NLS=y. This
 7006     is done automatically for autotools packages and therefore should
 7007     only be done for packages using other package infrastructures.
 7008  2. Add $(TARGET_NLS_DEPENDENCIES) to the package <pkg>_DEPENDENCIES
 7009     variable. This addition should be done unconditionally: the value
 7010     of this variable is automatically adjusted by the core
 7011     infrastructure to contain the relevant list of packages. If NLS
 7012     support is disabled, this variable is empty. If NLS support is
 7013     enabled, this variable contains host-gettext so that tools needed
 7014     to compile translation files are available on the host. In
 7015     addition, if uClibc or musl are used, this variable also contains
 7016     gettext in order to get the full-blown gettext implementation.
 7017  3. If needed, add $(TARGET_NLS_LIBS) to the linker flags, so that
 7018     the package gets linked with libintl. This is generally not
 7019     needed with autotools packages as they usually detect
 7020     automatically that they should link with libintl. However,
 7021     packages using other build systems, or problematic
 7022     autotools-based packages may need this. $(TARGET_NLS_LIBS) should
 7023     be added unconditionally to the linker flags, as the core
 7024     automatically makes it empty or defined to -lintl depending on
 7025     the configuration.
 7026 
 7027 No changes should be made to the Config.in file to support NLS.
 7028 
 7029 Finally, certain packages need some gettext utilities on the target,
 7030 such as the gettext program itself, which allows to retrieve
 7031 translated strings, from the command line. In such a case, the
 7032 package should:
 7033 
 7034   * use select BR2_PACKAGE_GETTEXT in their Config.in file,
 7035     indicating in a comment above that it’s a runtime dependency
 7036     only.
 7037   * not add any gettext dependency in the DEPENDENCIES variable of
 7038     their .mk file.
 7039 
 7040 18.24. Tips and tricks
 7041 
 7042 18.24.1. Package name, config entry name and makefile variable
 7043 relationship
 7044 
 7045 In Buildroot, there is some relationship between:
 7046 
 7047   * the package name, which is the package directory name (and the
 7048     name of the *.mk file);
 7049   * the config entry name that is declared in the Config.in file;
 7050   * the makefile variable prefix.
 7051 
 7052 It is mandatory to maintain consistency between these elements, using
 7053 the following rules:
 7054 
 7055   * the package directory and the *.mk name are the package name
 7056     itself (e.g.: package/foo-bar_boo/foo-bar_boo.mk);
 7057   * the make target name is the package name itself (e.g.:
 7058     foo-bar_boo);
 7059   * the config entry is the upper case package name with . and -
 7060     characters substituted with _, prefixed with BR2_PACKAGE_ (e.g.:
 7061     BR2_PACKAGE_FOO_BAR_BOO);
 7062   * the *.mk file variable prefix is the upper case package name with
 7063     . and - characters substituted with _ (e.g.:
 7064     FOO_BAR_BOO_VERSION).
 7065 
 7066 18.24.2. How to check the coding style
 7067 
 7068 Buildroot provides a script in utils/check-package that checks new or
 7069 changed files for coding style. It is not a complete language
 7070 validator, but it catches many common mistakes. It is meant to run in
 7071 the actual files you created or modified, before creating the patch
 7072 for submission.
 7073 
 7074 This script can be used for packages, filesystem makefiles, Config.in
 7075 files, etc. It does not check the files defining the package
 7076 infrastructures and some other files containing similar common code.
 7077 
 7078 To use it, run the check-package script, by telling which files you
 7079 created or changed:
 7080 
 7081 $ ./utils/check-package package/new-package/*
 7082 
 7083 If you have the utils directory in your path you can also run:
 7084 
 7085 $ cd package/new-package/
 7086 $ check-package *
 7087 
 7088 The tool can also be used for packages in a br2-external:
 7089 
 7090 $ check-package -b /path/to/br2-ext-tree/package/my-package/*
 7091 
 7092 18.24.3. How to test your package
 7093 
 7094 Once you have added your new package, it is important that you test
 7095 it under various conditions: does it build for all architectures?
 7096 Does it build with the different C libraries? Does it need threads,
 7097 NPTL? And so on…
 7098 
 7099 Buildroot runs autobuilders [http://autobuild.buildroot.org/] which
 7100 continuously test random configurations. However, these only build
 7101 the master branch of the git tree, and your new fancy package is not
 7102 yet there.
 7103 
 7104 Buildroot provides a script in utils/test-pkg that uses the same base
 7105 configurations as used by the autobuilders so you can test your
 7106 package in the same conditions.
 7107 
 7108 First, create a config snippet that contains all the necessary
 7109 options needed to enable your package, but without any architecture
 7110 or toolchain option. For example, let’s create a config snippet that
 7111 just enables libcurl, without any TLS backend:
 7112 
 7113 $ cat libcurl.config
 7114 BR2_PACKAGE_LIBCURL=y
 7115 
 7116 If your package needs more configuration options, you can add them to
 7117 the config snippet. For example, here’s how you would test libcurl
 7118 with openssl as a TLS backend and the curl program:
 7119 
 7120 $ cat libcurl.config
 7121 BR2_PACKAGE_LIBCURL=y
 7122 BR2_PACKAGE_LIBCURL_CURL=y
 7123 BR2_PACKAGE_OPENSSL=y
 7124 
 7125 Then run the test-pkg script, by telling it what config snippet to
 7126 use and what package to test:
 7127 
 7128 $ ./utils/test-pkg -c libcurl.config -p libcurl
 7129 
 7130 By default, test-pkg will build your package against a subset of the
 7131 toolchains used by the autobuilders, which has been selected by the
 7132 Buildroot developers as being the most useful and representative
 7133 subset. If you want to test all toolchains, pass the -a option. Note
 7134 that in any case, internal toolchains are excluded as they take too
 7135 long to build.
 7136 
 7137 The output lists all toolchains that are tested and the corresponding
 7138 result (excerpt, results are fake):
 7139 
 7140 $ ./utils/test-pkg -c libcurl.config -p libcurl
 7141                 armv5-ctng-linux-gnueabi [ 1/11]: OK
 7142               armv7-ctng-linux-gnueabihf [ 2/11]: OK
 7143                         br-aarch64-glibc [ 3/11]: SKIPPED
 7144                            br-arcle-hs38 [ 4/11]: SKIPPED
 7145                             br-arm-basic [ 5/11]: FAILED
 7146                   br-arm-cortex-a9-glibc [ 6/11]: OK
 7147                    br-arm-cortex-a9-musl [ 7/11]: FAILED
 7148                    br-arm-cortex-m4-full [ 8/11]: OK
 7149                              br-arm-full [ 9/11]: OK
 7150                     br-arm-full-nothread [10/11]: FAILED
 7151                       br-arm-full-static [11/11]: OK
 7152 11 builds, 2 skipped, 2 build failed, 1 legal-info failed
 7153 
 7154 The results mean:
 7155 
 7156   * OK: the build was successful.
 7157   * SKIPPED: one or more configuration options listed in the config
 7158     snippet were not present in the final configuration. This is due
 7159     to options having dependencies not satisfied by the toolchain,
 7160     such as for example a package that depends on BR2_USE_MMU with a
 7161     noMMU toolchain. The missing options are reported in
 7162     missing.config in the output build directory (~/br-test-pkg/
 7163     TOOLCHAIN_NAME/ by default).
 7164   * FAILED: the build failed. Inspect the logfile file in the output
 7165     build directory to see what went wrong:
 7166 
 7167       + the actual build failed,
 7168       + the legal-info failed,
 7169       + one of the preliminary steps (downloading the config file,
 7170         applying the configuration, running dirclean for the package)
 7171         failed.
 7172 
 7173 When there are failures, you can just re-run the script with the same
 7174 options (after you fixed your package); the script will attempt to
 7175 re-build the package specified with -p for all toolchains, without
 7176 the need to re-build all the dependencies of that package.
 7177 
 7178 The test-pkg script accepts a few options, for which you can get some
 7179 help by running:
 7180 
 7181 $ ./utils/test-pkg -h
 7182 
 7183 18.24.4. How to add a package from GitHub
 7184 
 7185 Packages on GitHub often don’t have a download area with release
 7186 tarballs. However, it is possible to download tarballs directly from
 7187 the repository on GitHub. As GitHub is known to have changed download
 7188 mechanisms in the past, the github helper function should be used as
 7189 shown below.
 7190 
 7191 # Use a tag or a full commit ID
 7192 FOO_VERSION = 1.0
 7193 FOO_SITE = $(call github,<user>,<package>,v$(FOO_VERSION))
 7194 
 7195 Notes
 7196 
 7197   * The FOO_VERSION can either be a tag or a commit ID.
 7198   * The tarball name generated by github matches the default one from
 7199     Buildroot (e.g.:
 7200     foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz), so it is
 7201     not necessary to specify it in the .mk file.
 7202   * When using a commit ID as version, you should use the full 40 hex
 7203     characters.
 7204   * When the tag contains a prefix such as v in v1.0, then the
 7205     VERSION variable should contain just 1.0, and the v should be
 7206     added directly in the SITE variable, as illustrated above. This
 7207     ensures that the VERSION variable value can be used to match
 7208     against release-monitoring.org [http://www.release-monitoring.org
 7209     /] results.
 7210 
 7211 If the package you wish to add does have a release section on GitHub,
 7212 the maintainer may have uploaded a release tarball, or the release
 7213 may just point to the automatically generated tarball from the git
 7214 tag. If there is a release tarball uploaded by the maintainer, we
 7215 prefer to use that since it may be slightly different (e.g. it
 7216 contains a configure script so we don’t need to do AUTORECONF).
 7217 
 7218 You can see on the release page if it’s an uploaded tarball or a git
 7219 tag:
 7220 
 7221   * If it looks like the image above then it was uploaded by the
 7222     maintainer and you should use that link (in that example: 
 7223     mongrel2-v1.9.2.tar.bz2) to specify FOO_SITE, and not use the 
 7224     github helper.
 7225   * On the other hand, if there’s is only the "Source code" link,
 7226     then it’s an automatically generated tarball and you should use
 7227     the github helper function.
 7228 
 7229 18.24.5. How to add a package from Gitlab
 7230 
 7231 In a similar way to the github macro described in Section 18.24.4,
 7232 “How to add a package from GitHub”, Buildroot also provides the
 7233 gitlab macro to download from Gitlab repositories. It can be used to
 7234 download auto-generated tarballs produced by Gitlab, either for
 7235 specific tags or commits:
 7236 
 7237 # Use a tag or a full commit ID
 7238 FOO_VERSION = 1.0
 7239 FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
 7240 
 7241 By default, it will use a .tar.gz tarball, but Gitlab also provides
 7242 .tar.bz2 tarballs, so by adding a <pkg>_SOURCE variable, this
 7243 .tar.bz2 tarball can be used:
 7244 
 7245 # Use a tag or a full commit ID
 7246 FOO_VERSION = 1.0
 7247 FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
 7248 FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2
 7249 
 7250 If there is a specific tarball uploaded by the upstream developers in
 7251 https://gitlab.com/<project>/releases/, do not use this macro, but
 7252 rather use directly the link to the tarball.
 7253 
 7254 18.25. Conclusion
 7255 
 7256 As you can see, adding a software package to Buildroot is simply a
 7257 matter of writing a Makefile using an existing example and modifying
 7258 it according to the compilation process required by the package.
 7259 
 7260 If you package software that might be useful for other people, don’t
 7261 forget to send a patch to the Buildroot mailing list (see
 7262 Section 22.5, “Submitting patches”)!
 7263 
 7264 Chapter 19. Patching a package
 7265 
 7266 While integrating a new package or updating an existing one, it may
 7267 be necessary to patch the source of the software to get it
 7268 cross-built within Buildroot.
 7269 
 7270 Buildroot offers an infrastructure to automatically handle this
 7271 during the builds. It supports three ways of applying patch sets:
 7272 downloaded patches, patches supplied within buildroot and patches
 7273 located in a user-defined global patch directory.
 7274 
 7275 19.1. Providing patches
 7276 
 7277 19.1.1. Downloaded
 7278 
 7279 If it is necessary to apply a patch that is available for download,
 7280 then add it to the <packagename>_PATCH variable. If an entry contains
 7281 ://, then Buildroot will assume it is a full URL and download the
 7282 patch from this location. Otherwise, Buildroot will assume that the
 7283 patch should be downloaded from <packagename>_SITE. It can be a
 7284 single patch, or a tarball containing a patch series.
 7285 
 7286 Like for all downloads, a hash should be added to the
 7287 <packagename>.hash file.
 7288 
 7289 This method is typically used for packages from Debian.
 7290 
 7291 19.1.2. Within Buildroot
 7292 
 7293 Most patches are provided within Buildroot, in the package directory;
 7294 these typically aim to fix cross-compilation, libc support, or other
 7295 such issues.
 7296 
 7297 These patch files should be named <number>-<description>.patch.
 7298 
 7299 Notes
 7300 
 7301   * The patch files coming with Buildroot should not contain any
 7302     package version reference in their filename.
 7303   * The field <number> in the patch file name refers to the apply
 7304     order, and shall start at 1; It is preferred to pad the number
 7305     with zeros up to 4 digits, like git-format-patch does. E.g.:
 7306     0001-foobar-the-buz.patch
 7307   * Previously, it was mandatory for patches to be prefixed with the
 7308     name of the package, like <package>-<number>-<description>.patch,
 7309     but that is no longer the case. Existing packages will be fixed
 7310     as time passes. Do not prefix patches with the package name.
 7311   * Previously, a series file, as used by quilt, could also be added
 7312     in the package directory. In that case, the series file defines
 7313     the patch application order. This is deprecated, and will be
 7314     removed in the future. Do not use a series file.
 7315 
 7316 19.1.3. Global patch directory
 7317 
 7318 The BR2_GLOBAL_PATCH_DIR configuration file option can be used to
 7319 specify a space separated list of one or more directories containing
 7320 global package patches. See Section 9.8, “Adding project-specific
 7321 patches” for details.
 7322 
 7323 19.2. How patches are applied
 7324 
 7325  1. Run the <packagename>_PRE_PATCH_HOOKS commands if defined;
 7326  2. Cleanup the build directory, removing any existing *.rej files;
 7327  3. If <packagename>_PATCH is defined, then patches from these
 7328     tarballs are applied;
 7329  4. If there are some *.patch files in the package’s Buildroot
 7330     directory or in a package subdirectory named <packageversion>,
 7331     then:
 7332 
 7333       + If a series file exists in the package directory, then
 7334         patches are applied according to the series file;
 7335       + Otherwise, patch files matching *.patch are applied in
 7336         alphabetical order. So, to ensure they are applied in the
 7337         right order, it is highly recommended to name the patch files
 7338         like this: <number>-<description>.patch, where <number>
 7339         refers to the apply order.
 7340  5. If BR2_GLOBAL_PATCH_DIR is defined, the directories will be
 7341     enumerated in the order they are specified. The patches are
 7342     applied as described in the previous step.
 7343  6. Run the <packagename>_POST_PATCH_HOOKS commands if defined.
 7344 
 7345 If something goes wrong in the steps 3 or 4, then the build fails.
 7346 
 7347 19.3. Format and licensing of the package patches
 7348 
 7349 Patches are released under the same license as the software they
 7350 apply to (see Section 13.2, “Complying with the Buildroot license”).
 7351 
 7352 A message explaining what the patch does, and why it is needed,
 7353 should be added in the header commentary of the patch.
 7354 
 7355 You should add a Signed-off-by statement in the header of the each
 7356 patch to help with keeping track of the changes and to certify that
 7357 the patch is released under the same license as the software that is
 7358 modified.
 7359 
 7360 If the software is under version control, it is recommended to use
 7361 the upstream SCM software to generate the patch set.
 7362 
 7363 Otherwise, concatenate the header with the output of the diff -purN
 7364 package-version.orig/ package-version/ command.
 7365 
 7366 If you update an existing patch (e.g. when bumping the package
 7367 version), make sure the existing From header and Signed-off-by tags
 7368 are not removed, but do update the rest of the patch comment when
 7369 appropriate.
 7370 
 7371 At the end, the patch should look like:
 7372 
 7373 configure.ac: add C++ support test
 7374 
 7375 Signed-off-by: John Doe <john.doe@noname.org>
 7376 
 7377 --- configure.ac.orig
 7378 +++ configure.ac
 7379 @@ -40,2 +40,12 @@
 7380 
 7381 AC_PROG_MAKE_SET
 7382 +
 7383 +AC_CACHE_CHECK([whether the C++ compiler works],
 7384 +               [rw_cv_prog_cxx_works],
 7385 +               [AC_LANG_PUSH([C++])
 7386 +                AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
 7387 +                               [rw_cv_prog_cxx_works=yes],
 7388 +                               [rw_cv_prog_cxx_works=no])
 7389 +                AC_LANG_POP([C++])])
 7390 +
 7391 +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
 7392 
 7393 19.4. Integrating patches found on the Web
 7394 
 7395 When integrating a patch of which you are not the author, you have to
 7396 add a few things in the header of the patch itself.
 7397 
 7398 Depending on whether the patch has been obtained from the project
 7399 repository itself, or from somewhere on the web, add one of the
 7400 following tags:
 7401 
 7402 Backported from: <some commit id>
 7403 
 7404 or
 7405 
 7406 Fetch from: <some url>
 7407 
 7408 It is also sensible to add a few words about any changes to the patch
 7409 that may have been necessary.
 7410 
 7411 Chapter 20. Download infrastructure
 7412 
 7413 TODO
 7414 
 7415 Chapter 21. Debugging Buildroot
 7416 
 7417 It is possible to instrument the steps Buildroot does when building
 7418 packages. Define the variable BR2_INSTRUMENTATION_SCRIPTS to contain
 7419 the path of one or more scripts (or other executables), in a
 7420 space-separated list, you want called before and after each step. The
 7421 scripts are called in sequence, with three parameters:
 7422 
 7423   * start or end to denote the start (resp. the end) of a step;
 7424   * the name of the step about to be started, or which just ended;
 7425   * the name of the package.
 7426 
 7427 For example :
 7428 
 7429 make BR2_INSTRUMENTATION_SCRIPTS="/path/to/my/script1 /path/to/my/script2"
 7430 
 7431 The list of steps is:
 7432 
 7433   * extract
 7434   * patch
 7435   * configure
 7436   * build
 7437   * install-host, when a host-package is installed in $(HOST_DIR)
 7438   * install-target, when a target-package is installed in $
 7439     (TARGET_DIR)
 7440   * install-staging, when a target-package is installed in $
 7441     (STAGING_DIR)
 7442   * install-image, when a target-package installs files in $
 7443     (BINARIES_DIR)
 7444 
 7445 The script has access to the following variables:
 7446 
 7447   * BR2_CONFIG: the path to the Buildroot .config file
 7448   * HOST_DIR, STAGING_DIR, TARGET_DIR: see Section 18.5.2,
 7449     “generic-package reference”
 7450   * BUILD_DIR: the directory where packages are extracted and built
 7451   * BINARIES_DIR: the place where all binary files (aka images) are
 7452     stored
 7453   * BASE_DIR: the base output directory
 7454 
 7455 Chapter 22. Contributing to Buildroot
 7456 
 7457 There are many ways in which you can contribute to Buildroot:
 7458 analyzing and fixing bugs, analyzing and fixing package build
 7459 failures detected by the autobuilders, testing and reviewing patches
 7460 sent by other developers, working on the items in our TODO list and
 7461 sending your own improvements to Buildroot or its manual. The
 7462 following sections give a little more detail on each of these items.
 7463 
 7464 If you are interested in contributing to Buildroot, the first thing
 7465 you should do is to subscribe to the Buildroot mailing list. This
 7466 list is the main way of interacting with other Buildroot developers
 7467 and to send contributions to. If you aren’t subscribed yet, then
 7468 refer to Chapter 5, Community resources for the subscription link.
 7469 
 7470 If you are going to touch the code, it is highly recommended to use a
 7471 git repository of Buildroot, rather than starting from an extracted
 7472 source code tarball. Git is the easiest way to develop from and
 7473 directly send your patches to the mailing list. Refer to Chapter 3, 
 7474 Getting Buildroot for more information on obtaining a Buildroot git
 7475 tree.
 7476 
 7477 22.1. Reproducing, analyzing and fixing bugs
 7478 
 7479 A first way of contributing is to have a look at the open bug reports
 7480 in the Buildroot bug tracker [https://bugs.buildroot.org/buglist.cgi?
 7481 product=buildroot]. As we strive to keep the bug count as small as
 7482 possible, all help in reproducing, analyzing and fixing reported bugs
 7483 is more than welcome. Don’t hesitate to add a comment to bug reports
 7484 reporting your findings, even if you don’t yet see the full picture.
 7485 
 7486 22.2. Analyzing and fixing autobuild failures
 7487 
 7488 The Buildroot autobuilders are a set of build machines that
 7489 continuously run Buildroot builds based on random configurations.
 7490 This is done for all architectures supported by Buildroot, with
 7491 various toolchains, and with a random selection of packages. With the
 7492 large commit activity on Buildroot, these autobuilders are a great
 7493 help in detecting problems very early after commit.
 7494 
 7495 All build results are available at http://autobuild.buildroot.org,
 7496 statistics are at http://autobuild.buildroot.org/stats.php. Every
 7497 day, an overview of all failed packages is sent to the mailing list.
 7498 
 7499 Detecting problems is great, but obviously these problems have to be
 7500 fixed as well. Your contribution is very welcome here! There are
 7501 basically two things that can be done:
 7502 
 7503   * Analyzing the problems. The daily summary mails do not contain
 7504     details about the actual failures: in order to see what’s going
 7505     on you have to open the build log and check the last output.
 7506     Having someone doing this for all packages in the mail is very
 7507     useful for other developers, as they can make a quick initial
 7508     analysis based on this output alone.
 7509   * Fixing a problem. When fixing autobuild failures, you should
 7510     follow these steps:
 7511 
 7512      1. Check if you can reproduce the problem by building with the
 7513         same configuration. You can do this manually, or use the
 7514         br-reproduce-build [http://git.buildroot.org/buildroot-test/
 7515         tree/utils/br-reproduce-build] script that will automatically
 7516         clone a Buildroot git repository, checkout the correct
 7517         revision, download and set the right configuration, and start
 7518         the build.
 7519      2. Analyze the problem and create a fix.
 7520      3. Verify that the problem is really fixed by starting from a
 7521         clean Buildroot tree and only applying your fix.
 7522      4. Send the fix to the Buildroot mailing list (see Section 22.5,
 7523         “Submitting patches”). In case you created a patch against
 7524         the package sources, you should also send the patch upstream
 7525         so that the problem will be fixed in a later release, and the
 7526         patch in Buildroot can be removed. In the commit message of a
 7527         patch fixing an autobuild failure, add a reference to the
 7528         build result directory, as follows:
 7529 
 7530 Fixes: http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
 7531 
 7532 22.3. Reviewing and testing patches
 7533 
 7534 With the amount of patches sent to the mailing list each day, the
 7535 maintainer has a very hard job to judge which patches are ready to
 7536 apply and which ones aren’t. Contributors can greatly help here by
 7537 reviewing and testing these patches.
 7538 
 7539 In the review process, do not hesitate to respond to patch
 7540 submissions for remarks, suggestions or anything that will help
 7541 everyone to understand the patches and make them better. Please use
 7542 internet style replies in plain text emails when responding to patch
 7543 submissions.
 7544 
 7545 To indicate approval of a patch, there are three formal tags that
 7546 keep track of this approval. To add your tag to a patch, reply to it
 7547 with the approval tag below the original author’s Signed-off-by line.
 7548 These tags will be picked up automatically by patchwork (see
 7549 Section 22.3.1, “Applying Patches from Patchwork”) and will be part
 7550 of the commit log when the patch is accepted.
 7551 
 7552 Tested-by
 7553     Indicates that the patch has been tested successfully. You are
 7554     encouraged to specify what kind of testing you performed
 7555     (compile-test on architecture X and Y, runtime test on target A,
 7556     …). This additional information helps other testers and the
 7557     maintainer.
 7558 Reviewed-by
 7559     Indicates that you code-reviewed the patch and did your best in
 7560     spotting problems, but you are not sufficiently familiar with the
 7561     area touched to provide an Acked-by tag. This means that there
 7562     may be remaining problems in the patch that would be spotted by
 7563     someone with more experience in that area. Should such problems
 7564     be detected, your Reviewed-by tag remains appropriate and you
 7565     cannot be blamed.
 7566 Acked-by
 7567     Indicates that you code-reviewed the patch and you are familiar
 7568     enough with the area touched to feel that the patch can be
 7569     committed as-is (no additional changes required). In case it
 7570     later turns out that something is wrong with the patch, your
 7571     Acked-by could be considered inappropriate. The difference
 7572     between Acked-by and Reviewed-by is thus mainly that you are
 7573     prepared to take the blame on Acked patches, but not on Reviewed
 7574     ones.
 7575 
 7576 If you reviewed a patch and have comments on it, you should simply
 7577 reply to the patch stating these comments, without providing a
 7578 Reviewed-by or Acked-by tag. These tags should only be provided if
 7579 you judge the patch to be good as it is.
 7580 
 7581 It is important to note that neither Reviewed-by nor Acked-by imply
 7582 that testing has been performed. To indicate that you both reviewed
 7583 and tested the patch, provide two separate tags (Reviewed/Acked-by
 7584 and Tested-by).
 7585 
 7586 Note also that any developer can provide Tested/Reviewed/Acked-by
 7587 tags, without exception, and we encourage everyone to do this.
 7588 Buildroot does not have a defined group of core developers, it just
 7589 so happens that some developers are more active than others. The
 7590 maintainer will value tags according to the track record of their
 7591 submitter. Tags provided by a regular contributor will naturally be
 7592 trusted more than tags provided by a newcomer. As you provide tags
 7593 more regularly, your trustworthiness (in the eyes of the maintainer)
 7594 will go up, but any tag provided is valuable.
 7595 
 7596 Buildroot’s Patchwork website can be used to pull in patches for
 7597 testing purposes. Please see Section 22.3.1, “Applying Patches from
 7598 Patchwork” for more information on using Buildroot’s Patchwork
 7599 website to apply patches.
 7600 
 7601 22.3.1. Applying Patches from Patchwork
 7602 
 7603 The main use of Buildroot’s Patchwork website for a developer is for
 7604 pulling in patches into their local git repository for testing
 7605 purposes.
 7606 
 7607 When browsing patches in the patchwork management interface, an mbox
 7608 link is provided at the top of the page. Copy this link address and
 7609 run the following commands:
 7610 
 7611 $ git checkout -b <test-branch-name>
 7612 $ wget -O - <mbox-url> | git am
 7613 
 7614 Another option for applying patches is to create a bundle. A bundle
 7615 is a set of patches that you can group together using the patchwork
 7616 interface. Once the bundle is created and the bundle is made public,
 7617 you can copy the mbox link for the bundle and apply the bundle using
 7618 the above commands.
 7619 
 7620 22.4. Work on items from the TODO list
 7621 
 7622 If you want to contribute to Buildroot but don’t know where to start,
 7623 and you don’t like any of the above topics, you can always work on
 7624 items from the Buildroot TODO list [http://elinux.org/Buildroot#
 7625 Todo_list]. Don’t hesitate to discuss an item first on the mailing
 7626 list or on IRC. Do edit the wiki to indicate when you start working
 7627 on an item, so we avoid duplicate efforts.
 7628 
 7629 22.5. Submitting patches
 7630 
 7631 Note
 7632 
 7633 Please, do not attach patches to bugs, send them to the mailing list
 7634 instead.
 7635 
 7636 If you made some changes to Buildroot and you would like to
 7637 contribute them to the Buildroot project, proceed as follows.
 7638 
 7639 22.5.1. The formatting of a patch
 7640 
 7641 We expect patches to be formatted in a specific way. This is
 7642 necessary to make it easy to review patches, to be able to apply them
 7643 easily to the git repository, to make it easy to find back in the
 7644 history how and why things have changed, and to make it possible to
 7645 use git bisect to locate the origin of a problem.
 7646 
 7647 First of all, it is essential that the patch has a good commit
 7648 message. The commit message should start with a separate line with a
 7649 brief summary of the change, prefixed by the area touched by the
 7650 patch. A few examples of good commit titles:
 7651 
 7652   * package/linuxptp: bump version to 2.0
 7653   * configs/imx23evk: bump Linux version to 4.19
 7654   * package/pkg-generic: postpone evaluation of dependency conditions
 7655   * boot/uboot: needs host-{flex,bison}
 7656   * support/testing: add python-ubjson tests
 7657 
 7658 The description that follows the prefix should start with a lower
 7659 case letter (i.e "bump", "needs", "postpone", "add" in the above
 7660 examples).
 7661 
 7662 Second, the body of the commit message should describe why this
 7663 change is needed, and if necessary also give details about how it was
 7664 done. When writing the commit message, think of how the reviewers
 7665 will read it, but also think about how you will read it when you look
 7666 at this change again a few years down the line.
 7667 
 7668 Third, the patch itself should do only one change, but do it
 7669 completely. Two unrelated or weakly related changes should usually be
 7670 done in two separate patches. This usually means that a patch affects
 7671 only a single package. If several changes are related, it is often
 7672 still possible to split them up in small patches and apply them in a
 7673 specific order. Small patches make it easier to review, and often
 7674 make it easier to understand afterwards why a change was done.
 7675 However, each patch must be complete. It is not allowed that the
 7676 build is broken when only the first but not the second patch is
 7677 applied. This is necessary to be able to use git bisect afterwards.
 7678 
 7679 Of course, while you’re doing your development, you’re probably going
 7680 back and forth between packages, and certainly not committing things
 7681 immediately in a way that is clean enough for submission. So most
 7682 developers rewrite the history of commits to produce a clean set of
 7683 commits that is appropriate for submission. To do this, you need to
 7684 use interactive rebasing. You can learn about it in the Pro Git book
 7685 [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History].
 7686 Sometimes, it is even easier to discard you history with git reset
 7687 --soft origin/master and select individual changes with git add -i or
 7688 git add -p.
 7689 
 7690 Finally, the patch should be signed off. This is done by adding
 7691 Signed-off-by: Your Real Name <> at the end of the commit message.
 7692 git commit -s does that for you, if configured properly. The
 7693 Signed-off-by tag means that you publish the patch under the
 7694 Buildroot license (i.e. GPL-2.0+, except for package patches, which
 7695 have the upstream license), and that you are allowed to do so. See
 7696 the Developer Certificate of Origin [http://developercertificate.org
 7697 /] for details.
 7698 
 7699 When adding new packages, you should submit every package in a
 7700 separate patch. This patch should have the update to package/
 7701 Config.in, the package Config.in file, the .mk file, the .hash file,
 7702 any init script, and all package patches. If the package has many
 7703 sub-options, these are sometimes better added as separate follow-up
 7704 patches. The summary line should be something like <packagename>: new
 7705 package. The body of the commit message can be empty for simple
 7706 packages, or it can contain the description of the package (like the
 7707 Config.in help text). If anything special has to be done to build the
 7708 package, this should also be explained explicitly in the commit
 7709 message body.
 7710 
 7711 When you bump a package to a new version, you should also submit a
 7712 separate patch for each package. Don’t forget to update the .hash
 7713 file, or add it if it doesn’t exist yet. Also don’t forget to check
 7714 if the _LICENSE and _LICENSE_FILES are still valid. The summary line
 7715 should be something like <packagename>: bump to version <new
 7716 version>. If the new version only contains security updates compared
 7717 to the existing one, the summary should be <packagename>: security
 7718 bump to version <new version> and the commit message body should show
 7719 the CVE numbers that are fixed. If some package patches can be
 7720 removed in the new version, it should be explained explicitly why
 7721 they can be removed, preferably with the upstream commit ID. Also any
 7722 other required changes should be explained explicitly, like configure
 7723 options that no longer exist or are no longer needed.
 7724 
 7725 If you are interested in getting notified of build failures and of
 7726 further changes in the packages you added or modified, please add
 7727 yourself to the DEVELOPERS file. This should be done in the same
 7728 patch creating or modifying the package. See the DEVELOPERS file for
 7729 more information.
 7730 
 7731 Buildroot provides a handy tool to check for common coding style
 7732 mistakes on files you created or modified, called check-package (see
 7733 Section 18.24.2, “How to check the coding style” for more
 7734 information).
 7735 
 7736 22.5.2. Preparing a patch series
 7737 
 7738 Starting from the changes committed in your local git view, rebase
 7739 your development branch on top of the upstream tree before generating
 7740 a patch set. To do so, run:
 7741 
 7742 $ git fetch --all --tags
 7743 $ git rebase origin/master
 7744 
 7745 Now, you are ready to generate then submit your patch set.
 7746 
 7747 To generate it, run:
 7748 
 7749 $ git format-patch -M -n -s -o outgoing origin/master
 7750 
 7751 This will generate patch files in the outgoing subdirectory,
 7752 automatically adding the Signed-off-by line.
 7753 
 7754 Once patch files are generated, you can review/edit the commit
 7755 message before submitting them, using your favorite text editor.
 7756 
 7757 Buildroot provides a handy tool to know to whom your patches should
 7758 be sent, called get-developers (see Chapter 23, DEVELOPERS file and
 7759 get-developers for more information). This tool reads your patches
 7760 and outputs the appropriate git send-email command to use:
 7761 
 7762 $ ./utils/get-developers outgoing/*
 7763 
 7764 Use the output of get-developers to send your patches:
 7765 
 7766 $ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*
 7767 
 7768 Alternatively, get-developers -e can be used directly with the
 7769 --cc-cmd argument to git send-email to automatically CC the affected
 7770 developers:
 7771 
 7772 $ git send-email --to buildroot@buildroot.org \
 7773       --cc-cmd './utils/get-developers -e' origin/master
 7774 
 7775 git can be configured to automatically do this out of the box with:
 7776 
 7777 $ git config sendemail.to buildroot@buildroot.org
 7778 $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"
 7779 
 7780 And then just do:
 7781 
 7782 $ git send-email origin/master
 7783 
 7784 Note that git should be configured to use your mail account. To
 7785 configure git, see man git-send-email or google it.
 7786 
 7787 If you do not use git send-email, make sure posted patches are not
 7788 line-wrapped, otherwise they cannot easily be applied. In such a
 7789 case, fix your e-mail client, or better yet, learn to use git
 7790 send-email.
 7791 
 7792 22.5.3. Cover letter
 7793 
 7794 If you want to present the whole patch set in a separate mail, add
 7795 --cover-letter to the git format-patch command (see man
 7796 git-format-patch for further information). This will generate a
 7797 template for an introduction e-mail to your patch series.
 7798 
 7799 A cover letter may be useful to introduce the changes you propose in
 7800 the following cases:
 7801 
 7802   * large number of commits in the series;
 7803   * deep impact of the changes in the rest of the project;
 7804   * RFC ^[4];
 7805   * whenever you feel it will help presenting your work, your
 7806     choices, the review process, etc.
 7807 
 7808 22.5.4. Patches for maintenance branches
 7809 
 7810 When fixing bugs on a maintenance branch, bugs should be fixed on the
 7811 master branch first. The commit log for such a patch may then contain
 7812 a post-commit note specifying what branches are affected:
 7813 
 7814 package/foo: fix stuff
 7815 
 7816 Signed-off-by: Your Real Name <your@email.address>
 7817 ---
 7818 Backport to: 2020.02.x, 2020.05.x
 7819 (2020.08.x not affected as the version was bumped)
 7820 
 7821 Those changes will then be backported by a maintainer to the affected
 7822 branches.
 7823 
 7824 However, some bugs may apply only to a specific release, for example
 7825 because it is using an older version of a package. In that case,
 7826 patches should be based off the maintenance branch, and the patch
 7827 subject prefix must include the maintenance branch name (for example
 7828 "[PATCH 2020.02.x]"). This can be done with the git format-patch flag
 7829 --subject-prefix:
 7830 
 7831 $ git format-patch --subject-prefix "PATCH 2020.02.x" \
 7832     -M -s -o outgoing origin/2020.02.x
 7833 
 7834 Then send the patches with git send-email, as described above.
 7835 
 7836 22.5.5. Patch revision changelog
 7837 
 7838 When improvements are requested, the new revision of each commit
 7839 should include a changelog of the modifications between each
 7840 submission. Note that when your patch series is introduced by a cover
 7841 letter, an overall changelog may be added to the cover letter in
 7842 addition to the changelog in the individual commits. The best thing
 7843 to rework a patch series is by interactive rebasing: git rebase -i
 7844 origin/master. Consult the git manual for more information.
 7845 
 7846 When added to the individual commits, this changelog is added when
 7847 editing the commit message. Below the Signed-off-by section, add ---
 7848 and your changelog.
 7849 
 7850 Although the changelog will be visible for the reviewers in the mail
 7851 thread, as well as in patchwork [http://patchwork.buildroot.org], git
 7852 will automatically ignores lines below --- when the patch will be
 7853 merged. This is the intended behavior: the changelog is not meant to
 7854 be preserved forever in the git history of the project.
 7855 
 7856 Hereafter the recommended layout:
 7857 
 7858 Patch title: short explanation, max 72 chars
 7859 
 7860 A paragraph that explains the problem, and how it manifests itself. If
 7861 the problem is complex, it is OK to add more paragraphs. All paragraphs
 7862 should be wrapped at 72 characters.
 7863 
 7864 A paragraph that explains the root cause of the problem. Again, more
 7865 than one paragraph is OK.
 7866 
 7867 Finally, one or more paragraphs that explain how the problem is solved.
 7868 Don't hesitate to explain complex solutions in detail.
 7869 
 7870 Signed-off-by: John DOE <john.doe@example.net>
 7871 
 7872 ---
 7873 Changes v2 -> v3:
 7874   - foo bar  (suggested by Jane)
 7875   - bar buz
 7876 
 7877 Changes v1 -> v2:
 7878   - alpha bravo  (suggested by John)
 7879   - charly delta
 7880 
 7881 Any patch revision should include the version number. The version
 7882 number is simply composed of the letter v followed by an integer
 7883 greater or equal to two (i.e. "PATCH v2", "PATCH v3" …).
 7884 
 7885 This can be easily handled with git format-patch by using the option
 7886 --subject-prefix:
 7887 
 7888 $ git format-patch --subject-prefix "PATCH v4" \
 7889     -M -s -o outgoing origin/master
 7890 
 7891 Since git version 1.8.1, you can also use -v <n> (where <n> is the
 7892 version number):
 7893 
 7894 $ git format-patch -v4 -M -s -o outgoing origin/master
 7895 
 7896 When you provide a new version of a patch, please mark the old one as
 7897 superseded in patchwork [http://patchwork.buildroot.org]. You need to
 7898 create an account on patchwork [http://patchwork.buildroot.org] to be
 7899 able to modify the status of your patches. Note that you can only
 7900 change the status of patches you submitted yourself, which means the
 7901 email address you register in patchwork [http://
 7902 patchwork.buildroot.org] should match the one you use for sending
 7903 patches to the mailing list.
 7904 
 7905 You can also add the --in-reply-to <message-id> option when
 7906 submitting a patch to the mailing list. The id of the mail to reply
 7907 to can be found under the "Message Id" tag on patchwork [http://
 7908 patchwork.buildroot.org]. The advantage of in-reply-to is that
 7909 patchwork will automatically mark the previous version of the patch
 7910 as superseded.
 7911 
 7912 22.6. Reporting issues/bugs or getting help
 7913 
 7914 Before reporting any issue, please check in the mailing list archive
 7915 whether someone has already reported and/or fixed a similar problem.
 7916 
 7917 However you choose to report bugs or get help, either by opening a
 7918 bug in the bug tracker or by sending a mail to the mailing list,
 7919 there are a number of details to provide in order to help people
 7920 reproduce and find a solution to the issue.
 7921 
 7922 Try to think as if you were trying to help someone else; in that
 7923 case, what would you need?
 7924 
 7925 Here is a short list of details to provide in such case:
 7926 
 7927   * host machine (OS/release)
 7928   * version of Buildroot
 7929   * target for which the build fails
 7930   * package(s) for which the build fails
 7931   * the command that fails and its output
 7932   * any information you think that may be relevant
 7933 
 7934 Additionally, you should add the .config file (or if you know how, a
 7935 defconfig; see Section 9.3, “Storing the Buildroot configuration”).
 7936 
 7937 If some of these details are too large, do not hesitate to use a
 7938 pastebin service. Note that not all available pastebin services will
 7939 preserve Unix-style line terminators when downloading raw pastes.
 7940 Following pastebin services are known to work correctly: - https://
 7941 gist.github.com/ - http://code.bulix.org/
 7942 
 7943 22.7. Using the run-tests framework
 7944 
 7945 Buildroot includes a run-time testing framework called run-tests
 7946 built upon Python scripting and QEMU runtime execution. There are two
 7947 types of test cases within the framework, one for build time tests
 7948 and another for run-time tests that have a QEMU dependency. The goals
 7949 of the framework are the following:
 7950 
 7951   * build a well defined configuration
 7952   * optionally, verify some properties of the build output
 7953   * if it is a run-time test:
 7954 
 7955       + boot it under QEMU
 7956       + run some test condition to verify that a given feature is
 7957         working
 7958 
 7959 The run-tests tool has a series of options documented in the tool’s
 7960 help -h description. Some common options include setting the download
 7961 folder, the output folder, keeping build output, and for multiple
 7962 test cases, you can set the JLEVEL for each.
 7963 
 7964 Here is an example walk through of running a test case.
 7965 
 7966   * For a first step, let us see what all the test case options are.
 7967     The test cases can be listed by executing support/testing/
 7968     run-tests -l. These tests can all be run individually during test
 7969     development from the console. Both one at a time and selectively
 7970     as a group of a subset of tests.
 7971 
 7972 $ support/testing/run-tests -l
 7973 List of tests
 7974 test_run (tests.utils.test_check_package.TestCheckPackage)
 7975 Test the various ways the script can be called in a simple top to ... ok
 7976 test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootMusl) ... ok
 7977 test_run (tests.toolchain.test_external.TestExternalToolchainBuildrootuClibc) ... ok
 7978 test_run (tests.toolchain.test_external.TestExternalToolchainCCache) ... ok
 7979 test_run (tests.toolchain.test_external.TestExternalToolchainCtngMusl) ... ok
 7980 test_run (tests.toolchain.test_external.TestExternalToolchainLinaroArm) ... ok
 7981 test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv4) ... ok
 7982 test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv5) ... ok
 7983 test_run (tests.toolchain.test_external.TestExternalToolchainSourceryArmv7) ... ok
 7984 [snip]
 7985 test_run (tests.init.test_systemd.TestInitSystemSystemdRoFull) ... ok
 7986 test_run (tests.init.test_systemd.TestInitSystemSystemdRoIfupdown) ... ok
 7987 test_run (tests.init.test_systemd.TestInitSystemSystemdRoNetworkd) ... ok
 7988 test_run (tests.init.test_systemd.TestInitSystemSystemdRwFull) ... ok
 7989 test_run (tests.init.test_systemd.TestInitSystemSystemdRwIfupdown) ... ok
 7990 test_run (tests.init.test_systemd.TestInitSystemSystemdRwNetworkd) ... ok
 7991 test_run (tests.init.test_busybox.TestInitSystemBusyboxRo) ... ok
 7992 test_run (tests.init.test_busybox.TestInitSystemBusyboxRoNet) ... ok
 7993 test_run (tests.init.test_busybox.TestInitSystemBusyboxRw) ... ok
 7994 test_run (tests.init.test_busybox.TestInitSystemBusyboxRwNet) ... ok
 7995 
 7996 Ran 157 tests in 0.021s
 7997 
 7998 OK
 7999 
 8000 Those runtime tests are regularly executed by Buildroot Gitlab CI
 8001 infrastructure, see .gitlab.yml and https://gitlab.com/buildroot.org/
 8002 buildroot/-/jobs.
 8003 
 8004 22.7.1. Creating a test case
 8005 
 8006 The best way to get familiar with how to create a test case is to
 8007 look at a few of the basic file system support/testing/tests/fs/ and
 8008 init support/testing/tests/init/ test scripts. Those tests give good
 8009 examples of a basic build and build with run type of tests. There are
 8010 other more advanced cases that use things like nested br2-external
 8011 folders to provide skeletons and additional packages.
 8012 
 8013 The test cases by default use a br-arm-full-* uClibc-ng toolchain and
 8014 the prebuild kernel for a armv5/7 cpu. It is recommended to use the
 8015 default defconfig test configuration except when Glibc/musl or a
 8016 newer kernel are necessary. By using the default it saves build time
 8017 and the test would automatically inherit a kernel/std library upgrade
 8018 when the default is updated.
 8019 
 8020 The basic test case definition involves
 8021 
 8022   * Creation of a new test file
 8023   * Defining a unique test class
 8024   * Determining if the default defconfig plus test options can be
 8025     used
 8026   * Implementing a def test_run(self): function to optionally startup
 8027     the emulator and provide test case conditions.
 8028 
 8029 After creating the test script, add yourself to the DEVELOPERS file
 8030 to be the maintainer of that test case.
 8031 
 8032 22.7.2. Debugging a test case
 8033 
 8034 Within the Buildroot repository, the testing framework is organized
 8035 at the top level in support/testing/ by folders of conf, infra and
 8036 tests. All the test cases live under the test folder and are
 8037 organized in various folders representing the catagory of test.
 8038 
 8039 Lets walk through an example.
 8040 
 8041   * Using the Busybox Init system test case with a read/write rootfs
 8042     tests.init.test_busybox.TestInitSystemBusyboxRw
 8043   * A minimal set of command line arguments when debugging a test
 8044     case would include -d which points to your dl folder, -o to an
 8045     output folder, and -k to keep any output on both pass/fail. With
 8046     those options, the test will retain logging and build artifacts
 8047     providing status of the build and execution of the test case.
 8048 
 8049 $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusyboxRw
 8050 15:03:26 TestInitSystemBusyboxRw                  Starting
 8051 15:03:28 TestInitSystemBusyboxRw                  Building
 8052 15:08:18 TestInitSystemBusyboxRw                  Building done
 8053 15:08:27 TestInitSystemBusyboxRw                  Cleaning up
 8054 .
 8055 Ran 1 test in 301.140s
 8056 
 8057 OK
 8058 
 8059   * For the case of a successful build, the output_folder would
 8060     contain a <test name> folder with the Buildroot build, build log
 8061     and run-time log. If the build failed, the console output would
 8062     show the stage at which it failed (setup / build / run).
 8063     Depending on the failure stage, the build/run logs and/or
 8064     Buildroot build artifacts can be inspected and instrumented. If
 8065     the QEMU instance needs to be launched for additional testing,
 8066     the first few lines of the run-time log capture it and it would
 8067     allow some incremental testing without re-running support/testing
 8068     /run-tests.
 8069   * You can also make modifications to the current sources inside the
 8070     output_folder (e.g. for debug purposes) and rerun the standard
 8071     Buildroot make targets (in order to regenerate the complete image
 8072     with the new modifications) and then rerun the test. Modifying
 8073     the sources directly can speed up debugging compared to adding
 8074     patch files, wiping the output directoy, and starting the test
 8075     again.
 8076 
 8077 $ ls output_folder/
 8078 TestInitSystemBusyboxRw/
 8079 TestInitSystemBusyboxRw-build.log
 8080 TestInitSystemBusyboxRw-run.log
 8081 
 8082   * The source file used to implement this example test is found
 8083     under support/testing/tests/init/test_busybox.py. This file
 8084     outlines the minimal defconfig that creates the build, QEMU
 8085     configuration to launch the built images and the test case
 8086     assertions.
 8087 
 8088 To test an existing or new test case within Gitlab CI, there is a
 8089 method of invoking a specific test by creating a Buildroot fork in
 8090 Gitlab under your account. This can be handy when adding/changing a
 8091 run-time test or fixing a bug on a use case tested by a run-time test
 8092 case.
 8093 
 8094 In the examples below, the <name> component of the branch name is a
 8095 unique string you choose to identify this specific job being created.
 8096 
 8097   * to trigger all run-test test case jobs:
 8098 
 8099  $ git push gitlab HEAD:<name>-runtime-tests
 8100 
 8101   * to trigger one test case job, a specific branch naming string is
 8102     used that includes the full test case name.
 8103 
 8104  $ git push gitlab HEAD:<name>-<test case name>
 8105 
 8106 
 8107 ---------------------------------------------------------------------
 8108 
 8109 ^[4] RFC: (Request for comments) change proposal
 8110 
 8111 Chapter 23. DEVELOPERS file and get-developers
 8112 
 8113 The main Buildroot directory contains a file named DEVELOPERS that
 8114 lists the developers involved with various areas of Buildroot. Thanks
 8115 to this file, the get-developers tool allows to:
 8116 
 8117   * Calculate the list of developers to whom patches should be sent,
 8118     by parsing the patches and matching the modified files with the
 8119     relevant developers. See Section 22.5, “Submitting patches” for
 8120     details.
 8121   * Find which developers are taking care of a given architecture or
 8122     package, so that they can be notified when a build failure occurs
 8123     on this architecture or package. This is done in interaction with
 8124     Buildroot’s autobuild infrastructure.
 8125 
 8126 We ask developers adding new packages, new boards, or generally new
 8127 functionality in Buildroot, to register themselves in the DEVELOPERS
 8128 file. As an example, we expect a developer contributing a new package
 8129 to include in his patch the appropriate modification to the
 8130 DEVELOPERS file.
 8131 
 8132 The DEVELOPERS file format is documented in detail inside the file
 8133 itself.
 8134 
 8135 The get-developers tool, located in utils/ allows to use the
 8136 DEVELOPERS file for various tasks:
 8137 
 8138   * When passing one or several patches as command line argument,
 8139     get-developers will return the appropriate git send-email
 8140     command. If the -e option is passed, only the email addresses are
 8141     printed in a format suitable for git send-email --cc-cmd.
 8142   * When using the -a <arch> command line option, get-developers will
 8143     return the list of developers in charge of the given
 8144     architecture.
 8145   * When using the -p <package> command line option, get-developers
 8146     will return the list of developers in charge of the given
 8147     package.
 8148   * When using the -c command line option, get-developers will look
 8149     at all files under version control in the Buildroot repository,
 8150     and list the ones that are not handled by any developer. The
 8151     purpose of this option is to help completing the DEVELOPERS file.
 8152   * When using without any arguments, it validates the integrity of
 8153     the DEVELOPERS file and will note WARNINGS for items that don’t
 8154     match.
 8155 
 8156 Chapter 24. Release Engineering
 8157 
 8158 24.1. Releases
 8159 
 8160 The Buildroot project makes quarterly releases with monthly bugfix
 8161 releases. The first release of each year is a long term support
 8162 release, LTS.
 8163 
 8164   * Quarterly releases: 2020.02, 2020.05, 2020.08, and 2020.11
 8165   * Bugfix releases: 2020.02.1, 2020.02.2, …
 8166   * LTS releases: 2020.02, 2021.02, …
 8167 
 8168 Releases are supported until the first bugfix release of the next
 8169 release, e.g., 2020.05.x is EOL when 2020.08.1 is released.
 8170 
 8171 LTS releases are supported until the first bugfix release of the next
 8172 LTS, e.g., 2020.02.x is supported until 2021.02.1 is released.
 8173 
 8174 24.2. Development
 8175 
 8176 Each release cycle consist of two months of development on the master
 8177 branch and one month stabilization before the release is made. During
 8178 this phase no new features are added to master, only bugfixes.
 8179 
 8180 The stabilization phase starts with tagging -rc1, and every week
 8181 until the release, another release candidate is tagged.
 8182 
 8183 To handle new features and version bumps during the stabilization
 8184 phase, a next branch may be created for these features. Once the
 8185 current release has been made, the next branch is merged into master
 8186 and the development cycle for the next release continues there.
 8187 
 8188 Part IV. Appendix
 8189 
 8190 Table of Contents
 8191 
 8192 25. Makedev syntax documentation
 8193 26. Makeusers syntax documentation
 8194 27. Migrating from older Buildroot versions
 8195 
 8196     27.1. Migrating to 2016.11
 8197     27.2. Migrating to 2017.08
 8198 
 8199 Chapter 25. Makedev syntax documentation
 8200 
 8201 The makedev syntax is used in several places in Buildroot to define
 8202 changes to be made for permissions, or which device files to create
 8203 and how to create them, in order to avoid calls to mknod.
 8204 
 8205 This syntax is derived from the makedev utility, and more complete
 8206 documentation can be found in the package/makedevs/README file.
 8207 
 8208 It takes the form of a space separated list of fields, one file per
 8209 line; the fields are:
 8210 
 8211 +--------------------------------------------------+
 8212 |name|type|mode|uid|gid|major|minor|start|inc|count|
 8213 +--------------------------------------------------+
 8214 
 8215 There are a few non-trivial blocks:
 8216 
 8217   * name is the path to the file you want to create/modify
 8218   * type is the type of the file, being one of:
 8219 
 8220       + f: a regular file
 8221       + d: a directory
 8222       + r: a directory recursively
 8223       + c: a character device file
 8224       + b: a block device file
 8225       + p: a named pipe
 8226   * mode are the usual permissions settings (only numerical values
 8227     are allowed)
 8228   * uid and gid are the UID and GID to set on this file; can be
 8229     either numerical values or actual names
 8230   * major and minor are here for device files, set to - for other
 8231     files
 8232   * start, inc and count are for when you want to create a batch of
 8233     files, and can be reduced to a loop, beginning at start,
 8234     incrementing its counter by inc until it reaches count
 8235 
 8236 Let’s say you want to change the permissions of a given file; using
 8237 this syntax, you will need to write:
 8238 
 8239 /usr/bin/foo f 755 0 0 - - - - -
 8240 /usr/bin/bar f 755 root root - - - - -
 8241 /data/buz f 644 buz-user buz-group - - - - -
 8242 
 8243 Alternatively, if you want to change owner/permission of a directory
 8244 recursively, you can write (to set UID to foo, GID to bar and access
 8245 rights to rwxr-x--- for the directory /usr/share/myapp and all files
 8246 and directories below it):
 8247 
 8248 /usr/share/myapp r 750 foo bar - - - - -
 8249 
 8250 On the other hand, if you want to create the device file /dev/hda and
 8251 the corresponding 15 files for the partitions, you will need for /dev
 8252 /hda:
 8253 
 8254 /dev/hda b 640 root root 3 0 0 0 -
 8255 
 8256 and then for device files corresponding to the partitions of /dev/
 8257 hda, /dev/hdaX, X ranging from 1 to 15:
 8258 
 8259 /dev/hda b 640 root root 3 1 1 1 15
 8260 
 8261 Extended attributes are supported if
 8262 BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES is enabled. This
 8263 is done by adding a line starting with |xattr after the line
 8264 describing the file. Right now, only capability is supported as
 8265 extended attribute.
 8266 
 8267 +------------------+
 8268 ||xattr|capability |
 8269 +------------------+
 8270 
 8271   * |xattr is a "flag" that indicate an extended attribute
 8272   * capability is a capability to add to the previous file
 8273 
 8274 If you want to add the capability cap_sys_admin to the binary foo,
 8275 you will write :
 8276 
 8277 /usr/bin/foo f 755 root root - - - - -
 8278 |xattr cap_sys_admin+eip
 8279 
 8280 You can add several capabilities to a file by using several |xattr
 8281 lines. If you want to add the capability cap_sys_admin and
 8282 cap_net_admin to the binary foo, you will write :
 8283 
 8284 /usr/bin/foo f 755 root root - - - - -
 8285 |xattr cap_sys_admin+eip
 8286 |xattr cap_net_admin+eip
 8287 
 8288 Chapter 26. Makeusers syntax documentation
 8289 
 8290 The syntax to create users is inspired by the makedev syntax, above,
 8291 but is specific to Buildroot.
 8292 
 8293 The syntax for adding a user is a space-separated list of fields, one
 8294 user per line; the fields are:
 8295 
 8296 +---------------------------------------------------------+
 8297 |username|uid|group|gid|password|home|shell|groups|comment|
 8298 +---------------------------------------------------------+
 8299 
 8300 Where:
 8301 
 8302   * username is the desired user name (aka login name) for the user.
 8303     It can not be root, and must be unique. If set to -, then just a
 8304     group will be created.
 8305   * uid is the desired UID for the user. It must be unique, and not
 8306     0. If set to -1, then a unique UID will be computed by Buildroot
 8307     in the range [1000…1999]
 8308   * group is the desired name for the user’s main group. It can not
 8309     be root. If the group does not exist, it will be created.
 8310   * gid is the desired GID for the user’s main group. It must be
 8311     unique, and not 0. If set to -1, and the group does not already
 8312     exist, then a unique GID will be computed by Buildroot in the
 8313     range [1000..1999]
 8314   * password is the crypt(3)-encoded password. If prefixed with !,
 8315     then login is disabled. If prefixed with =, then it is
 8316     interpreted as clear-text, and will be crypt-encoded (using MD5).
 8317     If prefixed with !=, then the password will be crypt-encoded
 8318     (using MD5) and login will be disabled. If set to *, then login
 8319     is not allowed. If set to -, then no password value will be set.
 8320   * home is the desired home directory for the user. If set to -, no
 8321     home directory will be created, and the user’s home will be /.
 8322     Explicitly setting home to / is not allowed.
 8323   * shell is the desired shell for the user. If set to -, then /bin/
 8324     false is set as the user’s shell.
 8325   * groups is the comma-separated list of additional groups the user
 8326     should be part of. If set to -, then the user will be a member of
 8327     no additional group. Missing groups will be created with an
 8328     arbitrary gid.
 8329   * comment (aka GECOS [https://en.wikipedia.org/wiki/Gecos_field]
 8330     field) is an almost-free-form text.
 8331 
 8332 There are a few restrictions on the content of each field:
 8333 
 8334   * except for comment, all fields are mandatory.
 8335   * except for comment, fields may not contain spaces.
 8336   * no field may contain a colon (:).
 8337 
 8338 If home is not -, then the home directory, and all files below, will
 8339 belong to the user and its main group.
 8340 
 8341 Examples:
 8342 
 8343 foo -1 bar -1 !=blabla /home/foo /bin/sh alpha,bravo Foo user
 8344 
 8345 This will create this user:
 8346 
 8347   * username (aka login name) is: foo
 8348   * uid is computed by Buildroot
 8349   * main group is: bar
 8350   * main group gid is computed by Buildroot
 8351   * clear-text password is: blabla, will be crypt(3)-encoded, and
 8352     login is disabled.
 8353   * home is: /home/foo
 8354   * shell is: /bin/sh
 8355   * foo is also a member of groups: alpha and bravo
 8356   * comment is: Foo user
 8357 
 8358 test 8000 wheel -1 = - /bin/sh - Test user
 8359 
 8360 This will create this user:
 8361 
 8362   * username (aka login name) is: test
 8363   * uid is : 8000
 8364   * main group is: wheel
 8365   * main group gid is computed by Buildroot, and will use the value
 8366     defined in the rootfs skeleton
 8367   * password is empty (aka no password).
 8368   * home is / but will not belong to test
 8369   * shell is: /bin/sh
 8370   * test is not a member of any additional groups
 8371   * comment is: Test user
 8372 
 8373 Chapter 27. Migrating from older Buildroot versions
 8374 
 8375 Some versions have introduced backward incompatibilities. This
 8376 section explains those incompatibilities, and for each explains what
 8377 to do to complete the migration.
 8378 
 8379 27.1. Migrating to 2016.11
 8380 
 8381 Before Buildroot 2016.11, it was possible to use only one
 8382 br2-external tree at once. With Buildroot 2016.11 came the
 8383 possibility to use more than one simultaneously (for details, see
 8384 Section 9.2, “Keeping customizations outside of Buildroot”).
 8385 
 8386 This however means that older br2-external trees are not usable
 8387 as-is. A minor change has to be made: adding a name to your
 8388 br2-external tree.
 8389 
 8390 This can be done very easily in just a few steps:
 8391 
 8392   * First, create a new file named external.desc, at the root of your
 8393     br2-external tree, with a single line defining the name of your
 8394     br2-external tree:
 8395 
 8396     $ echo 'name: NAME_OF_YOUR_TREE' >external.desc
 8397 
 8398     Note. Be careful when choosing a name: It has to be unique and be
 8399     made with only ASCII characters from the set [A-Za-z0-9_].
 8400 
 8401   * Then, change every occurence of BR2_EXTERNAL in your br2-external
 8402     tree with the new variable:
 8403 
 8404     $ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'
 8405 
 8406 Now, your br2-external tree can be used with Buildroot 2016.11
 8407 onward.
 8408 
 8409 Note: This change makes your br2-external tree incompatible with
 8410 Buildroot before 2016.11.
 8411 
 8412 27.2. Migrating to 2017.08
 8413 
 8414 Before Buildroot 2017.08, host packages were installed in $(HOST_DIR)
 8415 /usr (with e.g. the autotools' --prefix=$(HOST_DIR)/usr). With
 8416 Buildroot 2017.08, they are now installed directly in $(HOST_DIR).
 8417 
 8418 Whenever a package installs an executable that is linked with a
 8419 library in $(HOST_DIR)/lib, it must have an RPATH pointing to that
 8420 directory.
 8421 
 8422 An RPATH pointing to $(HOST_DIR)/usr/lib is no longer accepted.
 8423