"Fossies" - the Fresh Open Source Software Archive

Member "buildroot-2021.05/docs/manual/manual.html" (6 Jun 2021, 540081 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) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Buildroot user manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="idm1"></a>The Buildroot user manual</h1></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="#idm4"></a></span></dt><dt><span class="part"><a href="#_getting_started">I. Getting started</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_about_buildroot">1. About Buildroot</a></span></dt><dt><span class="chapter"><a href="#requirement">2. System requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#requirement-mandatory">2.1. Mandatory packages</a></span></dt><dt><span class="section"><a href="#requirement-optional">2.2. Optional packages</a></span></dt></dl></dd><dt><span class="chapter"><a href="#getting-buildroot">3. Getting Buildroot</a></span></dt><dt><span class="chapter"><a href="#_buildroot_quick_start">4. Buildroot quick start</a></span></dt><dt><span class="chapter"><a href="#community-resources">5. Community resources</a></span></dt></dl></dd><dt><span class="part"><a href="#_user_guide">II. User guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="#configure">6. Buildroot configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#_cross_compilation_toolchain">6.1. Cross-compilation toolchain</a></span></dt><dt><span class="section"><a href="#_dev_management">6.2. /dev management</a></span></dt><dt><span class="section"><a href="#_init_system">6.3. init system</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_configuration_of_other_components">7. Configuration of other components</a></span></dt><dt><span class="chapter"><a href="#_general_buildroot_usage">8. General Buildroot usage</a></span></dt><dd><dl><dt><span class="section"><a href="#make-tips">8.1. <span class="emphasis"><em>make</em></span> tips</a></span></dt><dt><span class="section"><a href="#full-rebuild">8.2. Understanding when a full rebuild is necessary</a></span></dt><dt><span class="section"><a href="#rebuild-pkg">8.3. Understanding how to rebuild packages</a></span></dt><dt><span class="section"><a href="#_offline_builds">8.4. Offline builds</a></span></dt><dt><span class="section"><a href="#_building_out_of_tree">8.5. Building out-of-tree</a></span></dt><dt><span class="section"><a href="#env-vars">8.6. Environment variables</a></span></dt><dt><span class="section"><a href="#_dealing_efficiently_with_filesystem_images">8.7. Dealing efficiently with filesystem images</a></span></dt><dt><span class="section"><a href="#_details_about_packages">8.8. Details about packages</a></span></dt><dt><span class="section"><a href="#_graphing_the_dependencies_between_packages">8.9. Graphing the dependencies between packages</a></span></dt><dt><span class="section"><a href="#_graphing_the_build_duration">8.10. Graphing the build duration</a></span></dt><dt><span class="section"><a href="#graph-size">8.11. Graphing the filesystem size contribution of packages</a></span></dt><dt><span class="section"><a href="#top-level-parallel-build">8.12. Top-level parallel build</a></span></dt><dt><span class="section"><a href="#_integration_with_eclipse">8.13. Integration with Eclipse</a></span></dt><dt><span class="section"><a href="#_advanced_usage">8.14. Advanced usage</a></span></dt></dl></dd><dt><span class="chapter"><a href="#customize">9. Project-specific customization</a></span></dt><dd><dl><dt><span class="section"><a href="#customize-dir-structure">9.1. Recommended directory structure</a></span></dt><dt><span class="section"><a href="#outside-br-custom">9.2. Keeping customizations outside of Buildroot</a></span></dt><dt><span class="section"><a href="#customize-store-buildroot-config">9.3. Storing the Buildroot configuration</a></span></dt><dt><span class="section"><a href="#customize-store-package-config">9.4. Storing the configuration of other components</a></span></dt><dt><span class="section"><a href="#rootfs-custom">9.5. Customizing the generated target filesystem</a></span></dt><dt><span class="section"><a href="#customize-users">9.6. Adding custom user accounts</a></span></dt><dt><span class="section"><a href="#_customization_emphasis_after_emphasis_the_images_have_been_created">9.7. Customization <span class="emphasis"><em>after</em></span> the images have been created</a></span></dt><dt><span class="section"><a href="#customize-patches">9.8. Adding project-specific patches</a></span></dt><dt><span class="section"><a href="#customize-packages">9.9. Adding project-specific packages</a></span></dt><dt><span class="section"><a href="#_quick_guide_to_storing_your_project_specific_customizations">9.10. Quick guide to storing your project-specific customizations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#selinux">10. Using SELinux in Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-selinux">10.1. Enabling SELinux support</a></span></dt><dt><span class="section"><a href="#selinux-policy-tweaking">10.2. SELinux policy tweaking</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_frequently_asked_questions_amp_troubleshooting">11. Frequently Asked Questions &amp; Troubleshooting</a></span></dt><dd><dl><dt><span class="section"><a href="#faq-boot-hang-after-starting">11.1. The boot hangs after <span class="emphasis"><em>Starting network…</em></span></a></span></dt><dt><span class="section"><a href="#faq-no-compiler-on-target">11.2. Why is there no compiler on the target?</a></span></dt><dt><span class="section"><a href="#faq-no-dev-files-on-target">11.3. Why are there no development files on the target?</a></span></dt><dt><span class="section"><a href="#faq-no-doc-on-target">11.4. Why is there no documentation on the target?</a></span></dt><dt><span class="section"><a href="#faq-why-not-visible-package">11.5. Why are some packages not visible in the Buildroot config menu?</a></span></dt><dt><span class="section"><a href="#faq-why-not-use-target-as-chroot">11.6. Why not use the target directory as a chroot directory?</a></span></dt><dt><span class="section"><a href="#faq-no-binary-packages">11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?</a></span></dt><dt><span class="section"><a href="#faq-speeding-up-build">11.8. How to speed-up the build process?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_known_issues">12. Known issues</a></span></dt><dt><span class="chapter"><a href="#legal-info">13. Legal notice and licensing</a></span></dt><dd><dl><dt><span class="section"><a href="#_complying_with_open_source_licenses">13.1. Complying with open source licenses</a></span></dt><dt><span class="section"><a href="#legal-info-buildroot">13.2. Complying with the Buildroot license</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_beyond_buildroot">14. Beyond Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_boot_the_generated_images">14.1. Boot the generated images</a></span></dt><dt><span class="section"><a href="#_chroot">14.2. Chroot</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_developer_guide">III. Developer guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_how_buildroot_works">15. How Buildroot works</a></span></dt><dt><span class="chapter"><a href="#_coding_style">16. Coding style</a></span></dt><dd><dl><dt><span class="section"><a href="#writing-rules-config-in">16.1. <code class="literal">Config.in</code> file</a></span></dt><dt><span class="section"><a href="#writing-rules-mk">16.2. The <code class="literal">.mk</code> file</a></span></dt><dt><span class="section"><a href="#_the_documentation">16.3. The documentation</a></span></dt><dt><span class="section"><a href="#_support_scripts">16.4. Support scripts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#adding-board-support">17. Adding support for a particular board</a></span></dt><dt><span class="chapter"><a href="#adding-packages">18. Adding new packages to Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_package_directory">18.1. Package directory</a></span></dt><dt><span class="section"><a href="#_config_files">18.2. Config files</a></span></dt><dt><span class="section"><a href="#_the_literal_mk_literal_file">18.3. The <code class="literal">.mk</code> file</a></span></dt><dt><span class="section"><a href="#adding-packages-hash">18.4. The <code class="literal">.hash</code> file</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_with_specific_build_systems">18.5. Infrastructure for packages with specific build systems</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_autotools_based_packages">18.6. Infrastructure for autotools-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_cmake_based_packages">18.7. Infrastructure for CMake-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_python_packages">18.8. Infrastructure for Python packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_luarocks_based_packages">18.9. Infrastructure for LuaRocks-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_perl_cpan_packages">18.10. Infrastructure for Perl/CPAN packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_virtual_packages">18.11. Infrastructure for virtual packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_using_kconfig_for_configuration_files">18.12. Infrastructure for packages using kconfig for configuration files</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_rebar_based_packages">18.13. Infrastructure for rebar-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_waf_based_packages">18.14. Infrastructure for Waf-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_meson_based_packages">18.15. Infrastructure for Meson-based packages</a></span></dt><dt><span class="section"><a href="#_integration_of_cargo_based_packages">18.16. Integration of Cargo-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_go_packages">18.17. Infrastructure for Go packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_qmake_based_packages">18.18. Infrastructure for QMake-based packages</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_packages_building_kernel_modules">18.19. Infrastructure for packages building kernel modules</a></span></dt><dt><span class="section"><a href="#_infrastructure_for_asciidoc_documents">18.20. Infrastructure for asciidoc documents</a></span></dt><dt><span class="section"><a href="#linux-kernel-specific-infra">18.21. Infrastructure specific to the Linux kernel package</a></span></dt><dt><span class="section"><a href="#hooks">18.22. Hooks available in the various build steps</a></span></dt><dt><span class="section"><a href="#_gettext_integration_and_interaction_with_packages">18.23. Gettext integration and interaction with packages</a></span></dt><dt><span class="section"><a href="#_tips_and_tricks">18.24. Tips and tricks</a></span></dt><dt><span class="section"><a href="#_conclusion">18.25. Conclusion</a></span></dt></dl></dd><dt><span class="chapter"><a href="#patch-policy">19. Patching a package</a></span></dt><dd><dl><dt><span class="section"><a href="#_providing_patches">19.1. Providing patches</a></span></dt><dt><span class="section"><a href="#patch-apply-order">19.2. How patches are applied</a></span></dt><dt><span class="section"><a href="#_format_and_licensing_of_the_package_patches">19.3. Format and licensing of the package patches</a></span></dt><dt><span class="section"><a href="#_integrating_patches_found_on_the_web">19.4. Integrating patches found on the Web</a></span></dt></dl></dd><dt><span class="chapter"><a href="#download-infra">20. Download infrastructure</a></span></dt><dt><span class="chapter"><a href="#debugging-buildroot">21. Debugging Buildroot</a></span></dt><dt><span class="chapter"><a href="#_contributing_to_buildroot">22. Contributing to Buildroot</a></span></dt><dd><dl><dt><span class="section"><a href="#_reproducing_analyzing_and_fixing_bugs">22.1. Reproducing, analyzing and fixing bugs</a></span></dt><dt><span class="section"><a href="#_analyzing_and_fixing_autobuild_failures">22.2. Analyzing and fixing autobuild failures</a></span></dt><dt><span class="section"><a href="#_reviewing_and_testing_patches">22.3. Reviewing and testing patches</a></span></dt><dt><span class="section"><a href="#_work_on_items_from_the_todo_list">22.4. Work on items from the TODO list</a></span></dt><dt><span class="section"><a href="#submitting-patches">22.5. Submitting patches</a></span></dt><dt><span class="section"><a href="#reporting-bugs">22.6. Reporting issues/bugs or getting help</a></span></dt><dt><span class="section"><a href="#_using_the_run_tests_framework">22.7. Using the run-tests framework</a></span></dt></dl></dd><dt><span class="chapter"><a href="#DEVELOPERS">23. DEVELOPERS file and get-developers</a></span></dt><dt><span class="chapter"><a href="#RELENG">24. Release Engineering</a></span></dt><dd><dl><dt><span class="section"><a href="#_releases">24.1. Releases</a></span></dt><dt><span class="section"><a href="#_development">24.2. Development</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_appendix">IV. Appendix</a></span></dt><dd><dl><dt><span class="chapter"><a href="#makedev-syntax">25. Makedev syntax documentation</a></span></dt><dt><span class="chapter"><a href="#makeuser-syntax">26. Makeusers syntax documentation</a></span></dt><dt><span class="chapter"><a href="#migrating-from-ol-versions">27. Migrating from older Buildroot versions</a></span></dt><dd><dl><dt><span class="section"><a href="#br2-external-converting">27.1. Migrating to 2016.11</a></span></dt><dt><span class="section"><a href="#migrating-host-usr">27.2. Migrating to 2017.08</a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-examples"><p><strong>List of Examples</strong></p><dl><dt>18.1. <a href="#idm3193">Config script: <span class="emphasis"><em>divine</em></span> package</a></dt><dt>18.2. <a href="#idm3200">Config script: <span class="emphasis"><em>imagemagick</em></span> package:</a></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="idm4"></a></h1></div></div></div><p>Buildroot 2021.05 manual generated on 2021-06-06
    3 21:24:05 UTC from git revision 69f79f2a2e</p><p>The Buildroot manual is written by the Buildroot developers.
    4 It is licensed under the GNU General Public License, version 2. Refer to the
    5 <a class="ulink" href="http://git.buildroot.org/buildroot/tree/COPYING?id=69f79f2a2ee1417e19c1ead2c9226e11753c06cb" target="_top">COPYING</a>
    6 file in the Buildroot sources for the full text of this license.</p><p>Copyright © 2004-2020 The Buildroot developers</p><div class="informalfigure"><div class="mediaobject"><img src="logo.png" alt="logo.png" /></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_getting_started"></a>Part I. Getting started</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_about_buildroot"></a>Chapter 1. About Buildroot</h2></div></div></div><p>Buildroot is a tool that simplifies and automates the process of
    7 building a complete Linux system for an embedded system, using
    8 cross-compilation.</p><p>In order to achieve this, Buildroot is able to generate a
    9 cross-compilation toolchain, a root filesystem, a Linux kernel image
   10 and a bootloader for your target. Buildroot can be used for any
   11 combination of these options, independently (you can for example use
   12 an existing cross-compilation toolchain, and build only your root
   13 filesystem with Buildroot).</p><p>Buildroot is useful mainly for people working with embedded systems.
   14 Embedded systems often use processors that are not the regular x86
   15 processors everyone is used to having in his PC. They can be PowerPC
   16 processors, MIPS processors, ARM processors, etc.</p><p>Buildroot supports numerous processors and their variants; it also
   17 comes with default configurations for several boards available
   18 off-the-shelf. Besides this, a number of third-party projects are based on,
   19 or develop their BSP <a href="#ftn.idm24" class="footnote" id="idm24"><sup class="footnote">[1]</sup></a> or
   20 SDK <a href="#ftn.idm26" class="footnote" id="idm26"><sup class="footnote">[2]</sup></a> on top of Buildroot.</p><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm24" class="footnote"><p><a href="#idm24" class="simpara"><sup class="simpara">[1] </sup></a>BSP: Board Support Package</p></div><div id="ftn.idm26" class="footnote"><p><a href="#idm26" class="simpara"><sup class="simpara">[2] </sup></a>SDK: Software Development Kit</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="requirement"></a>Chapter 2. System requirements</h2></div></div></div><p>Buildroot is designed to run on Linux systems.</p><p>While Buildroot itself will build most host packages it needs for the
   21 compilation, certain standard Linux utilities are expected to be
   22 already installed on the host system. Below you will find an overview of
   23 the mandatory and optional packages (note that package names may vary
   24 between distributions).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirement-mandatory"></a>2.1. Mandatory packages</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
   25 Build tools:
   26 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
   27 <code class="literal">which</code>
   28 </li><li class="listitem">
   29 <code class="literal">sed</code>
   30 </li><li class="listitem">
   31 <code class="literal">make</code> (version 3.81 or any later)
   32 </li><li class="listitem">
   33 <code class="literal">binutils</code>
   34 </li><li class="listitem">
   35 <code class="literal">build-essential</code> (only for Debian based systems)
   36 </li><li class="listitem">
   37 <code class="literal">gcc</code> (version 4.8 or any later)
   38 </li><li class="listitem">
   39 <code class="literal">g++</code> (version 4.8 or any later)
   40 </li><li class="listitem">
   41 <code class="literal">bash</code>
   42 </li><li class="listitem">
   43 <code class="literal">patch</code>
   44 </li><li class="listitem">
   45 <code class="literal">gzip</code>
   46 </li><li class="listitem">
   47 <code class="literal">bzip2</code>
   48 </li><li class="listitem">
   49 <code class="literal">perl</code> (version 5.8.7 or any later)
   50 </li><li class="listitem">
   51 <code class="literal">tar</code>
   52 </li><li class="listitem">
   53 <code class="literal">cpio</code>
   54 </li><li class="listitem">
   55 <code class="literal">unzip</code>
   56 </li><li class="listitem">
   57 <code class="literal">rsync</code>
   58 </li><li class="listitem">
   59 <code class="literal">file</code> (must be in <code class="literal">/usr/bin/file</code>)
   60 </li><li class="listitem">
   61 <code class="literal">bc</code>
   62 </li></ul></div></li><li class="listitem"><p class="simpara">
   63 Source fetching tools:
   64 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
   65 <code class="literal">wget</code>
   66 </li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirement-optional"></a>2.2. Optional packages</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
   67 Recommended dependencies:
   68 </p><p class="simpara">Some features or utilities in Buildroot, like the legal-info, or the
   69 graph generation tools, have additional dependencies. Although they
   70 are not mandatory for a simple build, they are still highly recommended:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
   71 <code class="literal">python</code> (version 2.7 or any later)
   72 </li></ul></div></li><li class="listitem"><p class="simpara">
   73 Configuration interface dependencies:
   74 </p><p class="simpara">For these libraries, you need to install both runtime and development
   75 data, which in many distributions are packaged separately. The
   76 development packages typically have a <span class="emphasis"><em>-dev</em></span> or <span class="emphasis"><em>-devel</em></span> suffix.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
   77 <code class="literal">ncurses5</code> to use the <span class="emphasis"><em>menuconfig</em></span> interface
   78 </li><li class="listitem">
   79 <code class="literal">qt5</code> to use the <span class="emphasis"><em>xconfig</em></span> interface
   80 </li><li class="listitem">
   81 <code class="literal">glib2</code>, <code class="literal">gtk2</code> and <code class="literal">glade2</code> to use the <span class="emphasis"><em>gconfig</em></span> interface
   82 </li></ul></div></li><li class="listitem"><p class="simpara">
   83 Source fetching tools:
   84 </p><p class="simpara">In the official tree, most of the package sources are retrieved using
   85 <code class="literal">wget</code> from <span class="emphasis"><em>ftp</em></span>, <span class="emphasis"><em>http</em></span> or <span class="emphasis"><em>https</em></span> locations. A few packages are only
   86 available through a version control system. Moreover, Buildroot is
   87 capable of downloading sources via other tools, like <code class="literal">rsync</code> or <code class="literal">scp</code>
   88 (refer to <a class="xref" href="#download-infra" title="Chapter 20. Download infrastructure">Chapter 20, <em>Download infrastructure</em></a> for more details). If you enable
   89 packages using any of these methods, you will need to install the
   90 corresponding tool on the host system:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
   91 <code class="literal">bazaar</code>
   92 </li><li class="listitem">
   93 <code class="literal">cvs</code>
   94 </li><li class="listitem">
   95 <code class="literal">git</code>
   96 </li><li class="listitem">
   97 <code class="literal">mercurial</code>
   98 </li><li class="listitem">
   99 <code class="literal">rsync</code>
  100 </li><li class="listitem">
  101 <code class="literal">scp</code>
  102 </li><li class="listitem">
  103 <code class="literal">subversion</code>
  104 </li></ul></div></li><li class="listitem"><p class="simpara">
  105 Java-related packages, if the Java Classpath needs to be built for
  106   the target system:
  107 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  108 The <code class="literal">javac</code> compiler
  109 </li><li class="listitem">
  110 The <code class="literal">jar</code> tool
  111 </li></ul></div></li><li class="listitem"><p class="simpara">
  112 Documentation generation tools:
  113 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  114 <code class="literal">asciidoc</code>, version 8.6.3 or higher
  115 </li><li class="listitem">
  116 <code class="literal">w3m</code>
  117 </li><li class="listitem">
  118 <code class="literal">python</code> with the <code class="literal">argparse</code> module (automatically present in 2.7+ and 3.2+)
  119 </li><li class="listitem">
  120 <code class="literal">dblatex</code> (required for the pdf manual only)
  121 </li></ul></div></li><li class="listitem"><p class="simpara">
  122 Graph generation tools:
  123 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  124 <code class="literal">graphviz</code> to use <span class="emphasis"><em>graph-depends</em></span> and <span class="emphasis"><em>&lt;pkg&gt;-graph-depends</em></span>
  125 </li><li class="listitem">
  126 <code class="literal">python-matplotlib</code> to use <span class="emphasis"><em>graph-build</em></span>
  127 </li></ul></div></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="getting-buildroot"></a>Chapter 3. Getting Buildroot</h2></div></div></div><p>Buildroot releases are made every 3 months, in February, May, August and
  128 November. Release numbers are in the format YYYY.MM, so for example
  129 2013.02, 2014.08.</p><p>Release tarballs are available at <a class="ulink" href="http://buildroot.org/downloads/" target="_top">http://buildroot.org/downloads/</a>.</p><p>For your convenience, a <a class="ulink" href="https://www.vagrantup.com/" target="_top">Vagrantfile</a> is
  130 available in <code class="literal">support/misc/Vagrantfile</code> in the Buildroot source tree
  131 to quickly set up a virtual machine with the needed dependencies to
  132 get started.</p><p>If you want to setup an isolated buildroot environment on Linux or Mac
  133 Os X, paste this line onto your terminal:</p><pre class="screen">curl -O https://buildroot.org/downloads/Vagrantfile; vagrant up</pre><p>If you are on Windows, paste this into your powershell:</p><pre class="screen">(new-object System.Net.WebClient).DownloadFile(
  134 "https://buildroot.org/downloads/Vagrantfile","Vagrantfile");
  135 vagrant up</pre><p>If you want to follow development, you can use the daily snapshots or
  136 make a clone of the Git repository. Refer to the
  137 <a class="ulink" href="http://buildroot.org/download" target="_top">Download page</a> of the Buildroot website
  138 for more details.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_buildroot_quick_start"></a>Chapter 4. Buildroot quick start</h2></div></div></div><p><span class="strong"><strong>Important</strong></span>: you can and should <span class="strong"><strong>build everything as a normal user</strong></span>. There
  139 is no need to be root to configure and use Buildroot. By running all
  140 commands as a regular user, you protect your system against packages
  141 behaving badly during compilation and installation.</p><p>The first step when using Buildroot is to create a configuration.
  142 Buildroot has a nice configuration tool similar to the one you can
  143 find in the <a class="ulink" href="http://www.kernel.org/" target="_top">Linux kernel</a> or in
  144 <a class="ulink" href="http://www.busybox.net/" target="_top">BusyBox</a>.</p><p>From the buildroot directory, run</p><pre class="screen"> $ make menuconfig</pre><p>for the original curses-based configurator, or</p><pre class="screen"> $ make nconfig</pre><p>for the new curses-based configurator, or</p><pre class="screen"> $ make xconfig</pre><p>for the Qt-based configurator, or</p><pre class="screen"> $ make gconfig</pre><p>for the GTK-based configurator.</p><p>All of these "make" commands will need to build a configuration
  145 utility (including the interface), so you may need to install
  146 "development" packages for relevant libraries used by the
  147 configuration utilities. Refer to <a class="xref" href="#requirement" title="Chapter 2. System requirements">Chapter 2, <em>System requirements</em></a> for more details,
  148 specifically the <a class="link" href="#requirement-optional" title="2.2. Optional packages">optional requirements</a>
  149 to get the dependencies of your favorite interface.</p><p>For each menu entry in the configuration tool, you can find associated
  150 help that describes the purpose of the entry. Refer to <a class="xref" href="#configure" title="Chapter 6. Buildroot configuration">Chapter 6, <em>Buildroot configuration</em></a>
  151 for details on some specific configuration aspects.</p><p>Once everything is configured, the configuration tool generates a
  152 <code class="literal">.config</code> file that contains the entire configuration. This file will be
  153 read by the top-level Makefile.</p><p>To start the build process, simply run:</p><pre class="screen"> $ make</pre><p>By default, Buildroot does not support top-level parallel build, so
  154 running <code class="literal">make -jN</code> is not necessary. There is however experimental
  155 support for top-level parallel build, see
  156 <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a>.</p><p>The <code class="literal">make</code> command will generally perform the following steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  157 download source files (as required);
  158 </li><li class="listitem">
  159 configure, build and install the cross-compilation toolchain, or
  160   simply import an external toolchain;
  161 </li><li class="listitem">
  162 configure, build and install selected target packages;
  163 </li><li class="listitem">
  164 build a kernel image, if selected;
  165 </li><li class="listitem">
  166 build a bootloader image, if selected;
  167 </li><li class="listitem">
  168 create a root filesystem in selected formats.
  169 </li></ul></div><p>Buildroot output is stored in a single directory, <code class="literal">output/</code>.
  170 This directory contains several subdirectories:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  171 <code class="literal">images/</code> where all the images (kernel image, bootloader and root
  172   filesystem images) are stored. These are the files you need to put
  173   on your target system.
  174 </li><li class="listitem">
  175 <code class="literal">build/</code> where all the components are built (this includes tools
  176   needed by Buildroot on the host and packages compiled for the
  177   target). This directory contains one subdirectory for each of these
  178   components.
  179 </li><li class="listitem">
  180 <code class="literal">host/</code> contains both the tools built for the host, and the sysroot
  181   of the target toolchain. The former is an installation of tools
  182   compiled for the host that are needed for the proper execution of
  183   Buildroot, including the cross-compilation toolchain. The latter
  184   is a hierarchy similar to a root filesystem hierarchy. It contains
  185   the headers and libraries of all user-space packages that provide
  186   and install libraries used by other packages. However, this
  187   directory is <span class="emphasis"><em>not</em></span> intended to be the root filesystem for the target:
  188   it contains a lot of development files, unstripped binaries and
  189   libraries that make it far too big for an embedded system. These
  190   development files are used to compile libraries and applications for
  191   the target that depend on other libraries.
  192 </li><li class="listitem">
  193 <code class="literal">staging/</code> is a symlink to the target toolchain sysroot inside
  194   <code class="literal">host/</code>, which exists for backwards compatibility.
  195 </li><li class="listitem">
  196 <code class="literal">target/</code> which contains <span class="emphasis"><em>almost</em></span> the complete root filesystem for
  197   the target: everything needed is present except the device files in
  198   <code class="literal">/dev/</code> (Buildroot can’t create them because Buildroot doesn’t run
  199   as root and doesn’t want to run as root). Also, it doesn’t have the correct
  200   permissions (e.g. setuid for the busybox binary). Therefore, this directory
  201   <span class="strong"><strong>should not be used on your target</strong></span>. Instead, you should use one of
  202   the images built in the <code class="literal">images/</code> directory. If you need an
  203   extracted image of the root filesystem for booting over NFS, then
  204   use the tarball image generated in <code class="literal">images/</code> and extract it as
  205   root. Compared to <code class="literal">staging/</code>, <code class="literal">target/</code> contains only the files and
  206   libraries needed to run the selected target applications: the
  207   development files (headers, etc.) are not present, the binaries are
  208   stripped.
  209 </li></ul></div><p>These commands, <code class="literal">make menuconfig|nconfig|gconfig|xconfig</code> and <code class="literal">make</code>, are the
  210 basic ones that allow to easily and quickly generate images fitting
  211 your needs, with all the features and applications you enabled.</p><p>More details about the "make" command usage are given in
  212 <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a>.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="community-resources"></a>Chapter 5. Community resources</h2></div></div></div><p>Like any open source project, Buildroot has different ways to share
  213 information in its community and outside.</p><p>Each of those ways may interest you if you are looking for some help,
  214 want to understand Buildroot or contribute to the project.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  215 Mailing List
  216 </span></dt><dd><p class="simpara">Buildroot has a mailing list for discussion and development. It is the
  217 main method of interaction for Buildroot users and developers.</p><p class="simpara">Only subscribers to the Buildroot mailing list are allowed to post to
  218 this list. You can subscribe via the
  219 <a class="ulink" href="http://lists.buildroot.org/mailman/listinfo/buildroot" target="_top">mailing list info
  220 page</a>.</p><p class="simpara">Mails that are sent to the mailing list are also available in the
  221 <a class="ulink" href="http://lists.buildroot.org/pipermail/buildroot" target="_top">mailing list archives</a> and
  222 via <a class="ulink" href="http://gmane.org" target="_top">Gmane</a>, at
  223 <a class="ulink" href="http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot" target="_top"><code class="literal">gmane.comp.lib.uclibc.buildroot</code></a>.
  224 Please search the mailing list archives before asking questions, since
  225 there is a good chance someone else has asked the same question before.</p></dd><dt><span class="term">
  226 IRC
  227 </span></dt><dd><p class="simpara">The Buildroot IRC channel <a class="ulink" href="irc://irc.oftc.net/#buildroot" target="_top">#buildroot</a> is
  228 hosted on <a class="ulink" href="https://www.oftc.net/WebChat/" target="_top">OFTC</a>. It is a useful place to
  229 ask quick questions or discuss on certain topics.</p><p class="simpara">When asking for help on IRC, share relevant logs or pieces of code
  230 using a code sharing website, such as <a class="ulink" href="http://code.bulix.org" target="_top">http://code.bulix.org</a>.</p><p class="simpara">Note that for certain questions, posting to the mailing list may be
  231 better as it will reach more people, both developers and users.</p></dd><dt><span class="term">
  232 Bug tracker
  233 </span></dt><dd>Bugs in Buildroot can be reported via the mailing list or alternatively
  234 via the <a class="ulink" href="https://bugs.buildroot.org/buglist.cgi?product=buildroot" target="_top">Buildroot
  235 bugtracker</a>. Please refer to <a class="xref" href="#reporting-bugs" title="22.6. Reporting issues/bugs or getting help">Section 22.6, “Reporting issues/bugs or getting help”</a> before creating a bug
  236 report.</dd><dt><span class="term">
  237 Wiki
  238 </span></dt><dd><a class="ulink" href="http://elinux.org/Buildroot" target="_top">The Buildroot wiki page</a> is hosted on
  239 the <a class="ulink" href="http://elinux.org" target="_top">eLinux</a> wiki. It contains some useful links, an
  240 overview of past and upcoming events, and a TODO list.</dd><dt><span class="term">
  241 Patchwork
  242 </span></dt><dd><p class="simpara">Patchwork is a web-based patch tracking system designed to facilitate
  243 the contribution and management of contributions to an open-source
  244 project. Patches that have been sent to a mailing list are 'caught' by
  245 the system, and appear on a web page. Any comments posted that
  246 reference the patch are appended to the patch page too. For more
  247 information on Patchwork see
  248 <a class="ulink" href="http://jk.ozlabs.org/projects/patchwork/" target="_top">http://jk.ozlabs.org/projects/patchwork/</a>.</p><p class="simpara">Buildroot’s Patchwork website is mainly for use by Buildroot’s
  249 maintainer to ensure patches aren’t missed. It is also used by Buildroot
  250 patch reviewers (see also <a class="xref" href="#apply-patches-patchwork" title="22.3.1. Applying Patches from Patchwork">Section 22.3.1, “Applying Patches from Patchwork”</a>).
  251 However, since the website exposes patches and their corresponding
  252 review comments in a clean and concise web interface, it can be useful
  253 for all Buildroot developers.</p><p class="simpara">The Buildroot patch management interface is available at
  254 <a class="ulink" href="http://patchwork.buildroot.org" target="_top">http://patchwork.buildroot.org</a>.</p></dd></dl></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_user_guide"></a>Part II. User guide</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="configure"></a>Chapter 6. Buildroot configuration</h2></div></div></div><p>All the configuration options in <code class="literal">make *config</code> have a help text
  255 providing details about the option.</p><p>The <code class="literal">make *config</code> commands also offer a search tool. Read the help
  256 message in the different frontend menus to know how to use it:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  257 in <span class="emphasis"><em>menuconfig</em></span>, the search tool is called by pressing <code class="literal">/</code>;
  258 </li><li class="listitem">
  259 in <span class="emphasis"><em>xconfig</em></span>, the search tool is called by pressing <code class="literal">Ctrl</code> + <code class="literal">f</code>.
  260 </li></ul></div><p>The result of the search shows the help message of the matching items.
  261 In <span class="emphasis"><em>menuconfig</em></span>, numbers in the left column provide a shortcut to the
  262 corresponding entry. Just type this number to directly jump to the
  263 entry, or to the containing menu in case the entry is not selectable due
  264 to a missing dependency.</p><p>Although the menu structure and the help text of the entries should be
  265 sufficiently self-explanatory, a number of topics require additional
  266 explanation that cannot easily be covered in the help text and are
  267 therefore covered in the following sections.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_cross_compilation_toolchain"></a>6.1. Cross-compilation toolchain</h2></div></div></div><p>A compilation toolchain is the set of tools that allows you to compile
  268 code for your system. It consists of a compiler (in our case, <code class="literal">gcc</code>),
  269 binary utils like assembler and linker (in our case, <code class="literal">binutils</code>) and a
  270 C standard library (for example
  271 <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">GNU Libc</a>,
  272 <a class="ulink" href="http://www.uclibc-ng.org/" target="_top">uClibc-ng</a>).</p><p>The system installed on your development station certainly already has
  273 a compilation toolchain that you can use to compile an application
  274 that runs on your system. If you’re using a PC, your compilation
  275 toolchain runs on an x86 processor and generates code for an x86
  276 processor. Under most Linux systems, the compilation toolchain uses
  277 the GNU libc (glibc) as the C standard library. This compilation
  278 toolchain is called the "host compilation toolchain". The machine on
  279 which it is running, and on which you’re working, is called the "host
  280 system" <a href="#ftn.idm363" class="footnote" id="idm363"><sup class="footnote">[3]</sup></a>.</p><p>The compilation toolchain is provided by your distribution, and
  281 Buildroot has nothing to do with it (other than using it to build a
  282 cross-compilation toolchain and other tools that are run on the
  283 development host).</p><p>As said above, the compilation toolchain that comes with your system
  284 runs on and generates code for the processor in your host system. As
  285 your embedded system has a different processor, you need a
  286 cross-compilation toolchain - a compilation toolchain that runs on
  287 your <span class="emphasis"><em>host system</em></span> but generates code for your <span class="emphasis"><em>target system</em></span> (and
  288 target processor). For example, if your host system uses x86 and your
  289 target system uses ARM, the regular compilation toolchain on your host
  290 runs on x86 and generates code for x86, while the cross-compilation
  291 toolchain runs on x86 and generates code for ARM.</p><p>Buildroot provides two solutions for the cross-compilation toolchain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  292 The <span class="strong"><strong>internal toolchain backend</strong></span>, called <code class="literal">Buildroot toolchain</code> in
  293    the configuration interface.
  294 </li><li class="listitem">
  295 The <span class="strong"><strong>external toolchain backend</strong></span>, called <code class="literal">External toolchain</code> in
  296    the configuration interface.
  297 </li></ul></div><p>The choice between these two solutions is done using the <code class="literal">Toolchain
  298 Type</code> option in the <code class="literal">Toolchain</code> menu. Once one solution has been
  299 chosen, a number of configuration options appear, they are detailed in
  300 the following sections.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="internal-toolchain-backend"></a>6.1.1. Internal toolchain backend</h3></div></div></div><p>The <span class="emphasis"><em>internal toolchain backend</em></span> is the backend where Buildroot builds
  301 by itself a cross-compilation toolchain, before building the userspace
  302 applications and libraries for your target embedded system.</p><p>This backend supports several C libraries:
  303 <a class="ulink" href="http://www.uclibc-ng.org" target="_top">uClibc-ng</a>,
  304 <a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> and
  305 <a class="ulink" href="http://www.musl-libc.org" target="_top">musl</a>.</p><p>Once you have selected this backend, a number of options appear. The
  306 most important ones allow to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  307 Change the version of the Linux kernel headers used to build the
  308    toolchain. This item deserves a few explanations. In the process of
  309    building a cross-compilation toolchain, the C library is being
  310    built. This library provides the interface between userspace
  311    applications and the Linux kernel. In order to know how to "talk"
  312    to the Linux kernel, the C library needs to have access to the
  313    <span class="emphasis"><em>Linux kernel headers</em></span> (i.e. the <code class="literal">.h</code> files from the kernel), which
  314    define the interface between userspace and the kernel (system
  315    calls, data structures, etc.). Since this interface is backward
  316    compatible, the version of the Linux kernel headers used to build
  317    your toolchain do not need to match <span class="emphasis"><em>exactly</em></span> the version of the
  318    Linux kernel you intend to run on your embedded system. They only
  319    need to have a version equal or older to the version of the Linux
  320    kernel you intend to run. If you use kernel headers that are more
  321    recent than the Linux kernel you run on your embedded system, then
  322    the C library might be using interfaces that are not provided by
  323    your Linux kernel.
  324 </li><li class="listitem">
  325 Change the version of the GCC compiler, binutils and the C library.
  326 </li><li class="listitem">
  327 Select a number of toolchain options (uClibc only): whether the
  328    toolchain should have RPC support (used mainly for NFS),
  329    wide-char support, locale support (for internationalization),
  330    C++ support or thread support. Depending on which options you choose,
  331    the number of userspace applications and libraries visible in
  332    Buildroot menus will change: many applications and libraries require
  333    certain toolchain options to be enabled. Most packages show a comment
  334    when a certain toolchain option is required to be able to enable
  335    those packages. If needed, you can further refine the uClibc
  336    configuration by running <code class="literal">make uclibc-menuconfig</code>. Note however that
  337    all packages in Buildroot are tested against the default uClibc
  338    configuration bundled in Buildroot: if you deviate from this
  339    configuration by removing features from uClibc, some packages may no
  340    longer build.
  341 </li></ul></div><p>It is worth noting that whenever one of those options is modified,
  342 then the entire toolchain and system must be rebuilt. See
  343 <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a>.</p><p>Advantages of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  344 Well integrated with Buildroot
  345 </li><li class="listitem">
  346 Fast, only builds what’s necessary
  347 </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  348 Rebuilding the toolchain is needed when doing <code class="literal">make clean</code>, which
  349   takes time. If you’re trying to reduce your build time, consider
  350   using the <span class="emphasis"><em>External toolchain backend</em></span>.
  351 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="external-toolchain-backend"></a>6.1.2. External toolchain backend</h3></div></div></div><p>The <span class="emphasis"><em>external toolchain backend</em></span> allows to use existing pre-built
  352 cross-compilation toolchains. Buildroot knows about a number of
  353 well-known cross-compilation toolchains (from
  354 <a class="ulink" href="http://www.linaro.org" target="_top">Linaro</a> for ARM,
  355 <a class="ulink" href="http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/" target="_top">Sourcery
  356 CodeBench</a> for ARM, x86-64, PowerPC, and MIPS, and is capable of
  357 downloading them automatically, or it can be pointed to a custom
  358 toolchain, either available for download or installed locally.</p><p>Then, you have three solutions to use an external toolchain:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  359 Use a predefined external toolchain profile, and let Buildroot
  360   download, extract and install the toolchain. Buildroot already knows
  361   about a few CodeSourcery and Linaro toolchains. Just select the
  362   toolchain profile in <code class="literal">Toolchain</code> from the available ones. This is
  363   definitely the easiest solution.
  364 </li><li class="listitem">
  365 Use a predefined external toolchain profile, but instead of having
  366   Buildroot download and extract the toolchain, you can tell Buildroot
  367   where your toolchain is already installed on your system. Just
  368   select the toolchain profile in <code class="literal">Toolchain</code> through the available
  369   ones, unselect <code class="literal">Download toolchain automatically</code>, and fill the
  370   <code class="literal">Toolchain path</code> text entry with the path to your cross-compiling
  371   toolchain.
  372 </li><li class="listitem">
  373 Use a completely custom external toolchain. This is particularly
  374   useful for toolchains generated using crosstool-NG or with Buildroot
  375   itself. To do this, select the <code class="literal">Custom toolchain</code> solution in the
  376   <code class="literal">Toolchain</code> list. You need to fill the <code class="literal">Toolchain path</code>, <code class="literal">Toolchain
  377   prefix</code> and <code class="literal">External toolchain C library</code> options. Then, you have
  378   to tell Buildroot what your external toolchain supports. If your
  379   external toolchain uses the <span class="emphasis"><em>glibc</em></span> library, you only have to tell
  380   whether your toolchain supports C++ or not and whether it has
  381   built-in RPC support. If your external toolchain uses the <span class="emphasis"><em>uClibc</em></span>
  382   library, then you have to tell Buildroot if it supports RPC,
  383   wide-char, locale, program invocation, threads and C++.
  384   At the beginning of the execution, Buildroot will tell you if
  385   the selected options do not match the toolchain configuration.
  386 </li></ul></div><p>Our external toolchain support has been tested with toolchains from
  387 CodeSourcery and Linaro, toolchains generated by
  388 <a class="ulink" href="http://crosstool-ng.org" target="_top">crosstool-NG</a>, and toolchains generated by
  389 Buildroot itself. In general, all toolchains that support the
  390 <span class="emphasis"><em>sysroot</em></span> feature should work. If not, do not hesitate to contact the
  391 developers.</p><p>We do not support toolchains or SDK generated by OpenEmbedded or
  392 Yocto, because these toolchains are not pure toolchains (i.e. just the
  393 compiler, binutils, the C and C++ libraries). Instead these toolchains
  394 come with a very large set of pre-compiled libraries and
  395 programs. Therefore, Buildroot cannot import the <span class="emphasis"><em>sysroot</em></span> of the
  396 toolchain, as it would contain hundreds of megabytes of pre-compiled
  397 libraries that are normally built by Buildroot.</p><p>We also do not support using the distribution toolchain (i.e. the
  398 gcc/binutils/C library installed by your distribution) as the
  399 toolchain to build software for the target. This is because your
  400 distribution toolchain is not a "pure" toolchain (i.e. only with the
  401 C/C++ library), so we cannot import it properly into the Buildroot
  402 build environment. So even if you are building a system for a x86 or
  403 x86_64 target, you have to generate a cross-compilation toolchain with
  404 Buildroot or crosstool-NG.</p><p>If you want to generate a custom toolchain for your project, that can
  405 be used as an external toolchain in Buildroot, our recommendation is
  406 to build it either with Buildroot itself (see
  407 <a class="xref" href="#build-toolchain-with-buildroot" title="6.1.3. Build an external toolchain with Buildroot">Section 6.1.3, “Build an external toolchain with Buildroot”</a>) or with
  408 <a class="ulink" href="http://crosstool-ng.org" target="_top">crosstool-NG</a>.</p><p>Advantages of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  409 Allows to use well-known and well-tested cross-compilation
  410   toolchains.
  411 </li><li class="listitem">
  412 Avoids the build time of the cross-compilation toolchain, which is
  413   often very significant in the overall build time of an embedded
  414   Linux system.
  415 </li></ul></div><p>Drawbacks of this backend:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  416 If your pre-built external toolchain has a bug, may be hard to get a
  417   fix from the toolchain vendor, unless you build your external
  418   toolchain by yourself using Buildroot or Crosstool-NG.
  419 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build-toolchain-with-buildroot"></a>6.1.3. Build an external toolchain with Buildroot</h3></div></div></div><p>The Buildroot internal toolchain option can be used to create an
  420 external toolchain. Here are a series of steps to build an internal
  421 toolchain and package it up for reuse by Buildroot itself (or other
  422 projects).</p><p>Create a new Buildroot configuration, with the following details:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  423 Select the appropriate <span class="strong"><strong>Target options</strong></span> for your target CPU
  424   architecture
  425 </li><li class="listitem">
  426 In the <span class="strong"><strong>Toolchain</strong></span> menu, keep the default of <span class="strong"><strong>Buildroot toolchain</strong></span>
  427   for <span class="strong"><strong>Toolchain type</strong></span>, and configure your toolchain as desired
  428 </li><li class="listitem">
  429 In the <span class="strong"><strong>System configuration</strong></span> menu, select <span class="strong"><strong>None</strong></span> as the <span class="strong"><strong>Init
  430   system</strong></span> and <span class="strong"><strong>none</strong></span> as <span class="strong"><strong>/bin/sh</strong></span>
  431 </li><li class="listitem">
  432 In the <span class="strong"><strong>Target packages</strong></span> menu, disable <span class="strong"><strong>BusyBox</strong></span>
  433 </li><li class="listitem">
  434 In the <span class="strong"><strong>Filesystem images</strong></span> menu, disable <span class="strong"><strong>tar the root filesystem</strong></span>
  435 </li></ul></div><p>Then, we can trigger the build, and also ask Buildroot to generate a
  436 SDK. This will conveniently generate for us a tarball which contains
  437 our toolchain:</p><pre class="screen">make sdk</pre><p>This produces the SDK tarball in <code class="literal">$(O)/images</code>, with a name similar to
  438 <code class="literal">arm-buildroot-linux-uclibcgnueabi_sdk-buildroot.tar.gz</code>. Save this
  439 tarball, as it is now the toolchain that you can re-use as an external
  440 toolchain in other Buildroot projects.</p><p>In those other Buildroot projects, in the <span class="strong"><strong>Toolchain</strong></span> menu:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  441 Set <span class="strong"><strong>Toolchain type</strong></span> to <span class="strong"><strong>External toolchain</strong></span>
  442 </li><li class="listitem">
  443 Set <span class="strong"><strong>Toolchain</strong></span> to <span class="strong"><strong>Custom toolchain</strong></span>
  444 </li><li class="listitem">
  445 Set <span class="strong"><strong>Toolchain origin</strong></span> to <span class="strong"><strong>Toolchain to be downloaded and installed</strong></span>
  446 </li><li class="listitem">
  447 Set <span class="strong"><strong>Toolchain URL</strong></span> to <code class="literal">file:///path/to/your/sdk/tarball.tar.gz</code>
  448 </li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_external_toolchain_wrapper"></a>External toolchain wrapper</h4></div></div></div><p>When using an external toolchain, Buildroot generates a wrapper program,
  449 that transparently passes the appropriate options (according to the
  450 configuration) to the external toolchain programs. In case you need to
  451 debug this wrapper to check exactly what arguments are passed, you can
  452 set the environment variable <code class="literal">BR2_DEBUG_WRAPPER</code> to either one of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  453 <code class="literal">0</code>, empty or not set: no debug
  454 </li><li class="listitem">
  455 <code class="literal">1</code>: trace all arguments on a single line
  456 </li><li class="listitem">
  457 <code class="literal">2</code>: trace one argument per line
  458 </li></ul></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_dev_management"></a>6.2. /dev management</h2></div></div></div><p>On a Linux system, the <code class="literal">/dev</code> directory contains special files, called
  459 <span class="emphasis"><em>device files</em></span>, that allow userspace applications to access the
  460 hardware devices managed by the Linux kernel. Without these <span class="emphasis"><em>device
  461 files</em></span>, your userspace applications would not be able to use the
  462 hardware devices, even if they are properly recognized by the Linux
  463 kernel.</p><p>Under <code class="literal">System configuration</code>, <code class="literal">/dev management</code>, Buildroot offers four
  464 different solutions to handle the <code class="literal">/dev</code> directory :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  465 The first solution is <span class="strong"><strong>Static using device table</strong></span>. This is the old
  466    classical way of handling device files in Linux. With this method,
  467    the device files are persistently stored in the root filesystem
  468    (i.e. they persist across reboots), and there is nothing that will
  469    automatically create and remove those device files when hardware
  470    devices are added or removed from the system. Buildroot therefore
  471    creates a standard set of device files using a <span class="emphasis"><em>device table</em></span>, the
  472    default one being stored in <code class="literal">system/device_table_dev.txt</code> in the
  473    Buildroot source code. This file is processed when Buildroot
  474    generates the final root filesystem image, and the <span class="emphasis"><em>device files</em></span>
  475    are therefore not visible in the <code class="literal">output/target</code> directory. The
  476    <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> option allows to change the
  477    default device table used by Buildroot, or to add an additional
  478    device table, so that additional <span class="emphasis"><em>device files</em></span> are created by
  479    Buildroot during the build. So, if you use this method, and a
  480    <span class="emphasis"><em>device file</em></span> is missing in your system, you can for example create
  481    a <code class="literal">board/&lt;yourcompany&gt;/&lt;yourproject&gt;/device_table_dev.txt</code> file
  482    that contains the description of your additional <span class="emphasis"><em>device files</em></span>,
  483    and then you can set <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to
  484    <code class="literal">system/device_table_dev.txt
  485    board/&lt;yourcompany&gt;/&lt;yourproject&gt;/device_table_dev.txt</code>. For more
  486    details about the format of the device table file, see
  487    <a class="xref" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">Chapter 25, <em>Makedev syntax documentation</em></a>.
  488 </li><li class="listitem">
  489 The second solution is <span class="strong"><strong>Dynamic using devtmpfs only</strong></span>. <span class="emphasis"><em>devtmpfs</em></span> is
  490    a virtual filesystem inside the Linux kernel that has been
  491    introduced in kernel 2.6.32 (if you use an older kernel, it is not
  492    possible to use this option). When mounted in <code class="literal">/dev</code>, this virtual
  493    filesystem will automatically make <span class="emphasis"><em>device files</em></span> appear and
  494    disappear as hardware devices are added and removed from the
  495    system. This filesystem is not persistent across reboots: it is
  496    filled dynamically by the kernel. Using <span class="emphasis"><em>devtmpfs</em></span> requires the
  497    following kernel configuration options to be enabled:
  498    <code class="literal">CONFIG_DEVTMPFS</code> and <code class="literal">CONFIG_DEVTMPFS_MOUNT</code>. When Buildroot is in
  499    charge of building the Linux kernel for your embedded device, it
  500    makes sure that those two options are enabled. However, if you
  501    build your Linux kernel outside of Buildroot, then it is your
  502    responsibility to enable those two options (if you fail to do so,
  503    your Buildroot system will not boot).
  504 </li><li class="listitem">
  505 The third solution is <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span>. This method
  506    also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed above (so
  507    the requirement to have <code class="literal">CONFIG_DEVTMPFS</code> and
  508    <code class="literal">CONFIG_DEVTMPFS_MOUNT</code> enabled in the kernel configuration still
  509    apply), but adds the <code class="literal">mdev</code> userspace utility on top of it. <code class="literal">mdev</code>
  510    is a program part of BusyBox that the kernel will call every time a
  511    device is added or removed. Thanks to the <code class="literal">/etc/mdev.conf</code>
  512    configuration file, <code class="literal">mdev</code> can be configured to for example, set
  513    specific permissions or ownership on a device file, call a script
  514    or application whenever a device appears or disappear,
  515    etc. Basically, it allows <span class="emphasis"><em>userspace</em></span> to react on device addition
  516    and removal events. <code class="literal">mdev</code> can for example be used to automatically
  517    load kernel modules when devices appear on the system. <code class="literal">mdev</code> is
  518    also important if you have devices that require a firmware, as it
  519    will be responsible for pushing the firmware contents to the
  520    kernel. <code class="literal">mdev</code> is a lightweight implementation (with fewer
  521    features) of <code class="literal">udev</code>. For more details about <code class="literal">mdev</code> and the syntax
  522    of its configuration file, see
  523    <a class="ulink" href="http://git.busybox.net/busybox/tree/docs/mdev.txt" target="_top">http://git.busybox.net/busybox/tree/docs/mdev.txt</a>.
  524 </li><li class="listitem">
  525 The fourth solution is <span class="strong"><strong>Dynamic using devtmpfs + eudev</strong></span>. This
  526    method also relies on the <span class="emphasis"><em>devtmpfs</em></span> virtual filesystem detailed
  527    above, but adds the <code class="literal">eudev</code> userspace daemon on top of it. <code class="literal">eudev</code>
  528    is a daemon that runs in the background, and gets called by the
  529    kernel when a device gets added or removed from the system. It is a
  530    more heavyweight solution than <code class="literal">mdev</code>, but provides higher
  531    flexibility.  <code class="literal">eudev</code> is a standalone version of <code class="literal">udev</code>, the
  532    original userspace daemon used in most desktop Linux distributions,
  533    which is now part of Systemd. For more details, see
  534    <a class="ulink" href="http://en.wikipedia.org/wiki/Udev" target="_top">http://en.wikipedia.org/wiki/Udev</a>.
  535 </li></ul></div><p>The Buildroot developers recommendation is to start with the <span class="strong"><strong>Dynamic
  536 using devtmpfs only</strong></span> solution, until you have the need for userspace
  537 to be notified when devices are added/removed, or if firmwares are
  538 needed, in which case <span class="strong"><strong>Dynamic using devtmpfs + mdev</strong></span> is usually a
  539 good solution.</p><p>Note that if <code class="literal">systemd</code> is chosen as init system, /dev management will
  540 be performed by the <code class="literal">udev</code> program provided by <code class="literal">systemd</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_init_system"></a>6.3. init system</h2></div></div></div><p>The <span class="emphasis"><em>init</em></span> program is the first userspace program started by the
  541 kernel (it carries the PID number 1), and is responsible for starting
  542 the userspace services and programs (for example: web server,
  543 graphical applications, other network servers, etc.).</p><p>Buildroot allows to use three different types of init systems, which
  544 can be chosen from <code class="literal">System configuration</code>, <code class="literal">Init system</code>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  545 The first solution is <span class="strong"><strong>BusyBox</strong></span>. Amongst many programs, BusyBox has
  546    an implementation of a basic <code class="literal">init</code> program, which is sufficient
  547    for most embedded systems. Enabling the <code class="literal">BR2_INIT_BUSYBOX</code> will
  548    ensure BusyBox will build and install its <code class="literal">init</code> program. This is
  549    the default solution in Buildroot. The BusyBox <code class="literal">init</code> program will
  550    read the <code class="literal">/etc/inittab</code> file at boot to know what to do. The syntax
  551    of this file can be found in
  552    <a class="ulink" href="http://git.busybox.net/busybox/tree/examples/inittab" target="_top">http://git.busybox.net/busybox/tree/examples/inittab</a> (note that
  553    BusyBox <code class="literal">inittab</code> syntax is special: do not use a random <code class="literal">inittab</code>
  554    documentation from the Internet to learn about BusyBox
  555    <code class="literal">inittab</code>). The default <code class="literal">inittab</code> in Buildroot is stored in
  556    <code class="literal">system/skeleton/etc/inittab</code>. Apart from mounting a few important
  557    filesystems, the main job the default inittab does is to start the
  558    <code class="literal">/etc/init.d/rcS</code> shell script, and start a <code class="literal">getty</code> program (which
  559    provides a login prompt).
  560 </li><li class="listitem">
  561 The second solution is <span class="strong"><strong>systemV</strong></span>. This solution uses the old
  562    traditional <span class="emphasis"><em>sysvinit</em></span> program, packed in Buildroot in
  563    <code class="literal">package/sysvinit</code>. This was the solution used in most desktop
  564    Linux distributions, until they switched to more recent
  565    alternatives such as Upstart or Systemd. <code class="literal">sysvinit</code> also works with
  566    an <code class="literal">inittab</code> file (which has a slightly different syntax than the
  567    one from BusyBox). The default <code class="literal">inittab</code> installed with this init
  568    solution is located in <code class="literal">package/sysvinit/inittab</code>.
  569 </li><li class="listitem">
  570 The third solution is <span class="strong"><strong>systemd</strong></span>. <code class="literal">systemd</code> is the new generation
  571    init system for Linux. It does far more than traditional <span class="emphasis"><em>init</em></span>
  572    programs: aggressive parallelization capabilities, uses socket and
  573    D-Bus activation for starting services, offers on-demand starting
  574    of daemons, keeps track of processes using Linux control groups,
  575    supports snapshotting and restoring of the system state,
  576    etc. <code class="literal">systemd</code> will be useful on relatively complex embedded
  577    systems, for example the ones requiring D-Bus and services
  578    communicating between each other. It is worth noting that <code class="literal">systemd</code>
  579    brings a fairly big number of large dependencies: <code class="literal">dbus</code>, <code class="literal">udev</code>
  580    and more. For more details about <code class="literal">systemd</code>, see
  581    <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd" target="_top">http://www.freedesktop.org/wiki/Software/systemd</a>.
  582 </li></ul></div><p>The solution recommended by Buildroot developers is to use the
  583 <span class="strong"><strong>BusyBox init</strong></span> as it is sufficient for most embedded
  584 systems. <span class="strong"><strong>systemd</strong></span> can be used for more complex situations.</p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm363" class="footnote"><p><a href="#idm363" class="simpara"><sup class="simpara">[3] </sup></a>This terminology differs from what is used by GNU
  585 configure, where the host is the machine on which the application will
  586 run (which is usually the same as target)</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_configuration_of_other_components"></a>Chapter 7. Configuration of other components</h2></div></div></div><p>Before attempting to modify any of the components below, make sure you
  587 have already configured Buildroot itself, and have enabled the
  588 corresponding package.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
  589 BusyBox
  590 </span></dt><dd><p class="simpara">If you already have a BusyBox configuration file, you can directly
  591 specify this file in the Buildroot configuration, using
  592 <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>. Otherwise, Buildroot will start from a
  593 default BusyBox configuration file.</p><p class="simpara">To make subsequent changes to the configuration, use <code class="literal">make
  594 busybox-menuconfig</code> to open the BusyBox configuration editor.</p><p class="simpara">It is also possible to specify a BusyBox configuration file through an
  595 environment variable, although this is not recommended. Refer to
  596 <a class="xref" href="#env-vars" title="8.6. Environment variables">Section 8.6, “Environment variables”</a> for more details.</p></dd><dt><span class="term">
  597 uClibc
  598 </span></dt><dd>Configuration of uClibc is done in the same way as for BusyBox. The
  599 configuration variable to specify an existing configuration file is
  600 <code class="literal">BR2_UCLIBC_CONFIG</code>. The command to make subsequent changes is <code class="literal">make
  601 uclibc-menuconfig</code>.</dd><dt><span class="term">
  602 Linux kernel
  603 </span></dt><dd><p class="simpara">If you already have a kernel configuration file, you can directly
  604 specify this file in the Buildroot configuration, using
  605 <code class="literal">BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG</code>.</p><p class="simpara">If you do not yet have a kernel configuration file, you can either start
  606 by specifying a defconfig in the Buildroot configuration, using
  607 <code class="literal">BR2_LINUX_KERNEL_USE_DEFCONFIG</code>, or start by creating an empty file and
  608 specifying it as custom configuration file, using
  609 <code class="literal">BR2_LINUX_KERNEL_USE_CUSTOM_CONFIG</code>.</p><p class="simpara">To make subsequent changes to the configuration, use <code class="literal">make
  610 linux-menuconfig</code> to open the Linux configuration editor.</p></dd><dt><span class="term">
  611 Barebox
  612 </span></dt><dd>Configuration of Barebox is done in the same way as for the Linux
  613 kernel. The corresponding configuration variables are
  614 <code class="literal">BR2_TARGET_BAREBOX_USE_CUSTOM_CONFIG</code> and
  615 <code class="literal">BR2_TARGET_BAREBOX_USE_DEFCONFIG</code>. To open the configuration editor,
  616 use <code class="literal">make barebox-menuconfig</code>.</dd><dt><span class="term">
  617 U-Boot
  618 </span></dt><dd>Configuration of U-Boot (version 2015.04 or newer) is done in the same
  619 way as for the Linux kernel. The corresponding configuration variables
  620 are <code class="literal">BR2_TARGET_UBOOT_USE_CUSTOM_CONFIG</code> and
  621 <code class="literal">BR2_TARGET_UBOOT_USE_DEFCONFIG</code>. To open the configuration editor,
  622 use <code class="literal">make uboot-menuconfig</code>.</dd></dl></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_general_buildroot_usage"></a>Chapter 8. General Buildroot usage</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="make-tips"></a>8.1<span class="emphasis"><em>make</em></span> tips</h2></div></div></div><p>This is a collection of tips that help you make the most of Buildroot.</p><p><strong>Display all commands executed by make: </strong>
  623 </p><pre class="screen"> $ make V=1 &lt;target&gt;</pre><p>
  624 </p><p><strong>Display the list of boards with a defconfig: </strong>
  625 </p><pre class="screen"> $ make list-defconfigs</pre><p>
  626 </p><p><strong>Display all available targets: </strong>
  627 </p><pre class="screen"> $ make help</pre><p>
  628 </p><p>Not all targets are always available,
  629 some settings in the <code class="literal">.config</code> file may hide some targets:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  630 <code class="literal">busybox-menuconfig</code> only works when <code class="literal">busybox</code> is enabled;
  631 </li><li class="listitem">
  632 <code class="literal">linux-menuconfig</code> and <code class="literal">linux-savedefconfig</code> only work when
  633   <code class="literal">linux</code> is enabled;
  634 </li><li class="listitem">
  635 <code class="literal">uclibc-menuconfig</code> is only available when the uClibc C library is
  636   selected in the internal toolchain backend;
  637 </li><li class="listitem">
  638 <code class="literal">barebox-menuconfig</code> and <code class="literal">barebox-savedefconfig</code> only work when the
  639   <code class="literal">barebox</code> bootloader is enabled.
  640 </li><li class="listitem">
  641 <code class="literal">uboot-menuconfig</code> and <code class="literal">uboot-savedefconfig</code> only work when the
  642   <code class="literal">U-Boot</code> bootloader is enabled.
  643 </li></ul></div><p><strong>Cleaning: </strong>Explicit cleaning is required when any of the architecture or toolchain
  644 configuration options are changed.</p><p>To delete all build products (including build directories, host, staging
  645 and target trees, the images and the toolchain):</p><pre class="screen"> $ make clean</pre><p><strong>Generating the manual: </strong>The present manual sources are located in the <span class="emphasis"><em>docs/manual</em></span> directory.
  646 To generate the manual:</p><pre class="screen"> $ make manual-clean
  647  $ make manual</pre><p>The manual outputs will be generated in <span class="emphasis"><em>output/docs/manual</em></span>.</p><div class="itemizedlist"><p class="title"><strong>Notes</strong></p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  648 A few tools are required to build the documentation (see:
  649   <a class="xref" href="#requirement-optional" title="2.2. Optional packages">Section 2.2, “Optional packages”</a>).
  650 </li></ul></div><p><strong>Resetting Buildroot for a new target: </strong>To delete all build products as well as the configuration:</p><pre class="screen"> $ make distclean</pre><p><strong>Notes. </strong>If <code class="literal">ccache</code> is enabled, running <code class="literal">make clean</code> or <code class="literal">distclean</code> does
  651 not empty the compiler cache used by Buildroot. To delete it, refer
  652 to <a class="xref" href="#ccache" title="8.14.3. Using ccache in Buildroot">Section 8.14.3, “Using <code class="literal">ccache</code> in Buildroot”</a>.</p><p><strong>Dumping the internal make variables: </strong>One can dump the variables known to make, along with their values:</p><pre class="screen"> $ make -s printvars VARS='VARIABLE1 VARIABLE2'
  653  VARIABLE1=value_of_variable
  654  VARIABLE2=value_of_variable</pre><p>It is possible to tweak the output using some variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  655 <code class="literal">VARS</code> will limit the listing to variables which names match the
  656   specified make-patterns - this must be set else nothing is printed
  657 </li><li class="listitem">
  658 <code class="literal">QUOTED_VARS</code>, if set to <code class="literal">YES</code>, will single-quote the value
  659 </li><li class="listitem">
  660 <code class="literal">RAW_VARS</code>, if set to <code class="literal">YES</code>, will print the unexpanded value
  661 </li></ul></div><p>For example:</p><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES
  662  BUSYBOX_DEPENDENCIES=skeleton toolchain
  663  BUSYBOX_FINAL_ALL_DEPENDENCIES=skeleton toolchain
  664  BUSYBOX_FINAL_DEPENDENCIES=skeleton toolchain
  666  BUSYBOX_RDEPENDENCIES=ncurses util-linux</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES QUOTED_VARS=YES
  667  BUSYBOX_DEPENDENCIES='skeleton toolchain'
  668  BUSYBOX_FINAL_ALL_DEPENDENCIES='skeleton toolchain'
  669  BUSYBOX_FINAL_DEPENDENCIES='skeleton toolchain'
  671  BUSYBOX_RDEPENDENCIES='ncurses util-linux'</pre><pre class="screen"> $ make -s printvars VARS=BUSYBOX_%DEPENDENCIES RAW_VARS=YES
  672  BUSYBOX_DEPENDENCIES=skeleton toolchain
  676  BUSYBOX_RDEPENDENCIES=ncurses util-linux</pre><p>The output of quoted variables can be reused in shell scripts, for example:</p><pre class="screen"> $ eval $(make -s printvars VARS=BUSYBOX_DEPENDENCIES QUOTED_VARS=YES)
  678  skeleton toolchain</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="full-rebuild"></a>8.2. Understanding when a full rebuild is necessary</h2></div></div></div><p>Buildroot does not attempt to detect what parts of the system should
  679 be rebuilt when the system configuration is changed through <code class="literal">make
  680 menuconfig</code>, <code class="literal">make xconfig</code> or one of the other configuration
  681 tools. In some cases, Buildroot should rebuild the entire system, in
  682 some cases, only a specific subset of packages. But detecting this in
  683 a completely reliable manner is very difficult, and therefore the
  684 Buildroot developers have decided to simply not attempt to do this.</p><p>Instead, it is the responsibility of the user to know when a full
  685 rebuild is necessary. As a hint, here are a few rules of thumb that
  686 can help you understand how to work with Buildroot:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  687 When the target architecture configuration is changed, a complete
  688    rebuild is needed. Changing the architecture variant, the binary
  689    format or the floating point strategy for example has an impact on
  690    the entire system.
  691 </li><li class="listitem">
  692 When the toolchain configuration is changed, a complete rebuild
  693    generally is needed. Changing the toolchain configuration often
  694    involves changing the compiler version, the type of C library or
  695    its configuration, or some other fundamental configuration item,
  696    and these changes have an impact on the entire system.
  697 </li><li class="listitem">
  698 When an additional package is added to the configuration, a full
  699    rebuild is not necessarily needed. Buildroot will detect that this
  700    package has never been built, and will build it. However, if this
  701    package is a library that can optionally be used by packages that
  702    have already been built, Buildroot will not automatically rebuild
  703    those. Either you know which packages should be rebuilt, and you
  704    can rebuild them manually, or you should do a full rebuild. For
  705    example, let’s suppose you have built a system with the <code class="literal">ctorrent</code>
  706    package, but without <code class="literal">openssl</code>. Your system works, but you realize
  707    you would like to have SSL support in <code class="literal">ctorrent</code>, so you enable the
  708    <code class="literal">openssl</code> package in Buildroot configuration and restart the
  709    build. Buildroot will detect that <code class="literal">openssl</code> should be built and
  710    will be build it, but it will not detect that <code class="literal">ctorrent</code> should be
  711    rebuilt to benefit from <code class="literal">openssl</code> to add OpenSSL support. You will
  712    either have to do a full rebuild, or rebuild <code class="literal">ctorrent</code> itself.
  713 </li><li class="listitem">
  714 When a package is removed from the configuration, Buildroot does
  715    not do anything special. It does not remove the files installed by
  716    this package from the target root filesystem or from the toolchain
  717    <span class="emphasis"><em>sysroot</em></span>. A full rebuild is needed to get rid of this
  718    package. However, generally you don’t necessarily need this package
  719    to be removed right now: you can wait for the next lunch break to
  720    restart the build from scratch.
  721 </li><li class="listitem">
  722 When the sub-options of a package are changed, the package is not
  723    automatically rebuilt. After making such changes, rebuilding only
  724    this package is often sufficient, unless enabling the package
  725    sub-option adds some features to the package that are useful for
  726    another package which has already been built. Again, Buildroot does
  727    not track when a package should be rebuilt: once a package has been
  728    built, it is never rebuilt unless explicitly told to do so.
  729 </li><li class="listitem">
  730 When a change to the root filesystem skeleton is made, a full
  731    rebuild is needed. However, when changes to the root filesystem
  732    overlay, a post-build script or a post-image script are made,
  733    there is no need for a full rebuild: a simple <code class="literal">make</code> invocation
  734    will take the changes into account.
  735 </li><li class="listitem">
  736 When a package listed in <code class="literal">FOO_DEPENDENCIES</code> is rebuilt or removed,
  737    the package <code class="literal">foo</code> is not automatically rebuilt. For example, if a
  738    package <code class="literal">bar</code> is listed in <code class="literal">FOO_DEPENDENCIES</code> with <code class="literal">FOO_DEPENDENCIES
  739    = bar</code> and the configuration of the <code class="literal">bar</code> package is changed, the
  740    configuration change would not result in a rebuild of package <code class="literal">foo</code>
  741    automatically. In this scenario, you may need to either rebuild any
  742    packages in your build which reference <code class="literal">bar</code> in their <code class="literal">DEPENDENCIES</code>,
  743    or perform a full rebuild to ensure any <code class="literal">bar</code> dependent packages are
  744    up to date.
  745 </li></ul></div><p>Generally speaking, when you’re facing a build error and you’re unsure
  746 of the potential consequences of the configuration changes you’ve
  747 made, do a full rebuild. If you get the same build error, then you are
  748 sure that the error is not related to partial rebuilds of packages,
  749 and if this error occurs with packages from the official Buildroot, do
  750 not hesitate to report the problem! As your experience with Buildroot
  751 progresses, you will progressively learn when a full rebuild is really
  752 necessary, and you will save more and more time.</p><p>For reference, a full rebuild is achieved by running:</p><pre class="screen">$ make clean all</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rebuild-pkg"></a>8.3. Understanding how to rebuild packages</h2></div></div></div><p>One of the most common questions asked by Buildroot users is how to
  753 rebuild a given package or how to remove a package without rebuilding
  754 everything from scratch.</p><p>Removing a package is unsupported by Buildroot without
  755 rebuilding from scratch. This is because Buildroot doesn’t keep track
  756 of which package installs what files in the <code class="literal">output/staging</code> and
  757 <code class="literal">output/target</code> directories, or which package would be compiled differently
  758 depending on the availability of another package.</p><p>The easiest way to rebuild a single package from scratch is to remove
  759 its build directory in <code class="literal">output/build</code>. Buildroot will then re-extract,
  760 re-configure, re-compile and re-install this package from scratch. You
  761 can ask buildroot to do this with the <code class="literal">make &lt;package&gt;-dirclean</code> command.</p><p>On the other hand, if you only want to restart the build process of a
  762 package from its compilation step, you can run <code class="literal">make &lt;package&gt;-rebuild</code>. It
  763 will restart the compilation and installation of the package, but not from
  764 scratch: it basically re-executes <code class="literal">make</code> and <code class="literal">make install</code> inside the package,
  765 so it will only rebuild files that changed.</p><p>If you want to restart the build process of a package from its configuration
  766 step, you can run <code class="literal">make &lt;package&gt;-reconfigure</code>. It will restart the
  767 configuration, compilation and installation of the package.</p><p>While <code class="literal">&lt;package&gt;-rebuild</code> implies <code class="literal">&lt;package&gt;-reinstall</code> and
  768 <code class="literal">&lt;package&gt;-reconfigure</code> implies <code class="literal">&lt;package&gt;-rebuild</code>, these targets as well
  769 as <code class="literal">&lt;package&gt;</code> only act on the said package, and do not trigger re-creating
  770 the root filesystem image. If re-creating the root filesystem in necessary,
  771 one should in addition run <code class="literal">make</code> or <code class="literal">make all</code>.</p><p>Internally, Buildroot creates so-called <span class="emphasis"><em>stamp files</em></span> to keep track of
  772 which build steps have been completed for each package. They are
  773 stored in the package build directory,
  774 <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;/</code> and are named
  775 <code class="literal">.stamp_&lt;step-name&gt;</code>. The commands detailed above simply manipulate
  776 these stamp files to force Buildroot to restart a specific set of
  777 steps of a package build process.</p><p>Further details about package special make targets are explained in
  778 <a class="xref" href="#pkg-build-steps" title="8.14.5. Package-specific make targets">Section 8.14.5, “Package-specific <span class="emphasis"><em>make</em></span> targets”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_offline_builds"></a>8.4. Offline builds</h2></div></div></div><p>If you intend to do an offline build and just want to download
  779 all sources that you previously selected in the configurator
  780 (<span class="emphasis"><em>menuconfig</em></span>, <span class="emphasis"><em>nconfig</em></span>, <span class="emphasis"><em>xconfig</em></span> or <span class="emphasis"><em>gconfig</em></span>), then issue:</p><pre class="screen"> $ make source</pre><p>You can now disconnect or copy the content of your <code class="literal">dl</code>
  781 directory to the build-host.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_building_out_of_tree"></a>8.5. Building out-of-tree</h2></div></div></div><p>As default, everything built by Buildroot is stored in the directory
  782 <code class="literal">output</code> in the Buildroot tree.</p><p>Buildroot also supports building out of tree with a syntax similar to
  783 the Linux kernel. To use it, add <code class="literal">O=&lt;directory&gt;</code> to the make command
  784 line:</p><pre class="screen"> $ make O=/tmp/build</pre><p>Or:</p><pre class="screen"> $ cd /tmp/build; make O=$PWD -C path/to/buildroot</pre><p>All the output files will be located under <code class="literal">/tmp/build</code>. If the <code class="literal">O</code>
  785 path does not exist, Buildroot will create it.</p><p><span class="strong"><strong>Note:</strong></span> the <code class="literal">O</code> path can be either an absolute or a relative path, but if it’s
  786 passed as a relative path, it is important to note that it is interpreted
  787 relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> the current working
  788 directory.</p><p>When using out-of-tree builds, the Buildroot <code class="literal">.config</code> and temporary
  789 files are also stored in the output directory. This means that you can
  790 safely run multiple builds in parallel using the same source tree as
  791 long as they use unique output directories.</p><p>For ease of use, Buildroot generates a Makefile wrapper in the output
  792 directory - so after the first run, you no longer need to pass <code class="literal">O=&lt;&gt;</code>
  793 and <code class="literal">-C &lt;&gt;</code>, simply run (in the output directory):</p><pre class="screen"> $ make &lt;target&gt;</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="env-vars"></a>8.6. Environment variables</h2></div></div></div><p>Buildroot also honors some environment variables, when they are passed
  794 to <code class="literal">make</code> or set in the environment:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  795 <code class="literal">HOSTCXX</code>, the host C++ compiler to use
  796 </li><li class="listitem">
  797 <code class="literal">HOSTCC</code>, the host C compiler to use
  798 </li><li class="listitem">
  799 <code class="literal">UCLIBC_CONFIG_FILE=&lt;path/to/.config&gt;</code>, path to
  800   the uClibc configuration file, used to compile uClibc, if an
  801   internal toolchain is being built.
  803   Note that the uClibc configuration file can also be set from the
  804   configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
  805   is the recommended way of setting it.
  807 </li><li class="listitem">
  808 <code class="literal">BUSYBOX_CONFIG_FILE=&lt;path/to/.config&gt;</code>, path to
  809   the BusyBox configuration file.
  811   Note that the BusyBox configuration file can also be set from the
  812   configuration interface, so through the Buildroot <code class="literal">.config</code> file; this
  813   is the recommended way of setting it.
  815 </li><li class="listitem">
  816 <code class="literal">BR2_CCACHE_DIR</code> to override the directory where
  817   Buildroot stores the cached files when using ccache.
  819 </li><li class="listitem">
  820 <code class="literal">BR2_DL_DIR</code> to override the directory in which
  821   Buildroot stores/retrieves downloaded files.
  823   Note that the Buildroot download directory can also be set from the
  824   configuration interface, so through the Buildroot <code class="literal">.config</code> file. See
  825   <a class="xref" href="#download-location" title="8.14.4. Location of downloaded packages">Section 8.14.4, “Location of downloaded packages”</a> for more details on how you can set the download
  826   directory.
  827 </li><li class="listitem">
  828 <code class="literal">BR2_GRAPH_ALT</code>, if set and non-empty, to use an alternate color-scheme in
  829   build-time graphs
  830 </li><li class="listitem">
  831 <code class="literal">BR2_GRAPH_OUT</code> to set the filetype of generated graphs, either <code class="literal">pdf</code> (the
  832   default), or <code class="literal">png</code>.
  833 </li><li class="listitem">
  834 <code class="literal">BR2_GRAPH_DEPS_OPTS</code> to pass extra options to the dependency graph; see
  835   <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a> for the accepted options
  836 </li><li class="listitem">
  837 <code class="literal">BR2_GRAPH_DOT_OPTS</code> is passed verbatim as options to the <code class="literal">dot</code> utility to
  838   draw the dependency graph.
  839 </li><li class="listitem">
  840 <code class="literal">BR2_GRAPH_SIZE_OPTS</code> to pass extra options to the size graph; see
  841   <a class="xref" href="#graph-size" title="8.11. Graphing the filesystem size contribution of packages">Section 8.11, “Graphing the filesystem size contribution of packages”</a> for the acepted options
  842 </li></ul></div><p>An example that uses config files located in the toplevel directory and
  843 in your $HOME:</p><pre class="screen"> $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config</pre><p>If you want to use a compiler other than the default <code class="literal">gcc</code>
  844 or <code class="literal">g</code>++ for building helper-binaries on your host, then do</p><pre class="screen"> $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_dealing_efficiently_with_filesystem_images"></a>8.7. Dealing efficiently with filesystem images</h2></div></div></div><p>Filesystem images can get pretty big, depending on the filesystem you choose,
  845 the number of packages, whether you provisioned free space… Yet, some
  846 locations in the filesystems images may just be <span class="emphasis"><em>empty</em></span> (e.g. a long run of
  847 <span class="emphasis"><em>zeroes</em></span>); such a file is called a <span class="emphasis"><em>sparse</em></span> file.</p><p>Most tools can handle sparse files efficiently, and will only store or write
  848 those parts of a sparse file that are not empty.</p><p>For example:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
  849 <code class="literal">tar</code> accepts the <code class="literal">-S</code> option to tell it to only store non-zero blocks
  850   of sparse files:
  851 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  852 <code class="literal">tar cf archive.tar -S [files…]</code> will efficiently store sparse files
  853    in a tarball
  854 </li><li class="listitem">
  855 <code class="literal">tar xf archive.tar -S</code> will efficiently store sparse files extracted
  856    from a tarball
  857 </li></ul></div></li><li class="listitem"><p class="simpara">
  858 <code class="literal">cp</code> accepts the <code class="literal">--sparse=WHEN</code> option (<code class="literal">WHEN</code> is one of <code class="literal">auto</code>,
  859   <code class="literal">never</code> or <code class="literal">always</code>):
  860 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
  861 <code class="literal">cp --sparse=always source.file dest.file</code> will make <code class="literal">dest.file</code> a
  862    sparse file if <code class="literal">source.file</code> has long runs of zeroes
  863 </li></ul></div></li></ul></div><p>Other tools may have similar options. Please consult their respective man
  864 pages.</p><p>You can use sparse files if you need to store the filesystem images (e.g.
  865 to transfer from one machine to another), or if you need to send them (e.g.
  866 to the Q&amp;A team).</p><p>Note however that flashing a filesystem image to a device while using the
  867 sparse mode of <code class="literal">dd</code> may result in a broken filesystem (e.g. the block bitmap
  868 of an ext2 filesystem may be corrupted; or, if you have sparse files in
  869 your filesystem, those parts may not be all-zeroes when read back). You
  870 should only use sparse files when handling files on the build machine, not
  871 when transferring them to an actual device that will be used on the target.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_details_about_packages"></a>8.8. Details about packages</h2></div></div></div><p><a id="package-details"></a>Buildroot can produce a JSON blurb that describes the set of enabled
  872 packages in the current configuration, together with their
  873 dependencies, licenses and other metadata. This JSON blurb is produced
  874 by using the <code class="literal">show-info</code> make target:</p><pre class="screen">make show-info</pre><p>Buildroot can also produce details about packages as HTML and JSON
  875 output using the <code class="literal">pkg-stats</code> make target. Amongst other things, these
  876 details include whether known CVEs (security vulnerabilities) affect
  877 the packages in your current configuration. It also shows if there is
  878 a newer upstream version for those packages.</p><pre class="screen">make pkg-stats</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_graphing_the_dependencies_between_packages"></a>8.9. Graphing the dependencies between packages</h2></div></div></div><p><a id="graph-depends"></a>One of Buildroot’s jobs is to know the dependencies between packages,
  879 and make sure they are built in the right order. These dependencies
  880 can sometimes be quite complicated, and for a given system, it is
  881 often not easy to understand why such or such package was brought into
  882 the build by Buildroot.</p><p>In order to help understanding the dependencies, and therefore better
  883 understand what is the role of the different components in your
  884 embedded Linux system, Buildroot is capable of generating dependency
  885 graphs.</p><p>To generate a dependency graph of the full system you have compiled,
  886 simply run:</p><pre class="screen">make graph-depends</pre><p>You will find the generated graph in
  887 <code class="literal">output/graphs/graph-depends.pdf</code>.</p><p>If your system is quite large, the dependency graph may be too complex
  888 and difficult to read. It is therefore possible to generate the
  889 dependency graph just for a given package:</p><pre class="screen">make &lt;pkg&gt;-graph-depends</pre><p>You will find the generated graph in
  890 <code class="literal">output/graph/&lt;pkg&gt;-graph-depends.pdf</code>.</p><p>Note that the dependency graphs are generated using the <code class="literal">dot</code> tool
  891 from the <span class="emphasis"><em>Graphviz</em></span> project, which you must have installed on your
  892 system to use this feature. In most distributions, it is available as
  893 the <code class="literal">graphviz</code> package.</p><p>By default, the dependency graphs are generated in the PDF
  894 format. However, by passing the <code class="literal">BR2_GRAPH_OUT</code> environment variable, you
  895 can switch to other output formats, such as PNG, PostScript or
  896 SVG. All formats supported by the <code class="literal">-T</code> option of the <code class="literal">dot</code> tool are
  897 supported.</p><pre class="screen">BR2_GRAPH_OUT=svg make graph-depends</pre><p>The <code class="literal">graph-depends</code> behaviour can be controlled by setting options in the
  898 <code class="literal">BR2_GRAPH_DEPS_OPTS</code> environment variable. The accepted options are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  899 <code class="literal">--depth N</code>, <code class="literal">-d N</code>, to limit the dependency depth to <code class="literal">N</code> levels. The
  900   default, <code class="literal">0</code>, means no limit.
  901 </li><li class="listitem">
  902 <code class="literal">--stop-on PKG</code>, <code class="literal">-s PKG</code>, to stop the graph on the package <code class="literal">PKG</code>.
  903   <code class="literal">PKG</code> can be an actual package name, a glob, the keyword <span class="emphasis"><em>virtual</em></span>
  904   (to stop on virtual packages), or the keyword <span class="emphasis"><em>host</em></span> (to stop on
  905   host packages). The package is still present on the graph, but its
  906   dependencies are not.
  907 </li><li class="listitem">
  908 <code class="literal">--exclude PKG</code>, <code class="literal">-x PKG</code>, like <code class="literal">--stop-on</code>, but also omits <code class="literal">PKG</code> from
  909   the graph.
  910 </li><li class="listitem">
  911 <code class="literal">--transitive</code>, <code class="literal">--no-transitive</code>, to draw (or not) the transitive
  912   dependencies. The default is to not draw transitive dependencies.
  913 </li><li class="listitem">
  914 <code class="literal">--colors R,T,H</code>, the comma-separated list of colors to draw the
  915   root package (<code class="literal">R</code>), the target packages (<code class="literal">T</code>) and the host packages
  916   (<code class="literal">H</code>). Defaults to: <code class="literal">lightblue,grey,gainsboro</code>
  917 </li></ul></div><pre class="screen">BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_graphing_the_build_duration"></a>8.10. Graphing the build duration</h2></div></div></div><p><a id="graph-duration"></a>When the build of a system takes a long time, it is sometimes useful
  918 to be able to understand which packages are the longest to build, to
  919 see if anything can be done to speed up the build. In order to help
  920 such build time analysis, Buildroot collects the build time of each
  921 step of each package, and allows to generate graphs from this data.</p><p>To generate the build time graph after a build, run:</p><pre class="screen">make graph-build</pre><p>This will generate a set of files in <code class="literal">output/graphs</code> :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  922 <code class="literal">build.hist-build.pdf</code>, a histogram of the build time for each
  923   package, ordered in the build order.
  924 </li><li class="listitem">
  925 <code class="literal">build.hist-duration.pdf</code>, a histogram of the build time for each
  926   package, ordered by duration (longest first)
  927 </li><li class="listitem">
  928 <code class="literal">build.hist-name.pdf</code>, a histogram of the build time for each
  929   package, order by package name.
  930 </li><li class="listitem">
  931 <code class="literal">build.pie-packages.pdf</code>, a pie chart of the build time per package
  932 </li><li class="listitem">
  933 <code class="literal">build.pie-steps.pdf</code>, a pie chart of the global time spent in each
  934   step of the packages build process.
  935 </li></ul></div><p>This <code class="literal">graph-build</code> target requires the Python Matplotlib and Numpy
  936 libraries to be installed (<code class="literal">python-matplotlib</code> and <code class="literal">python-numpy</code> on
  937 most distributions), and also the <code class="literal">argparse</code> module if you’re using a
  938 Python version older than 2.7 (<code class="literal">python-argparse</code> on most
  939 distributions).</p><p>By default, the output format for the graph is PDF, but a different
  940 format can be selected using the <code class="literal">BR2_GRAPH_OUT</code> environment variable. The
  941 only other format supported is PNG:</p><pre class="screen">BR2_GRAPH_OUT=png make graph-build</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="graph-size"></a>8.11. Graphing the filesystem size contribution of packages</h2></div></div></div><p>When your target system grows, it is sometimes useful to understand
  942 how much each Buildroot package is contributing to the overall root
  943 filesystem size. To help with such an analysis, Buildroot collects
  944 data about files installed by each package and using this data,
  945 generates a graph and CSV files detailing the size contribution of
  946 the different packages.</p><p>To generate these data after a build, run:</p><pre class="screen">make graph-size</pre><p>This will generate:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  947 <code class="literal">output/graphs/graph-size.pdf</code>, a pie chart of the contribution of
  948   each package to the overall root filesystem size
  949 </li><li class="listitem">
  950 <code class="literal">output/graphs/package-size-stats.csv</code>, a CSV file giving the size
  951   contribution of each package to the overall root filesystem size
  952 </li><li class="listitem">
  953 <code class="literal">output/graphs/file-size-stats.csv</code>, a CSV file giving the size
  954   contribution of each installed file to the package it belongs, and
  955   to the overall filesystem size.
  956 </li></ul></div><p>This <code class="literal">graph-size</code> target requires the Python Matplotlib library to be
  957 installed (<code class="literal">python-matplotlib</code> on most distributions), and also the
  958 <code class="literal">argparse</code> module if you’re using a Python version older than 2.7
  959 (<code class="literal">python-argparse</code> on most distributions).</p><p>Just like for the duration graph, a <code class="literal">BR2_GRAPH_OUT</code> environment variable
  960 is supported to adjust the output file format. See <a class="xref" href="#graph-depends">Section 8.9, “Graphing the dependencies between packages”</a>
  961 for details about this environment variable.</p><p>Additionally, one may set the environment variable <code class="literal">BR2_GRAPH_SIZE_OPTS</code>
  962 to further control the generated graph. Accepted options are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  963 <code class="literal">--size-limit X</code>, <code class="literal">-l X</code>, will group all packages which individual
  964   contribution is below <code class="literal">X</code> percent, to a single entry labelled <span class="emphasis"><em>Others</em></span>
  965   in the graph. By default, <code class="literal">X=0.01</code>, which means packages each
  966   contributing less than 1% are grouped under <span class="emphasis"><em>Others</em></span>. Accepted values
  967   are in the range <code class="literal">[0.0..1.0]</code>.
  968 </li><li class="listitem">
  969 <code class="literal">--iec</code>, <code class="literal">--binary</code>, <code class="literal">--si</code>, <code class="literal">--decimal</code>, to use IEC (binary, powers
  970   of 1024) or SI (decimal, powers of 1000; the default) prefixes.
  971 </li><li class="listitem">
  972 <code class="literal">--biggest-first</code>, to sort packages in decreasing size order, rather
  973   than in increasing size order.
  974 </li></ul></div><p><strong>Note. </strong>The collected filesystem size data is only meaningful after a complete
  975 clean rebuild. Be sure to run <code class="literal">make clean all</code> before using <code class="literal">make
  976 graph-size</code>.</p><p>To compare the root filesystem size of two different Buildroot compilations,
  977 for example after adjusting the configuration or when switching to another
  978 Buildroot release, use the <code class="literal">size-stats-compare</code> script. It takes two
  979 <code class="literal">file-size-stats.csv</code> files (produced by <code class="literal">make graph-size</code>) as input.
  980 Refer to the help text of this script for more details:</p><pre class="screen">utils/size-stats-compare -h</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="top-level-parallel-build"></a>8.12. Top-level parallel build</h2></div></div></div><p><strong>Note. </strong>This section deals with a very experimental feature, which is known to
  981 break even in some non-unusual situations. Use at your own risk.</p><p>Buildroot has always been capable of using parallel build on a per
  982 package basis: each package is built by Buildroot using <code class="literal">make -jN</code> (or
  983 the equivalent invocation for non-make-based build systems). The level
  984 of parallelism is by default number of CPUs + 1, but it can be
  985 adjusted using the <code class="literal">BR2_JLEVEL</code> configuration option.</p><p>Until 2020.02, Buildroot was however building packages in a serial
  986 fashion: each package was built one after the other, without
  987 parallelization of the build between packages. As of 2020.02,
  988 Buildroot has experimental support for <span class="strong"><strong>top-level parallel build</strong></span>,
  989 which allows some signicant build time savings by building packages
  990 that have no dependency relationship in parallel. This feature is
  991 however marked as experimental and is known not to work in some cases.</p><p>In order to use top-level parallel build, one must:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
  992 Enable the option <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> in the Buildroot
  993 configuration
  994 </li><li class="listitem">
  995 Use <code class="literal">make -jN</code> when starting the Buildroot build
  996 </li></ol></div><p>Internally, the <code class="literal">BR2_PER_PACKAGE_DIRECTORIES</code> will enable a mechanism
  997 called <span class="strong"><strong>per-package directories</strong></span>, which will have the following
  998 effects:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
  999 Instead of a global <span class="emphasis"><em>target</em></span> directory and a global <span class="emphasis"><em>host</em></span> directory
 1000   common to all packages, per-package <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
 1001   will be used, in <code class="literal">$(O)/per-package/&lt;pkg&gt;/target/</code> and
 1002   <code class="literal">$(O)/per-package/&lt;pkg&gt;/host/</code> respectively. Those folders will be
 1003   populated from the corresponding folders of the package dependencies
 1004   at the beginning of <code class="literal">&lt;pkg&gt;</code> build. The compiler and all other tools
 1005   will therefore only be able to see and access files installed by
 1006   dependencies explicitly listed by <code class="literal">&lt;pkg&gt;</code>.
 1007 </li><li class="listitem">
 1008 At the end of the build, the global <span class="emphasis"><em>target</em></span> and <span class="emphasis"><em>host</em></span> directories
 1009   will be populated, located in <code class="literal">$(O)/target</code> and <code class="literal">$(O)/host</code>
 1010   respectively. This means that during the build, those folders will
 1011   be empty and it’s only at the very end of the build that they will
 1012   be populated.
 1013 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_integration_with_eclipse"></a>8.13. Integration with Eclipse</h2></div></div></div><p>While a part of the embedded Linux developers like classical text
 1014 editors like Vim or Emacs, and command-line based interfaces, a number
 1015 of other embedded Linux developers like richer graphical interfaces to
 1016 do their development work. Eclipse being one of the most popular
 1017 Integrated Development Environment, Buildroot integrates with Eclipse
 1018 in order to ease the development work of Eclipse users.</p><p>Our integration with Eclipse simplifies the compilation, remote
 1019 execution and remote debugging of applications and libraries that are
 1020 built on top of a Buildroot system. It does not integrate the
 1021 Buildroot configuration and build processes themselves with
 1022 Eclipse. Therefore, the typical usage model of our Eclipse integration
 1023 would be:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1024 Configure your Buildroot system with <code class="literal">make menuconfig</code>, <code class="literal">make
 1025   xconfig</code> or any other configuration interface provided with
 1026   Buildroot.
 1027 </li><li class="listitem">
 1028 Build your Buildroot system by running <code class="literal">make</code>.
 1029 </li><li class="listitem">
 1030 Start Eclipse to develop, execute and debug your own custom
 1031   applications and libraries, that will rely on the libraries built
 1032   and installed by Buildroot.
 1033 </li></ul></div><p>The Buildroot Eclipse integration installation process and usage is
 1034 described in detail at
 1035 <a class="ulink" href="https://github.com/mbats/eclipse-buildroot-bundle/wiki" target="_top">https://github.com/mbats/eclipse-buildroot-bundle/wiki</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_advanced_usage"></a>8.14. Advanced usage</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_the_generated_toolchain_outside_buildroot"></a>8.14.1. Using the generated toolchain outside Buildroot</h3></div></div></div><p>You may want to compile, for your target, your own programs or other
 1036 software that are not packaged in Buildroot. In order to do this you
 1037 can use the toolchain that was generated by Buildroot.</p><p>The toolchain generated by Buildroot is located by default in
 1038 <code class="literal">output/host/</code>. The simplest way to use it is to add
 1039 <code class="literal">output/host/bin/</code> to your PATH environment variable and then to
 1040 use <code class="literal">ARCH-linux-gcc</code>, <code class="literal">ARCH-linux-objdump</code>, <code class="literal">ARCH-linux-ld</code>, etc.</p><p>Alternatively, Buildroot can also export the toolchain and the development
 1041 files of all selected packages, as an SDK, by running the command
 1042 <code class="literal">make sdk</code>. This generates a tarball of the content of the host directory
 1043 <code class="literal">output/host/</code>, named <code class="literal">&lt;TARGET-TUPLE&gt;_sdk-buildroot.tar.gz</code> (which can be
 1044 overriden by setting the environment variable <code class="literal">BR2_SDK_PREFIX</code>) and
 1045 located in the output directory <code class="literal">output/images/</code>.</p><p>This tarball can then be distributed to application developers, when
 1046 they want to develop their applications that are not (yet) packaged as
 1047 a Buildroot package.</p><p>Upon extracting the SDK tarball, the user must run the script
 1048 <code class="literal">relocate-sdk.sh</code> (located at the top directory of the SDK), to make
 1049 sure all paths are updated with the new location.</p><p>Alternatively, if you just want to prepare the SDK without generating
 1050 the tarball (e.g. because you will just be moving the <code class="literal">host</code> directory,
 1051 or will be generating the tarball on your own), Buildroot also allows
 1052 you to just prepare the SDK with <code class="literal">make prepare-sdk</code> without actually
 1053 generating a tarball.</p><p>For your convenience, by selecting the option
 1054 <code class="literal">BR2_PACKAGE_HOST_ENVIRONMENT_SETUP</code>, you can get a
 1055 <code class="literal">environment-setup</code> script installed in <code class="literal">output/host/</code> and therefore
 1056 in your SDK.  This script can be sourced with
 1057 <code class="literal">. your/sdk/path/environment-setup</code> to export a number of environment
 1058 variables that will help cross-compile your projects using the
 1059 Buildroot SDK: the <code class="literal">PATH</code> will contain the SDK binaries, standard
 1060 <span class="emphasis"><em>autotools</em></span> variables will be defined with the appropriate values, and
 1061 <code class="literal">CONFIGURE_FLAGS</code> will contain basic <code class="literal">./configure</code> options to
 1062 cross-compile <span class="emphasis"><em>autotools</em></span> projects. It also provides some useful
 1063 commands. Note however that once this script is sourced, the
 1064 environment is setup only for cross-compilation, and no longer for
 1065 native compilation.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_literal_gdb_literal_in_buildroot"></a>8.14.2. Using <code class="literal">gdb</code> in Buildroot</h3></div></div></div><p>Buildroot allows to do cross-debugging, where the debugger runs on the
 1066 build machine and communicates with <code class="literal">gdbserver</code> on the target to
 1067 control the execution of the program.</p><p>To achieve this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1068 If you are using an <span class="emphasis"><em>internal toolchain</em></span> (built by Buildroot), you
 1069   must enable <code class="literal">BR2_PACKAGE_HOST_GDB</code>, <code class="literal">BR2_PACKAGE_GDB</code> and
 1070   <code class="literal">BR2_PACKAGE_GDB_SERVER</code>. This ensures that both the cross gdb and
 1071   gdbserver get built, and that gdbserver gets installed to your target.
 1072 </li><li class="listitem">
 1073 If you are using an <span class="emphasis"><em>external toolchain</em></span>, you should enable
 1074   <code class="literal">BR2_TOOLCHAIN_EXTERNAL_GDB_SERVER_COPY</code>, which will copy the
 1075   gdbserver included with the external toolchain to the target. If your
 1076   external toolchain does not have a cross gdb or gdbserver, it is also
 1077   possible to let Buildroot build them, by enabling the same options as
 1078   for the <span class="emphasis"><em>internal toolchain backend</em></span>.
 1079 </li></ul></div><p>Now, to start debugging a program called <code class="literal">foo</code>, you should run on the
 1080 target:</p><pre class="screen">gdbserver :2345 foo</pre><p>This will cause <code class="literal">gdbserver</code> to listen on TCP port 2345 for a connection
 1081 from the cross gdb.</p><p>Then, on the host, you should start the cross gdb using the following
 1082 command line:</p><pre class="screen">&lt;buildroot&gt;/output/host/bin/&lt;tuple&gt;-gdb -x &lt;buildroot&gt;/output/staging/usr/share/buildroot/gdbinit foo</pre><p>Of course, <code class="literal">foo</code> must be available in the current directory, built
 1083 with debugging symbols. Typically you start this command from the
 1084 directory where <code class="literal">foo</code> is built (and not from <code class="literal">output/target/</code> as the
 1085 binaries in that directory are stripped).</p><p>The <code class="literal">&lt;buildroot&gt;/output/staging/usr/share/buildroot/gdbinit</code> file will tell the
 1086 cross gdb where to find the libraries of the target.</p><p>Finally, to connect to the target from the cross gdb:</p><pre class="screen">(gdb) target remote &lt;target ip address&gt;:2345</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ccache"></a>8.14.3. Using <code class="literal">ccache</code> in Buildroot</h3></div></div></div><p><a class="ulink" href="http://ccache.samba.org" target="_top">ccache</a> is a compiler cache. It stores the
 1087 object files resulting from each compilation process, and is able to
 1088 skip future compilation of the same source file (with same compiler
 1089 and same arguments) by using the pre-existing object files. When doing
 1090 almost identical builds from scratch a number of times, it can nicely
 1091 speed up the build process.</p><p><code class="literal">ccache</code> support is integrated in Buildroot. You just have to enable
 1092 <code class="literal">Enable compiler cache</code> in <code class="literal">Build options</code>. This will automatically
 1093 build <code class="literal">ccache</code> and use it for every host and target compilation.</p><p>The cache is located in <code class="literal">$HOME/.buildroot-ccache</code>. It is stored
 1094 outside of Buildroot output directory so that it can be shared by
 1095 separate Buildroot builds. If you want to get rid of the cache, simply
 1096 remove this directory.</p><p>You can get statistics on the cache (its size, number of hits,
 1097 misses, etc.) by running <code class="literal">make ccache-stats</code>.</p><p>The make target <code class="literal">ccache-options</code> and the <code class="literal">CCACHE_OPTIONS</code> variable
 1098 provide more generic access to the ccache. For example</p><pre class="screen"># set cache limit size
 1099 make CCACHE_OPTIONS="--max-size=5G" ccache-options
 1101 # zero statistics counters
 1102 make CCACHE_OPTIONS="--zero-stats" ccache-options</pre><p><code class="literal">ccache</code> makes a hash of the source files and of the compiler options.
 1103 If a compiler option is different, the cached object file will not be
 1104 used. Many compiler options, however, contain an absolute path to the
 1105 staging directory. Because of this, building in a different output
 1106 directory would lead to many cache misses.</p><p>To avoid this issue, buildroot has the <code class="literal">Use relative paths</code> option
 1107 (<code class="literal">BR2_CCACHE_USE_BASEDIR</code>). This will rewrite all absolute paths that
 1108 point inside the output directory into relative paths. Thus, changing
 1109 the output directory no longer leads to cache misses.</p><p>A disadvantage of the relative paths is that they also end up to be
 1110 relative paths in the object file. Therefore, for example, the debugger
 1111 will no longer find the file, unless you cd to the output directory
 1112 first.</p><p>See <a class="ulink" href="https://ccache.samba.org/manual.html#_compiling_in_different_directories" target="_top">the
 1113 ccache manual’s section on "Compiling in different directories"</a> for
 1114 more details about this rewriting of absolute paths.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="download-location"></a>8.14.4. Location of downloaded packages</h3></div></div></div><p>The various tarballs that are downloaded by Buildroot are all stored
 1115 in <code class="literal">BR2_DL_DIR</code>, which by default is the <code class="literal">dl</code> directory. If you want
 1116 to keep a complete version of Buildroot which is known to be working
 1117 with the associated tarballs, you can make a copy of this directory.
 1118 This will allow you to regenerate the toolchain and the target
 1119 filesystem with exactly the same versions.</p><p>If you maintain several Buildroot trees, it might be better to have a
 1120 shared download location. This can be achieved by pointing the
 1121 <code class="literal">BR2_DL_DIR</code> environment variable to a directory. If this is
 1122 set, then the value of <code class="literal">BR2_DL_DIR</code> in the Buildroot configuration is
 1123 overridden. The following line should be added to <code class="literal">&lt;~/.bashrc&gt;</code>.</p><pre class="screen"> export BR2_DL_DIR=&lt;shared download location&gt;</pre><p>The download location can also be set in the <code class="literal">.config</code> file, with the
 1124 <code class="literal">BR2_DL_DIR</code> option. Unlike most options in the .config file, this value
 1125 is overridden by the <code class="literal">BR2_DL_DIR</code> environment variable.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="pkg-build-steps"></a>8.14.5. Package-specific <span class="emphasis"><em>make</em></span> targets</h3></div></div></div><p>Running <code class="literal">make &lt;package&gt;</code> builds and installs that particular package
 1126 and its dependencies.</p><p>For packages relying on the Buildroot infrastructure, there are
 1127 numerous special make targets that can be called independently like
 1128 this:</p><pre class="screen">make &lt;package&gt;-&lt;target&gt;</pre><p>The package build targets are (in the order they are executed):</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; " width="90%"><colgroup><col class="col_1" /><col class="col_2" /></colgroup><thead><tr><th style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"> command/target    </th><th style="border-bottom: 1px solid #527bbd; " align="left" valign="top"> Description</th></tr></thead><tbody><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">source</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Fetch the source (download the tarball, clone
 1129 the source repository, etc)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Build and install all dependencies required to
 1130 build the package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">extract</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Put the source in the package build directory
 1131 (extract the tarball, copy the source, etc)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">patch</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Apply the patches, if any</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">configure</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Run the configure commands, if any</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">build</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Run the compilation commands</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install-staging</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the installation of the package in the
 1132 staging directory, if necessary</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install-target</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the installation of the package in the
 1133 target directory, if necessary</p></td></tr><tr><td style="border-right: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">install</code></p></td><td style="" align="left" valign="top"><p><span class="strong"><strong>target package:</strong></span> Run the 2 previous installation commands</p>
 1134 <p><span class="strong"><strong>host package:</strong></span> Run the installation of the package in the host
 1135 directory</p></td></tr></tbody></table></div><p>Additionally, there are some other useful make targets:</p><div class="informaltable"><table class="informaltable" cellpadding="4px" style="border-collapse: collapse;border-top: 3px solid #527bbd; border-bottom: 3px solid #527bbd; border-left: 3px solid #527bbd; border-right: 3px solid #527bbd; " width="90%"><colgroup><col class="col_1" /><col class="col_2" /></colgroup><thead><tr><th style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"> command/target    </th><th style="border-bottom: 1px solid #527bbd; " align="left" valign="top"> Description</th></tr></thead><tbody><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Displays the first-order dependencies required to build the
 1136 package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-recursive-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Recursively displays the dependencies
 1137   required to build the package</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Displays the first-order reverse dependencies of
 1138   the package (i.e packages that directly depend on it)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">show-recursive-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Recursively displays the reverse
 1139   dependencies of the package (i.e the packages that depend on it,
 1140   directly or indirectly)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">graph-depends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Generate a dependency graph of the package, in the
 1141 context of the current Buildroot configuration. See
 1142 <a class="link" href="#graph-depends">this section</a> for more details about dependency
 1143 graphs.</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">graph-rdepends</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Generate a graph of this package reverse
 1144   dependencies (i.e the packages that depend on it, directly or
 1145   indirectly)</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">dirclean</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Remove the whole package build directory</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">reinstall</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Re-run the install commands</p></td></tr><tr><td style="border-right: 1px solid #527bbd; border-bottom: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">rebuild</code></p></td><td style="border-bottom: 1px solid #527bbd; " align="left" valign="top"><p>Re-run the compilation commands - this only makes
 1146 sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a file
 1147 directly in the build directory</p></td></tr><tr><td style="border-right: 1px solid #527bbd; " align="center" valign="top"><p><code class="literal">reconfigure</code></p></td><td style="" align="left" valign="top"><p>Re-run the configure commands, then rebuild - this only
 1148 makes sense when using the <code class="literal">OVERRIDE_SRCDIR</code> feature or when you modified a
 1149 file directly in the build directory</p></td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_using_buildroot_during_development"></a>8.14.6. Using Buildroot during development</h3></div></div></div><p>The normal operation of Buildroot is to download a tarball, extract
 1150 it, configure, compile and install the software component found inside
 1151 this tarball. The source code is extracted in
 1152 <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;</code>, which is a temporary directory:
 1153 whenever <code class="literal">make clean</code> is used, this directory is entirely removed, and
 1154 re-created at the next <code class="literal">make</code> invocation. Even when a Git or
 1155 Subversion repository is used as the input for the package source
 1156 code, Buildroot creates a tarball out of it, and then behaves as it
 1157 normally does with tarballs.</p><p>This behavior is well-suited when Buildroot is used mainly as an
 1158 integration tool, to build and integrate all the components of an
 1159 embedded Linux system. However, if one uses Buildroot during the
 1160 development of certain components of the system, this behavior is not
 1161 very convenient: one would instead like to make a small change to the
 1162 source code of one package, and be able to quickly rebuild the system
 1163 with Buildroot.</p><p>Making changes directly in <code class="literal">output/build/&lt;package&gt;-&lt;version&gt;</code> is not
 1164 an appropriate solution, because this directory is removed on <code class="literal">make
 1165 clean</code>.</p><p>Therefore, Buildroot provides a specific mechanism for this use case:
 1166 the <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> mechanism. Buildroot reads an <span class="emphasis"><em>override</em></span>
 1167 file, which allows the user to tell Buildroot the location of the
 1168 source for certain packages.</p><p>The default location of the override file is <code class="literal">$(CONFIG_DIR)/local.mk</code>,
 1169 as defined by the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration option.
 1170 <code class="literal">$(CONFIG_DIR)</code> is the location of the Buildroot <code class="literal">.config</code> file, so
 1171 <code class="literal">local.mk</code> by default lives side-by-side with the <code class="literal">.config</code> file,
 1172 which means:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1173 In the top-level Buildroot source directory for in-tree builds
 1174   (i.e., when <code class="literal">O=</code> is not used)
 1175 </li><li class="listitem">
 1176 In the out-of-tree directory for out-of-tree builds (i.e., when
 1177   <code class="literal">O=</code> is used)
 1178 </li></ul></div><p>If a different location than these defaults is required, it can be
 1179 specified through the <code class="literal">BR2_PACKAGE_OVERRIDE_FILE</code> configuration
 1180 option.</p><p>In this <span class="emphasis"><em>override</em></span> file, Buildroot expects to find lines of the form:</p><pre class="screen">&lt;pkg1&gt;_OVERRIDE_SRCDIR = /path/to/pkg1/sources
 1181 &lt;pkg2&gt;_OVERRIDE_SRCDIR = /path/to/pkg2/sources</pre><p>For example:</p><pre class="screen">LINUX_OVERRIDE_SRCDIR = /home/bob/linux/
 1182 BUSYBOX_OVERRIDE_SRCDIR = /home/bob/busybox/</pre><p>When Buildroot finds that for a given package, an
 1183 <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> has been defined, it will no longer attempt to
 1184 download, extract and patch the package. Instead, it will directly use
 1185 the source code available in the specified directory and <code class="literal">make clean</code>
 1186 will not touch this directory. This allows to point Buildroot to your
 1187 own directories, that can be managed by Git, Subversion, or any other
 1188 version control system. To achieve this, Buildroot will use <span class="emphasis"><em>rsync</em></span> to
 1189 copy the source code of the component from the specified
 1190 <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/&lt;package&gt;-custom/</code>.</p><p>This mechanism is best used in conjunction with the <code class="literal">make
 1191 &lt;pkg&gt;-rebuild</code> and <code class="literal">make &lt;pkg&gt;-reconfigure</code> targets. A <code class="literal">make
 1192 &lt;pkg&gt;-rebuild all</code> sequence will <span class="emphasis"><em>rsync</em></span> the source code from
 1193 <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR</code> to <code class="literal">output/build/&lt;package&gt;-custom</code> (thanks to
 1194 <span class="emphasis"><em>rsync</em></span>, only the modified files are copied), and restart the build
 1195 process of just this package.</p><p>In the example of the <code class="literal">linux</code> package above, the developer can then
 1196 make a source code change in <code class="literal">/home/bob/linux</code> and then run:</p><pre class="screen">make linux-rebuild all</pre><p>and in a matter of seconds gets the updated Linux kernel image in
 1197 <code class="literal">output/images</code>. Similarly, a change can be made to the BusyBox source
 1198 code in <code class="literal">/home/bob/busybox</code>, and after:</p><pre class="screen">make busybox-rebuild all</pre><p>the root filesystem image in <code class="literal">output/images</code> contains the updated
 1199 BusyBox.</p><p>Source trees for big projects often contain hundreds or thousands of
 1200 files which are not needed for building, but will slow down the process
 1201 of copying the sources with <span class="emphasis"><em>rsync</em></span>. Optionally, it is possible define
 1202 <code class="literal">&lt;pkg&gt;_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS</code> to skip syncing certain files
 1203 from the source tree. For example, when working on the <code class="literal">webkitgtk</code>
 1204 package, the following will exclude the tests and in-tree builds from
 1205 a local WebKit source tree:</p><pre class="screen">WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
 1207         --exclude JSTests --exclude ManualTests --exclude PerformanceTests \
 1208         --exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
 1209         --exclude WebKit.xcworkspace --exclude Websites --exclude Examples</pre><p>By default, Buildroot skips syncing of VCS artifacts (e.g., the <span class="strong"><strong>.git</strong></span> and
 1210 <span class="strong"><strong>.svn</strong></span> directories). Some packages prefer to have these VCS directories
 1211 available during build, for example for automatically determining a precise
 1212 commit reference for version information. To undo this built-in filtering at a
 1213 cost of a slower speed, add these directories back:</p><pre class="screen">LINUX_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = --include .git</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="customize"></a>Chapter 9. Project-specific customization</h2></div></div></div><p>Typical actions you may need to perform for a given project are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1214 configuring Buildroot (including build options and toolchain,
 1215   bootloader, kernel, package and filesystem image type selection)
 1216 </li><li class="listitem">
 1217 configuring other components, like the Linux kernel and BusyBox
 1218 </li><li class="listitem"><p class="simpara">
 1219 customizing the generated target filesystem
 1220 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 1221 adding or overwriting files on the target filesystem (using
 1222      <code class="literal">BR2_ROOTFS_OVERLAY</code>)
 1223 </li><li class="listitem">
 1224 modifying or deleting files on the target filesystem (using
 1225      <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
 1226 </li><li class="listitem">
 1227 running arbitrary commands prior to generating the filesystem image
 1228      (using <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
 1229 </li><li class="listitem">
 1230 setting file permissions and ownership (using
 1231      <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>)
 1232 </li><li class="listitem">
 1233 adding custom devices nodes (using
 1234      <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code>)
 1235 </li></ul></div></li><li class="listitem">
 1236 adding custom user accounts (using <code class="literal">BR2_ROOTFS_USERS_TABLES</code>)
 1237 </li><li class="listitem">
 1238 running arbitrary commands after generating the filesystem image
 1239   (using <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code>)
 1240 </li><li class="listitem">
 1241 adding project-specific patches to some packages (using
 1242   <code class="literal">BR2_GLOBAL_PATCH_DIR</code>)
 1243 </li><li class="listitem">
 1244 adding project-specific packages
 1245 </li></ul></div><p>An important note regarding such <span class="emphasis"><em>project-specific</em></span> customizations:
 1246 please carefully consider which changes are indeed project-specific and
 1247 which changes are also useful to developers outside your project. The
 1248 Buildroot community highly recommends and encourages the upstreaming of
 1249 improvements, packages and board support to the official Buildroot
 1250 project. Of course, it is sometimes not possible or desirable to
 1251 upstream because the changes are highly specific or proprietary.</p><p>This chapter describes how to make such project-specific customizations
 1252 in Buildroot and how to store them in a way that you can build the same
 1253 image in a reproducible way, even after running <span class="emphasis"><em>make clean</em></span>. By
 1254 following the recommended strategy, you can even use the same Buildroot
 1255 tree to build multiple distinct projects!</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-dir-structure"></a>9.1. Recommended directory structure</h2></div></div></div><p>When customizing Buildroot for your project, you will be creating one or
 1256 more project-specific files that need to be stored somewhere. While most
 1257 of these files could be placed in <span class="emphasis"><em>any</em></span> location as their path is to be
 1258 specified in the Buildroot configuration, the Buildroot developers
 1259 recommend a specific directory structure which is described in this
 1260 section.</p><p>Orthogonal to this directory structure, you can choose <span class="emphasis"><em>where</em></span> you place
 1261 this structure itself: either inside the Buildroot tree, or outside of
 1262 it using a br2-external tree. Both options are valid, the choice is up
 1263 to you.</p><pre class="screen">+-- board/
 1264 |   +-- &lt;company&gt;/
 1265 |       +-- &lt;boardname&gt;/
 1266 |           +-- linux.config
 1267 |           +-- busybox.config
 1268 |           +-- &lt;other configuration files&gt;
 1269 |           +-- post_build.sh
 1270 |           +-- post_image.sh
 1271 |           +-- rootfs_overlay/
 1272 |           |   +-- etc/
 1273 |           |   +-- &lt;some file&gt;
 1274 |           +-- patches/
 1275 |               +-- foo/
 1276 |               |   +-- &lt;some patch&gt;
 1277 |               +-- libbar/
 1278 |                   +-- &lt;some other patches&gt;
 1279 |
 1280 +-- configs/
 1281 |   +-- &lt;boardname&gt;_defconfig
 1282 |
 1283 +-- package/
 1284 |   +-- &lt;company&gt;/
 1285 |       +-- Config.in (if not using a br2-external tree)
 1286 |       +-- &lt;company&gt;.mk (if not using a br2-external tree)
 1287 |       +-- package1/
 1288 |       |    +-- Config.in
 1289 |       |    +-- package1.mk
 1290 |       +-- package2/
 1291 |           +-- Config.in
 1292 |           +-- package2.mk
 1293 |
 1294 +-- Config.in (if using a br2-external tree)
 1295 +-- external.mk (if using a br2-external tree)
 1296 +-- external.desc (if using a br2-external tree)</pre><p>Details on the files shown above are given further in this chapter.</p><p>Note: if you choose to place this structure outside of the Buildroot
 1297 tree but in a br2-external tree, the &lt;company&gt; and possibly &lt;boardname&gt;
 1298 components may be superfluous and can be left out.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_implementing_layered_customizations"></a>9.1.1. Implementing layered customizations</h3></div></div></div><p>It is quite common for a user to have several related projects that partly
 1299 need the same customizations. Instead of duplicating these
 1300 customizations for each project, it is recommended to use a layered
 1301 customization approach, as explained in this section.</p><p>Almost all of the customization methods available in Buildroot, like
 1302 post-build scripts and root filesystem overlays, accept a
 1303 space-separated list of items. The specified items are always treated in
 1304 order, from left to right. By creating more than one such item, one for
 1305 the common customizations and another one for the really
 1306 project-specific customizations, you can avoid unnecessary duplication.
 1307 Each layer is typically embodied by a separate directory inside
 1308 <code class="literal">board/&lt;company&gt;/</code>. Depending on your projects, you could even introduce
 1309 more than two layers.</p><p>An example directory structure for where a user has two customization
 1310 layers <span class="emphasis"><em>common</em></span> and <span class="emphasis"><em>fooboard</em></span> is:</p><pre class="screen">+-- board/
 1311     +-- &lt;company&gt;/
 1312         +-- common/
 1313         |   +-- post_build.sh
 1314         |   +-- rootfs_overlay/
 1315         |   |   +-- ...
 1316         |   +-- patches/
 1317         |       +-- ...
 1318         |
 1319         +-- fooboard/
 1320             +-- linux.config
 1321             +-- busybox.config
 1322             +-- &lt;other configuration files&gt;
 1323             +-- post_build.sh
 1324             +-- rootfs_overlay/
 1325             |   +-- ...
 1326             +-- patches/
 1327                 +-- ...</pre><p>For example, if the user has the <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration
 1328 option set as:</p><pre class="screen">BR2_GLOBAL_PATCH_DIR="board/&lt;company&gt;/common/patches board/&lt;company&gt;/fooboard/patches"</pre><p>then first the patches from the <span class="emphasis"><em>common</em></span> layer would be applied,
 1329 followed by the patches from the <span class="emphasis"><em>fooboard</em></span> layer.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="outside-br-custom"></a>9.2. Keeping customizations outside of Buildroot</h2></div></div></div><p>As already briefly mentioned in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, you can
 1330 place project-specific customizations in two locations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1331 directly within the Buildroot tree, typically maintaining them using
 1332    branches in a version control system so that upgrading to a newer
 1333    Buildroot release is easy.
 1334 </li><li class="listitem">
 1335 outside of the Buildroot tree, using the <span class="emphasis"><em>br2-external</em></span> mechanism.
 1336    This mechanism allows to keep package recipes, board support and
 1337    configuration files outside of the Buildroot tree, while still
 1338    having them nicely integrated in the build logic. We call this
 1339    location a <span class="emphasis"><em>br2-external tree</em></span>. This section explains how to use
 1340    the br2-external mechanism and what to provide in a br2-external
 1341    tree.
 1342 </li></ul></div><p>One can tell Buildroot to use one or more br2-external trees by setting
 1343 the <code class="literal">BR2_EXTERNAL</code> make variable set to the path(s) of the br2-external
 1344 tree(s) to use. It can be passed to any Buildroot <code class="literal">make</code> invocation. It
 1345 is automatically saved in the hidden <code class="literal">.br2-external.mk</code> file in the output
 1346 directory. Thanks to this, there is no need to pass <code class="literal">BR2_EXTERNAL</code> at
 1347 every <code class="literal">make</code> invocation. It can however be changed at any time by
 1348 passing a new value, and can be removed by passing an empty value.</p><p><strong>Note. </strong>The path to a br2-external tree can be either absolute or relative.
 1349 If it is passed as a relative path, it is important to note that it is
 1350 interpreted relative to the main Buildroot source directory, <span class="strong"><strong>not</strong></span> to
 1351 the Buildroot output directory.</p><p><strong>Note: </strong>If using an br2-external tree from before Buildroot 2016.11, you need to
 1352 convert it before you can use it with Buildroot 2016.11 onward. See
 1353 <a class="xref" href="#br2-external-converting" title="27.1. Migrating to 2016.11">Section 27.1, “Migrating to 2016.11</a> for help on doing so.</p><p>Some examples:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/path/to/foo menuconfig</pre><p>From now on, definitions from the <code class="literal">/path/to/foo</code> br2-external tree
 1354 will be used:</p><pre class="screen">buildroot/ $ make
 1355 buildroot/ $ make legal-info</pre><p>We can switch to another br2-external tree at any time:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/where/we/have/bar xconfig</pre><p>We can also use multiple br2-external trees:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL=/path/to/foo:/where/we/have/bar menuconfig</pre><p>Or disable the usage of any br2-external tree:</p><pre class="screen">buildroot/ $ make BR2_EXTERNAL= xconfig</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_layout_of_a_br2_external_tree"></a>9.2.1. Layout of a br2-external tree</h3></div></div></div><p>A br2-external tree must contain at least those three files, described
 1356 in the following chapters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1357 <code class="literal">external.desc</code>
 1358 </li><li class="listitem">
 1359 <code class="literal">external.mk</code>
 1360 </li><li class="listitem">
 1361 <code class="literal">Config.in</code>
 1362 </li></ul></div><p>Apart from those mandatory files, there may be additional and optional
 1363 content that may be present in a br2-external tree, like the <code class="literal">configs/</code>
 1364 or <code class="literal">provides/</code> directories. They are described in the following chapters
 1365 as well.</p><p>A complete example br2-external tree layout is also described later.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_external_desc_literal_file"></a>The <code class="literal">external.desc</code> file</h4></div></div></div><p>That file describes the br2-external tree: the <span class="emphasis"><em>name</em></span> and <span class="emphasis"><em>description</em></span>
 1366 for that br2-external tree.</p><p>The format for this file is line based, with each line starting by a
 1367 keyword, followed by a colon and one or more spaces, followed by the
 1368 value assigned to that keyword. There are two keywords currently
 1369 recognised:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
 1370 <code class="literal">name</code>, mandatory, defines the name for that br2-external tree. That
 1371    name must only use ASCII characters in the set <code class="literal">[A-Za-z0-9_]</code>; any
 1372    other character is forbidden. Buildroot sets the variable
 1373    <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> to the absolute path of the br2-external
 1374    tree, so that you can use it to refer to your br2-external tree. This
 1375    variable is available both in Kconfig, so you can use it to source your
 1376    Kconfig files (see below) and in the Makefile, so that you can use it
 1377    to include other Makefiles (see below) or refer to other files (like
 1378    data files) from your br2-external tree.
 1379 </p><p><strong>Note: </strong>Since it is possible to use multiple br2-external trees at once, this
 1380   name is used by Buildroot to generate variables for each of those trees.
 1381   That name is used to identify your br2-external tree, so try to come up
 1382   with a name that really describes your br2-external tree, in order for
 1383   it to be relatively unique, so that it does not clash with another name
 1384   from another br2-external tree, especially if you are planning on
 1385   somehow sharing your br2-external tree with third parties or using
 1386   br2-external trees from third parties.</p></li><li class="listitem">
 1387 <code class="literal">desc</code>, optional, provides a short description for that br2-external
 1388    tree. It shall fit on a single line, is mostly free-form (see below),
 1389    and is used when displaying information about a br2-external tree (e.g.
 1390    above the list of defconfig files, or as the prompt in the menuconfig);
 1391    as such, it should relatively brief (40 chars is probably a good upper
 1392    limit). The description is available in the <code class="literal">BR2_EXTERNAL_$(NAME)_DESC</code>
 1393    variable.
 1394 </li></ul></div><p>Examples of names and the corresponding <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code>
 1395 variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1396 <code class="literal">FOO</code><code class="literal">BR2_EXTERNAL_FOO_PATH</code>
 1397 </li><li class="listitem">
 1398 <code class="literal">BAR_42</code><code class="literal">BR2_EXTERNAL_BAR_42_PATH</code>
 1399 </li></ul></div><p>In the following examples, it is assumed the name to be set to <code class="literal">BAR_42</code>.</p><p><strong>Note: </strong>Both <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> and <code class="literal">BR2_EXTERNAL_$(NAME)_DESC</code> are
 1400   available in the Kconfig files and the Makefiles. They are also
 1401   exported in the environment so are available in post-build, post-image
 1402   and in-fakeroot scripts.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_config_in_literal_and_literal_external_mk_literal_files"></a>The <code class="literal">Config.in</code> and <code class="literal">external.mk</code> files</h4></div></div></div><p>Those files (which may each be empty) can be used to define package
 1403 recipes (i.e. <code class="literal">foo/Config.in</code> and <code class="literal">foo/foo.mk</code> like for packages bundled
 1404 in Buildroot itself) or other custom configuration options or make logic.</p><p>Buildroot automatically includes the <code class="literal">Config.in</code> from each br2-external
 1405 tree to make it appear in the top-level configuration menu, and includes
 1406 the <code class="literal">external.mk</code> from each br2-external tree with the rest of the
 1407 makefile logic.</p><p>The main usage of this is to store package recipes. The recommended way
 1408 to do this is to write a <code class="literal">Config.in</code> file that looks like:</p><pre class="screen">source "$BR2_EXTERNAL_BAR_42_PATH/package/package1/Config.in"
 1409 source "$BR2_EXTERNAL_BAR_42_PATH/package/package2/Config.in"</pre><p>Then, have an <code class="literal">external.mk</code> file that looks like:</p><pre class="screen">include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))</pre><p>And then in <code class="literal">$(BR2_EXTERNAL_BAR_42_PATH)/package/package1</code> and
 1410 <code class="literal">$(BR2_EXTERNAL_BAR_42_PATH)/package/package2</code> create normal
 1411 Buildroot package recipes, as explained in <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a>.
 1412 If you prefer, you can also group the packages in subdirectories
 1413 called &lt;boardname&gt; and adapt the above paths accordingly.</p><p>You can also define custom configuration options in <code class="literal">Config.in</code> and
 1414 custom make logic in <code class="literal">external.mk</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_configs_literal_directory"></a>The <code class="literal">configs/</code> directory</h4></div></div></div><p>One can store Buildroot defconfigs in the <code class="literal">configs</code> subdirectory of
 1415 the br2-external tree. Buildroot will automatically show them in the
 1416 output of <code class="literal">make list-defconfigs</code> and allow them to be loaded with the
 1417 normal <code class="literal">make &lt;name&gt;_defconfig</code> command. They will be visible in the
 1418 <span class="emphasis"><em>make list-defconfigs</em></span> output, below an <code class="literal">External configs</code> label that
 1419 contains the name of the br2-external tree they are defined in.</p><p><strong>Note: </strong>If a defconfig file is present in more than one br2-external tree, then
 1420 the one from the last br2-external tree is used. It is thus possible
 1421 to override a defconfig bundled in Buildroot or another br2-external
 1422 tree.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_literal_provides_literal_directory"></a>The <code class="literal">provides/</code> directory</h4></div></div></div><p>For some packages, Buildroot provides a choice between two (or more)
 1423 implementations of API-compatible such packages. For example, there is
 1424 a choice to choose either libjpeg ot jpeg-turbo; there is one between
 1425 openssl or libressl; there is one to select one of the known,
 1426 pre-configured toolchains…</p><p>It is possible for a br2-external to extend those choices, by providing
 1427 a set of files that define those alternatives:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1428 <code class="literal">provides/toolchains.in</code> defines the pre-configured toolchains, which
 1429   will then be listed in the toolchain selection;
 1430 </li><li class="listitem">
 1431 <code class="literal">provides/jpeg.in</code> defines the alternative libjpeg implementations;
 1432 </li><li class="listitem">
 1433 <code class="literal">provides/openssl.in</code> defines the alternative openssl implementations;
 1434 </li><li class="listitem">
 1435 <code class="literal">provides/skeleton.in</code> defines the alternative skeleton implementations;
 1436 </li><li class="listitem">
 1437 <code class="literal">provides/init.in</code> defines the alternative init system implementations, this
 1438   can be used to select a default skeleton for your init.
 1439 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_free_form_content"></a>Free-form content</h4></div></div></div><p>One can store all the board-specific configuration files there, such
 1440 as the kernel configuration, the root filesystem overlay, or any other
 1441 configuration file for which Buildroot allows to set the location (by
 1442 using the <code class="literal">BR2_EXTERNAL_$(NAME)_PATH</code> variable). For example, you
 1443 could set the paths to a global patch directory, to a rootfs overlay
 1444 and to the kernel configuration file as follows (e.g. by running
 1445 <code class="literal">make menuconfig</code> and filling in these options):</p><pre class="screen">BR2_GLOBAL_PATCH_DIR=$(BR2_EXTERNAL_BAR_42_PATH)/patches/
 1446 BR2_ROOTFS_OVERLAY=$(BR2_EXTERNAL_BAR_42_PATH)/board/&lt;boardname&gt;/overlay/
 1447 BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE=$(BR2_EXTERNAL_BAR_42_PATH)/board/&lt;boardname&gt;/kernel.config</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_additional_linux_kernel_extensions"></a>Additional Linux kernel extensions</h4></div></div></div><p>Additional Linux kernel extensions (see <a class="xref" href="#linux-kernel-ext" title="18.21.2. linux-kernel-extensions">Section 18.21.2, “linux-kernel-extensions”</a>) can
 1448 be added by storing them in the <code class="literal">linux/</code> directory at the root of a
 1449 br2-external tree.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_example_layout"></a>Example layout</h4></div></div></div><p>Here is an example layout using all features of br2-external (the sample
 1450 content is shown for the file above it, when it is relevant to explain
 1451 the br2-external tree; this is all entirely made up just for the sake of
 1452 illustration, of course):</p><pre class="screen">/path/to/br2-ext-tree/
 1453   |- external.desc
 1454   |     |name: BAR_42
 1455   |     |desc: Example br2-external tree
 1456   |     `----
 1457   |
 1458   |- Config.in
 1459   |     |source "$BR2_EXTERNAL_BAR_42_PATH/toolchain/toolchain-external-mine/Config.in.options"
 1460   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-1/Config.in"
 1461   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/pkg-2/Config.in"
 1462   |     |source "$BR2_EXTERNAL_BAR_42_PATH/package/my-jpeg/Config.in"
 1463   |     |
 1464   |     |config BAR_42_FLASH_ADDR
 1465   |     |    hex "my-board flash address"
 1466   |     |    default 0x10AD
 1467   |     `----
 1468   |
 1469   |- external.mk
 1470   |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/package/*/*.mk))
 1471   |     |include $(sort $(wildcard $(BR2_EXTERNAL_BAR_42_PATH)/toolchain/*/*.mk))
 1472   |     |
 1473   |     |flash-my-board:
 1474   |     |    $(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/flash-image \
 1475   |     |        --image $(BINARIES_DIR)/image.bin \
 1476   |     |        --address $(BAR_42_FLASH_ADDR)
 1477   |     `----
 1478   |
 1479   |- package/pkg-1/Config.in
 1480   |     |config BR2_PACKAGE_PKG_1
 1481   |     |    bool "pkg-1"
 1482   |     |    help
 1483   |     |      Some help about pkg-1
 1484   |     `----
 1485   |- package/pkg-1/pkg-1.hash
 1486   |- package/pkg-1/pkg-1.mk
 1487   |     |PKG_1_VERSION = 1.2.3
 1488   |     |PKG_1_SITE = /some/where/to/get/pkg-1
 1489   |     |PKG_1_LICENSE = blabla
 1490   |     |
 1491   |     |define PKG_1_INSTALL_INIT_SYSV
 1492   |     |    $(INSTALL) -D -m 0755 $(PKG_1_PKGDIR)/S99my-daemon \
 1493   |     |                          $(TARGET_DIR)/etc/init.d/S99my-daemon
 1494   |     |endef
 1495   |     |
 1496   |     |$(eval $(autotools-package))
 1497   |     `----
 1498   |- package/pkg-1/S99my-daemon
 1499   |
 1500   |- package/pkg-2/Config.in
 1501   |- package/pkg-2/pkg-2.hash
 1502   |- package/pkg-2/pkg-2.mk
 1503   |
 1504   |- provides/jpeg.in
 1505   |     |config BR2_PACKAGE_MY_JPEG
 1506   |     |    bool "my-jpeg"
 1507   |     `----
 1508   |- package/my-jpeg/Config.in
 1509   |     |config BR2_PACKAGE_PROVIDES_JPEG
 1510   |     |    default "my-jpeg" if BR2_PACKAGE_MY_JPEG
 1511   |     `----
 1512   |- package/my-jpeg/my-jpeg.mk
 1513   |     |# This is a normal package .mk file
 1514   |     |MY_JPEG_VERSION = 1.2.3
 1515   |     |MY_JPEG_SITE = https://example.net/some/place
 1516   |     |MY_JPEG_PROVIDES = jpeg
 1517   |     |$(eval $(autotools-package))
 1518   |     `----
 1519   |
 1520   |- provides/init.in
 1521   |     |config BR2_INIT_MINE
 1522   |     |    bool "my custom init"
 1523   |     |    select BR2_PACKAGE_MY_INIT
 1525   |     `----
 1526   |
 1527   |- provides/skeleton.in
 1528   |     |config BR2_ROOTFS_SKELETON_MINE
 1529   |     |    bool "my custom skeleton"
 1530   |     |    select BR2_PACKAGE_SKELETON_MINE
 1531   |     `----
 1532   |- package/skeleton-mine/Config.in
 1533   |     |config BR2_PACKAGE_SKELETON_MINE
 1534   |     |    bool
 1535   |     |    select BR2_PACKAGE_HAS_SKELETON
 1536   |     |
 1537   |     |config BR2_PACKAGE_PROVIDES_SKELETON
 1538   |     |    default "skeleton-mine" if BR2_PACKAGE_SKELETON_MINE
 1539   |     `----
 1540   |- package/skeleton-mine/skeleton-mine.mk
 1543   |     |SKELETON_MINE_PROVIDES = skeleton
 1545   |     |$(eval $(generic-package))
 1546   |     `----
 1547   |
 1548   |- provides/toolchains.in
 1549   |     |config BR2_TOOLCHAIN_EXTERNAL_MINE
 1550   |     |    bool "my custom toolchain"
 1551   |     |    depends on BR2_some_arch
 1552   |     |    select BR2_INSTALL_LIBSTDCPP
 1553   |     `----
 1554   |- toolchain/toolchain-external-mine/Config.in.options
 1556   |     |config BR2_TOOLCHAIN_EXTERNAL_PREFIX
 1557   |     |    default "arch-mine-linux-gnu"
 1559   |     |    default "toolchain-external-mine"
 1560   |     |endif
 1561   |     `----
 1562   |- toolchain/toolchain-external-mine/toolchain-external-mine.mk
 1563   |     |TOOLCHAIN_EXTERNAL_MINE_SITE = https://example.net/some/place
 1564   |     |TOOLCHAIN_EXTERNAL_MINE_SOURCE = my-toolchain.tar.gz
 1565   |     |$(eval $(toolchain-external-package))
 1566   |     `----
 1567   |
 1568   |- linux/Config.ext.in
 1570   |     |    bool "example-external-driver"
 1571   |     |    help
 1572   |     |      Example external driver
 1573   |     |---
 1574   |- linux/linux-ext-example-driver.mk
 1575   |
 1576   |- configs/my-board_defconfig
 1577   |     |BR2_GLOBAL_PATCH_DIR="$(BR2_EXTERNAL_BAR_42_PATH)/patches/"
 1578   |     |BR2_ROOTFS_OVERLAY="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/overlay/"
 1579   |     |BR2_ROOTFS_POST_IMAGE_SCRIPT="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/post-image.sh"
 1580   |     |BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="$(BR2_EXTERNAL_BAR_42_PATH)/board/my-board/kernel.config"
 1581   |     `----
 1582   |
 1583   |- patches/linux/0001-some-change.patch
 1584   |- patches/linux/0002-some-other-change.patch
 1585   |- patches/busybox/0001-fix-something.patch
 1586   |
 1587   |- board/my-board/kernel.config
 1588   |- board/my-board/overlay/var/www/index.html
 1589   |- board/my-board/overlay/var/www/my.css
 1590   |- board/my-board/flash-image
 1591   `- board/my-board/post-image.sh
 1592         |#!/bin/sh
 1593         |generate-my-binary-image \
 1594         |    --root ${BINARIES_DIR}/rootfs.tar \
 1595         |    --kernel ${BINARIES_DIR}/zImage \
 1596         |    --dtb ${BINARIES_DIR}/my-board.dtb \
 1597         |    --output ${BINARIES_DIR}/image.bin
 1598         `----</pre><p>The br2-external tree will then be visible in the menuconfig (with
 1599 the layout expanded):</p><pre class="screen">External options  ---&gt;
 1600     *** Example br2-external tree (in /path/to/br2-ext-tree/)
 1601     [ ] pkg-1
 1602     [ ] pkg-2
 1603     (0x10AD) my-board flash address</pre><p>If you are using more than one br2-external tree, it would look like
 1604 (with the layout expanded and the second one with name <code class="literal">FOO_27</code> but no
 1605 <code class="literal">desc:</code> field in <code class="literal">external.desc</code>):</p><pre class="screen">External options  ---&gt;
 1606     Example br2-external tree  ---&gt;
 1607         *** Example br2-external tree (in /path/to/br2-ext-tree)
 1608         [ ] pkg-1
 1609         [ ] pkg-2
 1610         (0x10AD) my-board flash address
 1611     FOO_27  ---&gt;
 1612         *** FOO_27 (in /path/to/another-br2-ext)
 1613         [ ] foo
 1614         [ ] bar</pre><p>Additionally, the jpeg provider will be visible in the jpeg choice:</p><pre class="screen">Target packages  ---&gt;
 1615     Libraries  ---&gt;
 1616         Graphics  ---&gt;
 1617             [*] jpeg support
 1618                 jpeg variant ()  ---&gt;
 1619                     ( ) jpeg
 1620                     ( ) jpeg-turbo
 1621                         *** jpeg from: Example br2-external tree ***
 1622                     (X) my-jpeg
 1623                         *** jpeg from: FOO_27 ***
 1624                     ( ) another-jpeg</pre><p>And similarly for the toolchains:</p><pre class="screen">Toolchain  ---&gt;
 1625     Toolchain ()  ---&gt;
 1626         ( ) Custom toolchain
 1627             *** Toolchains from: Example br2-external tree ***
 1628         (X) my custom toolchain</pre><p><strong>Note. </strong>The toolchain options in <code class="literal">toolchain/toolchain-external-mine/Config.in.options</code>
 1629 will not appear in the <code class="literal">Toolchain</code> menu. They must be explicitly included
 1630 from within the br2-external’s top-level <code class="literal">Config.in</code> and will thus appear
 1631 in the <code class="literal">External options</code> menu.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-store-buildroot-config"></a>9.3. Storing the Buildroot configuration</h2></div></div></div><p>The Buildroot configuration can be stored using the command
 1632  <code class="literal">make savedefconfig</code>.</p><p>This strips the Buildroot configuration down by removing configuration
 1633 options that are at their default value. The result is stored in a file
 1634 called <code class="literal">defconfig</code>. If you want to save it in another place, change the
 1635 <code class="literal">BR2_DEFCONFIG</code> option in the Buildroot configuration itself, or call
 1636 make with <code class="literal">make savedefconfig BR2_DEFCONFIG=&lt;path-to-defconfig&gt;</code>.</p><p>The recommended place to store this defconfig is
 1637 <code class="literal">configs/&lt;boardname&gt;_defconfig</code>. If you follow this recommendation, the
 1638 configuration will be listed in <code class="literal">make help</code> and can be set again by
 1639 running <code class="literal">make &lt;boardname&gt;_defconfig</code>.</p><p>Alternatively, you can copy the file to any other place and rebuild with
 1640 <code class="literal">make defconfig BR2_DEFCONFIG=&lt;path-to-defconfig-file&gt;</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-store-package-config"></a>9.4. Storing the configuration of other components</h2></div></div></div><p>The configuration files for BusyBox, the Linux kernel, Barebox, U-Boot
 1641 and uClibc should be stored as well if changed. For each of these
 1642 components, a Buildroot configuration option exists to point to an input
 1643 configuration file, e.g. <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. To store
 1644 their configuration, set these configuration options to a path where you
 1645 want to save the configuration files, and then use the helper targets
 1646 described below to actually store the configuration.</p><p>As explained in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path to
 1647 store these configuration files is
 1648 <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/foo.config</code>.</p><p>Make sure that you create a configuration file <span class="emphasis"><em>before</em></span> changing
 1649 the <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code> etc. options. Otherwise,
 1650 Buildroot will try to access this config file, which doesn’t exist
 1651 yet, and will fail. You can create the configuration file by running
 1652 <code class="literal">make linux-menuconfig</code> etc.</p><p>Buildroot provides a few helper targets to make the saving of
 1653 configuration files easier.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1654 <code class="literal">make linux-update-defconfig</code> saves the linux configuration to the
 1655   path specified by <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>. It
 1656   simplifies the config file by removing default values. However,
 1657   this only works with kernels starting from 2.6.33. For earlier
 1658   kernels, use <code class="literal">make linux-update-config</code>.
 1659 </li><li class="listitem">
 1660 <code class="literal">make busybox-update-config</code> saves the busybox configuration to the
 1661   path specified by <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>.
 1662 </li><li class="listitem">
 1663 <code class="literal">make uclibc-update-config</code> saves the uClibc configuration to the
 1664   path specified by <code class="literal">BR2_UCLIBC_CONFIG</code>.
 1665 </li><li class="listitem">
 1666 <code class="literal">make barebox-update-defconfig</code> saves the barebox configuration to the
 1667   path specified by <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>.
 1668 </li><li class="listitem">
 1669 <code class="literal">make uboot-update-defconfig</code> saves the U-Boot configuration to the
 1670   path specified by <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>.
 1671 </li><li class="listitem">
 1672 For at91bootstrap3, no helper exists so you have to copy the config
 1673   file manually to <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>.
 1674 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rootfs-custom"></a>9.5. Customizing the generated target filesystem</h2></div></div></div><p>Besides changing the configuration through <code class="literal">make *config</code>,
 1675 there are a few other ways to customize the resulting target filesystem.</p><p>The two recommended methods, which can co-exist, are root filesystem
 1676 overlay(s) and post build script(s).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
 1677 Root filesystem overlays (<code class="literal">BR2_ROOTFS_OVERLAY</code>)
 1678 </span></dt><dd><p class="simpara">A filesystem overlay is a tree of files that is copied directly
 1679   over the target filesystem after it has been built. To enable this
 1680   feature, set config option <code class="literal">BR2_ROOTFS_OVERLAY</code> (in the <code class="literal">System
 1681   configuration</code> menu) to the root of the overlay. You can even specify
 1682   multiple overlays, space-separated. If you specify a relative path,
 1683   it will be relative to the root of the Buildroot tree. Hidden
 1684   directories of version control systems, like <code class="literal">.git</code>, <code class="literal">.svn</code>, <code class="literal">.hg</code>,
 1685   etc., files called <code class="literal">.empty</code> and files ending in <code class="literal">~</code> are excluded from
 1686   the copy.</p><p class="simpara">When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the overlay must not
 1687   contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span> directories, as Buildroot will
 1688   create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>.  In
 1689   such a situation, should the overlay have any programs or libraries,
 1690   they should be placed in <span class="emphasis"><em>/usr/bin</em></span>, <span class="emphasis"><em>/usr/sbin</em></span> and <span class="emphasis"><em>/usr/lib</em></span>.</p><p class="simpara">As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path for
 1691   this overlay is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/rootfs-overlay</code>.</p></dd><dt><span class="term">
 1692 Post-build scripts (<code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code>)
 1693 </span></dt><dd><p class="simpara">Post-build scripts are shell scripts called <span class="emphasis"><em>after</em></span> Buildroot builds
 1694   all the selected software, but <span class="emphasis"><em>before</em></span> the rootfs images are
 1695   assembled. To enable this feature, specify a space-separated list of
 1696   post-build scripts in config option <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> (in
 1697   the <code class="literal">System configuration</code> menu). If you specify a relative path, it
 1698   will be relative to the root of the Buildroot tree.</p><p class="simpara">Using post-build scripts, you can remove or modify any file in your
 1699   target filesystem. You should, however, use this feature with care.
 1700   Whenever you find that a certain package generates wrong or unneeded
 1701   files, you should fix that package rather than work around it with some
 1702   post-build cleanup scripts.</p><p class="simpara">As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended path for
 1703   this script is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/post_build.sh</code>.</p><p class="simpara">The post-build scripts are run with the main Buildroot tree as current
 1704   working directory. The path to the target filesystem is passed as the
 1705   first argument to each script. If the config option
 1706   <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these arguments will be
 1707   passed to the script too. All the scripts will be passed the exact
 1708   same set of arguments, it is not possible to pass different sets of
 1709   arguments to each script.</p><p class="simpara">In addition, you may also use these environment variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1710 <code class="literal">BR2_CONFIG</code>: the path to the Buildroot .config file
 1711 </li><li class="listitem">
 1712 <code class="literal">CONFIG_DIR</code>: the directory containing the .config file, and
 1713     therefore the top-level Buildroot Makefile to use (which is
 1714     correct for both in-tree and out-of-tree builds)
 1715 </li><li class="listitem">
 1716 <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>, <code class="literal">TARGET_DIR</code>: see
 1717     <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>
 1718 </li><li class="listitem">
 1719 <code class="literal">BUILD_DIR</code>: the directory where packages are extracted and built
 1720 </li><li class="listitem">
 1721 <code class="literal">BINARIES_DIR</code>: the place where all binary files (aka images) are
 1722     stored
 1723 </li><li class="listitem">
 1724 <code class="literal">BASE_DIR</code>: the base output directory
 1725 </li></ul></div></dd></dl></div><p>Below three more methods of customizing the target filesystem are
 1726 described, but they are not recommended.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
 1727 Direct modification of the target filesystem
 1728 </span></dt><dd><p class="simpara">For temporary modifications, you can modify the target filesystem
 1729   directly and rebuild the image. The target filesystem is available
 1730   under <code class="literal">output/target/</code>. After making your changes, run <code class="literal">make</code> to
 1731   rebuild the target filesystem image.</p><p class="simpara">This method allows you to do anything to the target filesystem, but if
 1732   you need to clean your Buildroot tree using <code class="literal">make clean</code>, these
 1733   changes will be lost. Such cleaning is necessary in several cases,
 1734   refer to <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a> for details. This solution is therefore
 1735   only useful for quick tests: <span class="emphasis"><em>changes do not survive the <code class="literal">make clean</code>
 1736   command</em></span>. Once you have validated your changes, you should make sure
 1737   that they will persist after a <code class="literal">make clean</code>, using a root filesystem
 1738   overlay or a post-build script.</p></dd><dt><span class="term">
 1739 Custom target skeleton (<code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code>)
 1740 </span></dt><dd><p class="simpara">The root filesystem image is created from a target skeleton, on top of
 1741   which all packages install their files. The skeleton is copied to the
 1742   target directory <code class="literal">output/target</code> before any package is built and
 1743   installed. The default target skeleton provides the standard Unix
 1744   filesystem layout and some basic init scripts and configuration files.</p><p class="simpara">If the default skeleton (available under <code class="literal">system/skeleton</code>) does not
 1745   match your needs, you would typically use a root filesystem overlay or
 1746   post-build script to adapt it. However, if the default skeleton is
 1747   entirely different than what you need, using a custom skeleton may be
 1748   more suitable.</p><p class="simpara">To enable this feature, enable config option
 1749   <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM</code> and set <code class="literal">BR2_ROOTFS_SKELETON_CUSTOM_PATH</code>
 1750   to the path of your custom skeleton. Both options are available in the
 1751   <code class="literal">System configuration</code> menu. If you specify a relative path, it will
 1752   be relative to the root of the Buildroot tree.</p><p class="simpara">Custom skeletons don’t need to contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span>
 1753   directories, since they are created automatically during the build.
 1754   When <code class="literal">BR2_ROOTFS_MERGED_USR</code> is enabled, then the custom skeleton must
 1755   not contain the <span class="emphasis"><em>/bin</em></span>, <span class="emphasis"><em>/lib</em></span> or <span class="emphasis"><em>/sbin</em></span> directories, as Buildroot
 1756   will create them as symbolic links to the relevant folders in <span class="emphasis"><em>/usr</em></span>.
 1757   In such a situation, should the skeleton have any programs or
 1758   libraries, they should be placed in <span class="emphasis"><em>/usr/bin</em></span>, <span class="emphasis"><em>/usr/sbin</em></span> and
 1759   <span class="emphasis"><em>/usr/lib</em></span>.</p><p class="simpara">This method is not recommended because it duplicates the entire
 1760   skeleton, which prevents taking advantage of the fixes or improvements
 1761   brought to the default skeleton in later Buildroot releases.</p></dd><dt><span class="term">
 1762 Post-fakeroot scripts (<code class="literal">BR2_ROOTFS_POST_FAKEROOT_SCRIPT</code>)
 1763 </span></dt><dd><p class="simpara">When aggregating the final images, some parts of the process requires
 1764   root rights: creating device nodes in <code class="literal">/dev</code>, setting permissions or
 1765   ownership to files and directories… To avoid requiring actual root
 1766   rights, Buildroot uses <code class="literal">fakeroot</code> to simulate root rights. This is not
 1767   a complete substitute for actually being root, but is enough for what
 1768   Buildroot needs.</p><p class="simpara">Post-fakeroot scripts are shell scripts that are called at the <span class="emphasis"><em>end</em></span> of
 1769   the fakeroot phase, <span class="emphasis"><em>right before</em></span> the filesystem image generator is
 1770   called. As such, they are called in the fakeroot context.</p><p class="simpara">Post-fakeroot scripts can be useful in case you need to tweak the
 1771   filesystem to do modifications that are usually only available to the
 1772   root user.</p><p><strong>Note: </strong>It is recommended to use the existing mechanisms to set file permissions
 1773   or create entries in <code class="literal">/dev</code> (see <a class="xref" href="#customize-device-permission" title="9.5.1. Setting file permissions and ownership and adding custom devices nodes">Section 9.5.1, “Setting file permissions and ownership and adding custom devices nodes”</a>) or
 1774   to create users (see <a class="xref" href="#customize-users" title="9.6. Adding custom user accounts">Section 9.6, “Adding custom user accounts”</a>)</p><p><strong>Note: </strong>The difference between post-build scripts (above) and fakeroot scripts,
 1775   is that post-build scripts are not called in the fakeroot context.</p><p><strong>Note: </strong>Using <code class="literal">fakeroot</code> is not an absolute substitute for actually being root.
 1776   <code class="literal">fakeroot</code> only ever fakes the file access rights and types (regular,
 1777   block-or-char device…) and uid/gid; these are emulated in-memory.</p></dd></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="customize-device-permission"></a>9.5.1. Setting file permissions and ownership and adding custom devices nodes</h3></div></div></div><p>Sometimes it is needed to set specific permissions or ownership on files
 1778 or device nodes. For example, certain files may need to be owned by
 1779 root. Since the post-build scripts are not run as root, you cannot do
 1780 such changes from there unless you use an explicit fakeroot from the
 1781 post-build script.</p><p>Instead, Buildroot provides support for so-called <span class="emphasis"><em>permission tables</em></span>.
 1782 To use this feature, set config option <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code> to a
 1783 space-separated list of permission tables, regular text files following
 1784 the <a class="link" href="#makedev-syntax" title="Chapter 25. Makedev syntax documentation">makedev syntax</a>.</p><p>If you are using a static device table (i.e. not using <code class="literal">devtmpfs</code>,
 1785 <code class="literal">mdev</code>, or <code class="literal">(e)udev</code>) then you can add device nodes using the same
 1786 syntax, in so-called <span class="emphasis"><em>device tables</em></span>. To use this feature, set config
 1787 option <code class="literal">BR2_ROOTFS_STATIC_DEVICE_TABLE</code> to a space-separated list of
 1788 device tables.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
 1789 such files is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/</code>.</p><p>It should be noted that if the specific permissions or device nodes are
 1790 related to a specific application, you should set variables
 1791 <code class="literal">FOO_PERMISSIONS</code> and <code class="literal">FOO_DEVICES</code> in the package’s <code class="literal">.mk</code> file instead
 1792 (see <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>).</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-users"></a>9.6. Adding custom user accounts</h2></div></div></div><p>Sometimes it is needed to add specific users in the target system.
 1793 To cover this requirement, Buildroot provides support for so-called
 1794 <span class="emphasis"><em>users tables</em></span>. To use this feature, set config option
 1795 <code class="literal">BR2_ROOTFS_USERS_TABLES</code> to a space-separated list of users tables,
 1796 regular text files following the <a class="link" href="#makeuser-syntax" title="Chapter 26. Makeusers syntax documentation">makeusers syntax</a>.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
 1797 such files is <code class="literal">board/&lt;company&gt;/&lt;boardname&gt;/</code>.</p><p>It should be noted that if the custom users are related to a specific
 1798 application, you should set variable <code class="literal">FOO_USERS</code> in the package’s <code class="literal">.mk</code>
 1799 file instead (see <a class="xref" href="#generic-package-reference" title="18.5.2. generic-package reference">Section 18.5.2, “<code class="literal">generic-package</code> reference”</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_customization_emphasis_after_emphasis_the_images_have_been_created"></a>9.7. Customization <span class="emphasis"><em>after</em></span> the images have been created</h2></div></div></div><p>While post-build scripts (<a class="xref" href="#rootfs-custom" title="9.5. Customizing the generated target filesystem">Section 9.5, “Customizing the generated target filesystem”</a>) are run <span class="emphasis"><em>before</em></span>
 1800 building the filesystem image, kernel and bootloader, <span class="strong"><strong>post-image
 1801 scripts</strong></span> can be used to perform some specific actions <span class="emphasis"><em>after</em></span> all images
 1802 have been created.</p><p>Post-image scripts can for example be used to automatically extract your
 1803 root filesystem tarball in a location exported by your NFS server, or
 1804 to create a special firmware image that bundles your root filesystem and
 1805 kernel image, or any other custom action required for your project.</p><p>To enable this feature, specify a space-separated list of post-image
 1806 scripts in config option <code class="literal">BR2_ROOTFS_POST_IMAGE_SCRIPT</code> (in the <code class="literal">System
 1807 configuration</code> menu). If you specify a relative path, it will be
 1808 relative to the root of the Buildroot tree.</p><p>Just like post-build scripts, post-image scripts are run with the main
 1809 Buildroot tree as current working directory. The path to the <code class="literal">images</code>
 1810 output directory is passed as the first argument to each script. If the
 1811 config option <code class="literal">BR2_ROOTFS_POST_SCRIPT_ARGS</code> is not empty, these
 1812 arguments will be passed to the script too. All the scripts will be
 1813 passed the exact same set of arguments, it is not possible to pass
 1814 different sets of arguments to each script.</p><p>Again just like for the post-build scripts, the scripts have access to
 1815 the environment variables <code class="literal">BR2_CONFIG</code>, <code class="literal">HOST_DIR</code>, <code class="literal">STAGING_DIR</code>,
 1816 <code class="literal">TARGET_DIR</code>, <code class="literal">BUILD_DIR</code>, <code class="literal">BINARIES_DIR</code>, <code class="literal">CONFIG_DIR</code> and
 1817 <code class="literal">BASE_DIR</code>.</p><p>The post-image scripts will be executed as the user that executes
 1818 Buildroot, which should normally <span class="emphasis"><em>not</em></span> be the root user. Therefore, any
 1819 action requiring root permissions in one of these scripts will require
 1820 special handling (usage of fakeroot or sudo), which is left to the
 1821 script developer.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-patches"></a>9.8. Adding project-specific patches</h2></div></div></div><p>It is sometimes useful to apply <span class="emphasis"><em>extra</em></span> patches to packages - on top of
 1822 those provided in Buildroot. This might be used to support custom
 1823 features in a project, for example, or when working on a new
 1824 architecture.</p><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> configuration option can be used to specify
 1825 a space separated list of one or more directories containing package
 1826 patches.</p><p>For a specific version <code class="literal">&lt;packageversion&gt;</code> of a specific package
 1827 <code class="literal">&lt;packagename&gt;</code>, patches are applied from <code class="literal">BR2_GLOBAL_PATCH_DIR</code> as
 1828 follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p class="simpara">
 1829 For every directory - <code class="literal">&lt;global-patch-dir&gt;</code> - that exists in
 1830   <code class="literal">BR2_GLOBAL_PATCH_DIR</code>, a <code class="literal">&lt;package-patch-dir&gt;</code> will be determined as
 1831   follows:
 1832 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1833 <code class="literal">&lt;global-patch-dir&gt;/&lt;packagename&gt;/&lt;packageversion&gt;/</code> if the
 1834   directory exists.
 1835 </li><li class="listitem">
 1836 Otherwise, <code class="literal">&lt;global-patch-dir&gt;/&lt;packagename&gt;</code> if the directory
 1837   exists.
 1838 </li></ul></div></li><li class="listitem"><p class="simpara">
 1839 Patches will then be applied from a <code class="literal">&lt;package-patch-dir&gt;</code> as
 1840   follows:
 1841 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1842 If a <code class="literal">series</code> file exists in the package directory, then patches are
 1843   applied according to the <code class="literal">series</code> file;
 1844 </li><li class="listitem">
 1845 Otherwise, patch files matching <code class="literal">*.patch</code> are applied in
 1846   alphabetical order.  So, to ensure they are applied in the right
 1847   order, it is highly recommended to name the patch files like this:
 1848   <code class="literal">&lt;number&gt;-&lt;description&gt;.patch</code>, where <code class="literal">&lt;number&gt;</code> refers to the
 1849   <span class="emphasis"><em>apply order</em></span>.
 1850 </li></ul></div></li></ol></div><p>For information about how patches are applied for a package, see
 1851 <a class="xref" href="#patch-apply-order" title="19.2. How patches are applied">Section 19.2, “How patches are applied”</a></p><p>The <code class="literal">BR2_GLOBAL_PATCH_DIR</code> option is the preferred method for
 1852 specifying a custom patch directory for packages. It can be used to
 1853 specify a patch directory for any package in buildroot. It should also
 1854 be used in place of the custom patch directory options that are
 1855 available for packages such as U-Boot and Barebox. By doing this, it
 1856 will allow a user to manage their patches from one top-level
 1857 directory.</p><p>The exception to <code class="literal">BR2_GLOBAL_PATCH_DIR</code> being the preferred method for
 1858 specifying custom patches is <code class="literal">BR2_LINUX_KERNEL_PATCH</code>.
 1859 <code class="literal">BR2_LINUX_KERNEL_PATCH</code> should be used to specify kernel patches that
 1860 are available at a URL. <span class="strong"><strong>Note:</strong></span> <code class="literal">BR2_LINUX_KERNEL_PATCH</code> specifies kernel
 1861 patches that are applied after patches available in <code class="literal">BR2_GLOBAL_PATCH_DIR</code>,
 1862 as it is done from a post-patch hook of the Linux package.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customize-packages"></a>9.9. Adding project-specific packages</h2></div></div></div><p>In general, any new package should be added directly in the <code class="literal">package</code>
 1863 directory and submitted to the Buildroot upstream project. How to add
 1864 packages to Buildroot in general is explained in full detail in
 1865 <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a> and will not be repeated here. However, your
 1866 project may need some proprietary packages that cannot be upstreamed.
 1867 This section will explain how you can keep such project-specific
 1868 packages in a project-specific directory.</p><p>As shown in <a class="xref" href="#customize-dir-structure" title="9.1. Recommended directory structure">Section 9.1, “Recommended directory structure”</a>, the recommended location for
 1869 project-specific packages is <code class="literal">package/&lt;company&gt;/</code>. If you are using the
 1870 br2-external tree feature (see <a class="xref" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">Section 9.2, “Keeping customizations outside of Buildroot”</a>) the recommended
 1871 location is to put them in a sub-directory named <code class="literal">package/</code> in your
 1872 br2-external tree.</p><p>However, Buildroot will not be aware of the packages in this location,
 1873 unless we perform some additional steps. As explained in
 1874 <a class="xref" href="#adding-packages" title="Chapter 18. Adding new packages to Buildroot">Chapter 18, <em>Adding new packages to Buildroot</em></a>, a package in Buildroot basically consists of two
 1875 files: a <code class="literal">.mk</code> file (describing how to build the package) and a
 1876 <code class="literal">Config.in</code> file (describing the configuration options for this
 1877 package).</p><p>Buildroot will automatically include the <code class="literal">.mk</code> files in first-level
 1878 subdirectories of the <code class="literal">package</code> directory (using the pattern
 1879 <code class="literal">package/*/*.mk</code>). If we want Buildroot to include <code class="literal">.mk</code> files from
 1880 deeper subdirectories (like <code class="literal">package/&lt;company&gt;/package1/</code>) then we
 1881 simply have to add a <code class="literal">.mk</code> file in a first-level subdirectory that
 1882 includes these additional <code class="literal">.mk</code> files. Therefore, create a file
 1883 <code class="literal">package/&lt;company&gt;/&lt;company&gt;.mk</code> with following contents (assuming you
 1884 have only one extra directory level below <code class="literal">package/&lt;company&gt;/</code>):</p><pre class="screen">include $(sort $(wildcard package/&lt;company&gt;/*/*.mk))</pre><p>For the <code class="literal">Config.in</code> files, create a file <code class="literal">package/&lt;company&gt;/Config.in</code>
 1885 that includes the <code class="literal">Config.in</code> files of all your packages. An exhaustive
 1886 list has to be provided since wildcards are not supported in the source command of kconfig.
 1887 For example:</p><pre class="screen">source "package/&lt;company&gt;/package1/Config.in"
 1888 source "package/&lt;company&gt;/package2/Config.in"</pre><p>Include this new file <code class="literal">package/&lt;company&gt;/Config.in</code> from
 1889 <code class="literal">package/Config.in</code>, preferably in a company-specific menu to make
 1890 merges with future Buildroot versions easier.</p><p>If using a br2-external tree, refer to <a class="xref" href="#outside-br-custom" title="9.2. Keeping customizations outside of Buildroot">Section 9.2, “Keeping customizations outside of Buildroot”</a> for how
 1891 to fill in those files.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_quick_guide_to_storing_your_project_specific_customizations"></a>9.10. Quick guide to storing your project-specific customizations</h2></div></div></div><p>Earlier in this chapter, the different methods for making
 1892 project-specific customizations have been described. This section will
 1893 now summarize all this by providing step-by-step instructions to storing your
 1894 project-specific customizations. Clearly, the steps that are not relevant to
 1895 your project can be skipped.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
 1896 <code class="literal">make menuconfig</code> to configure toolchain, packages and kernel.
 1897 </li><li class="listitem">
 1898 <code class="literal">make linux-menuconfig</code> to update the kernel config, similar for
 1899    other configuration like busybox, uclibc, …
 1900 </li><li class="listitem">
 1901 <code class="literal">mkdir -p board/&lt;manufacturer&gt;/&lt;boardname&gt;</code>
 1902 </li><li class="listitem"><p class="simpara">
 1903 Set the following options to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/&lt;package&gt;.config</code>
 1904    (as far as they are relevant):
 1905 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1906 <code class="literal">BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE</code>
 1907 </li><li class="listitem">
 1908 <code class="literal">BR2_PACKAGE_BUSYBOX_CONFIG</code>
 1909 </li><li class="listitem">
 1910 <code class="literal">BR2_UCLIBC_CONFIG</code>
 1911 </li><li class="listitem">
 1912 <code class="literal">BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE</code>
 1913 </li><li class="listitem">
 1914 <code class="literal">BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE</code>
 1915 </li><li class="listitem">
 1916 <code class="literal">BR2_TARGET_UBOOT_CUSTOM_CONFIG_FILE</code>
 1917 </li></ul></div></li><li class="listitem"><p class="simpara">
 1918 Write the configuration files:
 1919 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1920 <code class="literal">make linux-update-defconfig</code>
 1921 </li><li class="listitem">
 1922 <code class="literal">make busybox-update-config</code>
 1923 </li><li class="listitem">
 1924 <code class="literal">make uclibc-update-config</code>
 1925 </li><li class="listitem">
 1926 <code class="literal">cp &lt;output&gt;/build/at91bootstrap3-*/.config
 1927      board/&lt;manufacturer&gt;/&lt;boardname&gt;/at91bootstrap3.config</code>
 1928 </li><li class="listitem">
 1929 <code class="literal">make barebox-update-defconfig</code>
 1930 </li><li class="listitem">
 1931 <code class="literal">make uboot-update-defconfig</code>
 1932 </li></ul></div></li><li class="listitem">
 1933 Create <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay/</code> and fill it
 1934    with additional files you need on your rootfs, e.g.
 1935    <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay/etc/inittab</code>.
 1936    Set <code class="literal">BR2_ROOTFS_OVERLAY</code>
 1937    to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/rootfs-overlay</code>.
 1938 </li><li class="listitem">
 1939 Create a post-build script
 1940    <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/post_build.sh</code>. Set
 1941    <code class="literal">BR2_ROOTFS_POST_BUILD_SCRIPT</code> to
 1942    <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/post_build.sh</code>
 1943 </li><li class="listitem">
 1944 If additional setuid permissions have to be set or device nodes have
 1945    to be created, create <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/device_table.txt</code>
 1946    and add that path to <code class="literal">BR2_ROOTFS_DEVICE_TABLE</code>.
 1947 </li><li class="listitem">
 1948 If additional user accounts have to be created, create
 1949    <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/users_table.txt</code> and add that path
 1950    to <code class="literal">BR2_ROOTFS_USERS_TABLES</code>.
 1951 </li><li class="listitem">
 1952 To add custom patches to certain packages, set <code class="literal">BR2_GLOBAL_PATCH_DIR</code>
 1953    to <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;/patches/</code> and add your patches
 1954    for each package in a subdirectory named after the package. Each
 1955    patch should be called <code class="literal">&lt;packagename&gt;-&lt;num&gt;-&lt;description&gt;.patch</code>.
 1956 </li><li class="listitem">
 1957 Specifically for the Linux kernel, there also exists the option
 1958    <code class="literal">BR2_LINUX_KERNEL_PATCH</code> with as main advantage that it can also
 1959    download patches from a URL. If you do not need this,
 1960    <code class="literal">BR2_GLOBAL_PATCH_DIR</code> is preferred. U-Boot, Barebox, at91bootstrap
 1961    and at91bootstrap3 also have separate options, but these do not
 1962    provide any advantage over <code class="literal">BR2_GLOBAL_PATCH_DIR</code> and will likely be
 1963    removed in the future.
 1964 </li><li class="listitem">
 1965 If you need to add project-specific packages, create
 1966    <code class="literal">package/&lt;manufacturer&gt;/</code> and place your packages in that
 1967    directory. Create an overall <code class="literal">&lt;manufacturer&gt;.mk</code> file that
 1968    includes the <code class="literal">.mk</code> files of all your packages. Create an overall
 1969    <code class="literal">Config.in</code> file that sources the <code class="literal">Config.in</code> files of all your
 1970    packages. Include this <code class="literal">Config.in</code> file from Buildroot’s
 1971    <code class="literal">package/Config.in</code> file.
 1972 </li><li class="listitem">
 1973 <code class="literal">make savedefconfig</code> to save the buildroot configuration.
 1974 </li><li class="listitem">
 1975 <code class="literal">cp defconfig configs/&lt;boardname&gt;_defconfig</code>
 1976 </li></ol></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="selinux"></a>Chapter 10. Using SELinux in Buildroot</h2></div></div></div><p><a class="ulink" href="https://selinuxproject.org" target="_top">SELinux</a> is a Linux kernel security module
 1977 enforcing access control policies. In addition to the traditional file
 1978 permissions and access control lists, <code class="literal">SELinux</code> allows to write rules
 1979 for users or processes to access specific functions of resources
 1980 (files, sockets…).</p><p><span class="emphasis"><em>SELinux</em></span> has three modes of operation:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1981 <span class="emphasis"><em>Disabled</em></span>: the policy is not applied
 1982 </li><li class="listitem">
 1983 <span class="emphasis"><em>Permissive</em></span>: the policy is applied, and non-authorized actions are
 1984   simply logged. This mode is often used for troubleshooting SELinux
 1985   issues.
 1986 </li><li class="listitem">
 1987 <span class="emphasis"><em>Enforcing</em></span>: the policy is applied, and non-authorized actions are
 1988   denied
 1989 </li></ul></div><p>In Buildroot the mode of operation is controlled by the
 1990 <code class="literal">BR2_PACKAGE_REFPOLICY_POLICY_STATE_*</code> configuration options. The
 1991 Linux kernel also has various configuration options that affect how
 1992 <code class="literal">SELinux</code> is enabled (see <code class="literal">security/selinux/Kconfig</code> in the Linux
 1993 kernel sources).</p><p>By default in Buildroot the <code class="literal">SELinux</code> policy is provided by the
 1994 upstream <a class="ulink" href="https://github.com/SELinuxProject/refpolicy" target="_top">refpolicy</a>
 1995 project, enabled with <code class="literal">BR2_PACKAGE_REFPOLICY</code>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="enabling-selinux"></a>10.1. Enabling SELinux support</h2></div></div></div><p>To have proper support for <code class="literal">SELinux</code> in a Buildroot generated system,
 1996 the following configuration options must be enabled:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 1997 <code class="literal">BR2_PACKAGE_LIBSELINUX</code>
 1998 </li><li class="listitem">
 1999 <code class="literal">BR2_PACKAGE_REFPOLICY</code>
 2000 </li></ul></div><p>In addition, your filesystem image format must support extended
 2001 attributes.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="selinux-policy-tweaking"></a>10.2. SELinux policy tweaking</h2></div></div></div><p>The <code class="literal">SELinux refpolicy</code> contains modules that can be enabled or
 2002 disabled when being built. Each module provide a number of <code class="literal">SELinux</code>
 2003 rules. In Buildroot the non-base modules are disabled by default and
 2004 several ways to enable such modules are provided:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2005 Packages can enable a list of <code class="literal">SELinux</code> modules within the <code class="literal">refpolicy</code> using
 2006   the <code class="literal">&lt;packagename&gt;_SELINUX_MODULES</code> variable.
 2007 </li><li class="listitem">
 2008 Packages can provide additional <code class="literal">SELinux</code> modules by putting them (.fc, .if
 2009   and .te files) in <code class="literal">package/&lt;packagename&gt;/selinux/</code>.
 2010 </li><li class="listitem">
 2011 Extra <code class="literal">SELinux</code> modules can be added in directories pointed by the
 2012   <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DIRS</code> configuration option.
 2013 </li><li class="listitem">
 2014 Additional modules in the <code class="literal">refpolicy</code> can be enabled if listed in the
 2015   <code class="literal">BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES</code> configuration option.
 2016 </li></ul></div><p>Buildroot also allows to completely override the <code class="literal">refpolicy</code>. This
 2017 allows to provide a full custom policy designed specifically for a
 2018 given system. When going this way, all of the above mechanisms are
 2019 disabled: no extra <code class="literal">SElinux</code> module is added to the policy, and all
 2020 the available modules within the custom policy are enabled and built
 2021 into the final binary policy. The custom policy must be a fork of the
 2022 official <a class="ulink" href="https://github.com/SELinuxProject/refpolicy" target="_top">refpolicy</a>.</p><p>In order to fully override the <code class="literal">refpolicy</code> the following configuration
 2023 variables have to be set:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2024 <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_GIT</code>
 2025 </li><li class="listitem">
 2026 <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL</code>
 2027 </li><li class="listitem">
 2028 <code class="literal">BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION</code>
 2029 </li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_frequently_asked_questions_amp_troubleshooting"></a>Chapter 11. Frequently Asked Questions &amp; Troubleshooting</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-boot-hang-after-starting"></a>11.1. The boot hangs after <span class="emphasis"><em>Starting network…</em></span></h2></div></div></div><p>If the boot process seems to hang after the following messages
 2030 (messages not necessarily exactly similar, depending on the list of
 2031 packages selected):</p><pre class="screen">Freeing init memory: 3972K
 2032 Initializing random number generator... done.
 2033 Starting network...
 2034 Starting dropbear sshd: generating rsa key... generating dsa key... OK</pre><p>then it means that your system is running, but didn’t start a shell on
 2035 the serial console. In order to have the system start a shell on your
 2036 serial console, you have to go into the Buildroot configuration, in
 2037 <code class="literal">System configuration</code>, modify <code class="literal">Run a getty (login prompt) after boot</code>
 2038 and set the appropriate port and baud rate in the <code class="literal">getty options</code>
 2039 submenu. This will automatically tune the <code class="literal">/etc/inittab</code> file of the
 2040 generated system so that a shell starts on the correct serial port.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-compiler-on-target"></a>11.2. Why is there no compiler on the target?</h2></div></div></div><p>It has been decided that support for the <span class="emphasis"><em>native compiler on the
 2041 target</em></span> would be stopped from the Buildroot-2012.11 release because:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2042 this feature was neither maintained nor tested, and often broken;
 2043 </li><li class="listitem">
 2044 this feature was only available for Buildroot toolchains;
 2045 </li><li class="listitem">
 2046 Buildroot mostly targets <span class="emphasis"><em>small</em></span> or <span class="emphasis"><em>very small</em></span> target hardware
 2047   with limited resource onboard (CPU, ram, mass-storage), for which
 2048   compiling on the target does not make much sense;
 2049 </li><li class="listitem">
 2050 Buildroot aims at easing the cross-compilation, making native
 2051   compilation on the target unnecessary.
 2052 </li></ul></div><p>If you need a compiler on your target anyway, then Buildroot is not
 2053 suitable for your purpose. In such case, you need a <span class="emphasis"><em>real
 2054 distribution</em></span> and you should opt for something like:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2055 <a class="ulink" href="http://www.openembedded.org" target="_top">openembedded</a>
 2056 </li><li class="listitem">
 2057 <a class="ulink" href="https://www.yoctoproject.org" target="_top">yocto</a>
 2058 </li><li class="listitem">
 2059 <a class="ulink" href="http://www.emdebian.org" target="_top">emdebian</a>
 2060 </li><li class="listitem">
 2061 <a class="ulink" href="https://fedoraproject.org/wiki/Architectures" target="_top">Fedora</a>
 2062 </li><li class="listitem">
 2063 <a class="ulink" href="http://en.opensuse.org/Portal:ARM" target="_top">openSUSE ARM</a>
 2064 </li><li class="listitem">
 2065 <a class="ulink" href="http://archlinuxarm.org" target="_top">Arch Linux ARM</a>
 2066 </li><li class="listitem">
 2068 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-dev-files-on-target"></a>11.3. Why are there no development files on the target?</h2></div></div></div><p>Since there is no compiler available on the target (see
 2069 <a class="xref" href="#faq-no-compiler-on-target" title="11.2. Why is there no compiler on the target?">Section 11.2, “Why is there no compiler on the target?”</a>), it does not make sense to waste
 2070 space with headers or static libraries.</p><p>Therefore, those files are always removed from the target since the
 2071 Buildroot-2012.11 release.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-doc-on-target"></a>11.4. Why is there no documentation on the target?</h2></div></div></div><p>Because Buildroot mostly targets <span class="emphasis"><em>small</em></span> or <span class="emphasis"><em>very small</em></span> target
 2072 hardware with limited resource onboard (CPU, ram, mass-storage), it
 2073 does not make sense to waste space with the documentation data.</p><p>If you need documentation data on your target anyway, then Buildroot
 2074 is not suitable for your purpose, and you should look for a <span class="emphasis"><em>real
 2075 distribution</em></span> (see: <a class="xref" href="#faq-no-compiler-on-target" title="11.2. Why is there no compiler on the target?">Section 11.2, “Why is there no compiler on the target?”</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-why-not-visible-package"></a>11.5. Why are some packages not visible in the Buildroot config menu?</h2></div></div></div><p>If a package exists in the Buildroot tree and does not appear in the
 2076 config menu, this most likely means that some of the package’s
 2077 dependencies are not met.</p><p>To know more about the dependencies of a package, search for the
 2078 package symbol in the config menu (see <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a>).</p><p>Then, you may have to recursively enable several options (which
 2079 correspond to the unmet dependencies) to finally be able to select
 2080 the package.</p><p>If the package is not visible due to some unmet toolchain options,
 2081 then you should certainly run a full rebuild (see <a class="xref" href="#make-tips" title="8.1. make tips">Section 8.1, “<span class="emphasis"><em>make</em></span> tips”</a> for
 2082 more explanations).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-why-not-use-target-as-chroot"></a>11.6. Why not use the target directory as a chroot directory?</h2></div></div></div><p>There are plenty of reasons to <span class="strong"><strong>not</strong></span> use the target directory a chroot
 2083 one, among these:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2084 file ownerships, modes and permissions are not correctly set in the
 2085   target directory;
 2086 </li><li class="listitem">
 2087 device nodes are not created in the target directory.
 2088 </li></ul></div><p>For these reasons, commands run through chroot, using the target
 2089 directory as the new root, will most likely fail.</p><p>If you want to run the target filesystem inside a chroot, or as an NFS
 2090 root, then use the tarball image generated in <code class="literal">images/</code> and extract it
 2091 as root.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-no-binary-packages"></a>11.7. Why doesn’t Buildroot generate binary packages (.deb, .ipkg…)?</h2></div></div></div><p>One feature that is often discussed on the Buildroot list is the
 2092 general topic of "package management". To summarize, the idea
 2093 would be to add some tracking of which Buildroot package installs
 2094 what files, with the goals of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2095 being able to remove files installed by a package when this package
 2096    gets unselected from the menuconfig;
 2097 </li><li class="listitem">
 2098 being able to generate binary packages (ipk or other format) that
 2099    can be installed on the target without re-generating a new root
 2100    filesystem image.
 2101 </li></ul></div><p>In general, most people think it is easy to do: just track which package
 2102 installed what and remove it when the package is unselected. However, it
 2103 is much more complicated than that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2104 It is not only about the <code class="literal">target/</code> directory, but also the sysroot in
 2105    <code class="literal">host/&lt;tuple&gt;/sysroot</code> and the <code class="literal">host/</code> directory itself. All files
 2106    installed in those directories by various packages must be tracked.
 2107 </li><li class="listitem">
 2108 When a package is unselected from the configuration, it is not
 2109    sufficient to remove just the files it installed. One must also
 2110    remove all its reverse dependencies (i.e. packages relying on it)
 2111    and rebuild all those packages. For example, package A depends
 2112    optionally on the OpenSSL library. Both are selected, and Buildroot
 2113    is built. Package A is built with crypto support using OpenSSL.
 2114    Later on, OpenSSL gets unselected from the configuration, but
 2115    package A remains (since OpenSSL is an optional dependency, this
 2116    is possible.) If only OpenSSL files are removed, then the files
 2117    installed by package A are broken: they use a library that is no
 2118    longer present on the target. Although this is technically doable,
 2119    it adds a lot of complexity to Buildroot, which goes against the
 2120    simplicity we try to stick to.
 2121 </li><li class="listitem">
 2122 In addition to the previous problem, there is the case where the
 2123    optional dependency is not even known to Buildroot. For example,
 2124    package A in version 1.0 never used OpenSSL, but in version 2.0 it
 2125    automatically uses OpenSSL if available. If the Buildroot .mk file
 2126    hasn’t been updated to take this into account, then package A will
 2127    not be part of the reverse dependencies of OpenSSL and will not be
 2128    removed and rebuilt when OpenSSL is removed. For sure, the .mk file
 2129    of package A should be fixed to mention this optional dependency,
 2130    but in the mean time, you can have non-reproducible behaviors.
 2131 </li><li class="listitem">
 2132 The request is to also allow changes in the menuconfig to be
 2133    applied on the output directory without having to rebuild
 2134    everything from scratch. However, this is very difficult to achieve
 2135    in a reliable way: what happens when the suboptions of a package
 2136    are changed (we would have to detect this, and rebuild the package
 2137    from scratch and potentially all its reverse dependencies), what
 2138    happens if toolchain options are changed, etc. At the moment, what
 2139    Buildroot does is clear and simple so its behaviour is very
 2140    reliable and it is easy to support users. If configuration changes
 2141    done in menuconfig are applied after the next make, then it has to
 2142    work correctly and properly in all situations, and not have some
 2143    bizarre corner cases. The risk is to get bug reports like "I have
 2144    enabled package A, B and C, then ran make, then disabled package
 2145    C and enabled package D and ran make, then re-enabled package C
 2146    and enabled package E and then there is a build failure". Or worse
 2147    "I did some configuration, then built, then did some changes,
 2148    built, some more changes, built, some more changes, built, and now
 2149    it fails, but I don’t remember all the changes I did and in which
 2150    order". This will be impossible to support.
 2151 </li></ul></div><p>For all these reasons, the conclusion is that adding tracking of
 2152 installed files to remove them when the package is unselected, or to
 2153 generate a repository of binary packages, is something that is very
 2154 hard to achieve reliably and will add a lot of complexity.</p><p>On this matter, the Buildroot developers make this position statement:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2155 Buildroot strives to make it easy to generate a root filesystem (hence
 2156    the name, by the way.) That is what we want to make Buildroot good at:
 2157    building root filesystems.
 2158 </li><li class="listitem">
 2159 Buildroot is not meant to be a distribution (or rather, a distribution
 2160    generator.) It is the opinion of most Buildroot developers that this
 2161    is not a goal we should pursue. We believe that there are other tools
 2162    better suited to generate a distro than Buildroot is. For example,
 2163    <a class="ulink" href="http://openembedded.org/" target="_top">Open Embedded</a>, or <a class="ulink" href="https://openwrt.org/" target="_top">openWRT</a>,
 2164    are such tools.
 2165 </li><li class="listitem">
 2166 We prefer to push Buildroot in a direction that makes it easy (or even
 2167    easier) to generate complete root filesystems. This is what makes
 2168    Buildroot stands out in the crowd (among other things, of course!)
 2169 </li><li class="listitem">
 2170 We believe that for most embedded Linux systems, binary packages are
 2171    not necessary, and potentially harmful. When binary packages are
 2172    used, it means that the system can be partially upgraded, which
 2173    creates an enormous number of possible combinations of package
 2174    versions that should be tested before doing the upgrade on the
 2175    embedded device. On the other hand, by doing complete system
 2176    upgrades by upgrading the entire root filesystem image at once,
 2177    the image deployed to the embedded system is guaranteed to really
 2178    be the one that has been tested and validated.
 2179 </li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="faq-speeding-up-build"></a>11.8. How to speed-up the build process?</h2></div></div></div><p>Since Buildroot often involves doing full rebuilds of the entire
 2180 system that can be quite long, we provide below a number of tips to
 2181 help reduce the build time:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2182 Use a pre-built external toolchain instead of the default Buildroot
 2183    internal toolchain. By using a pre-built Linaro toolchain (on ARM)
 2184    or a Sourcery CodeBench toolchain (for ARM, x86, x86-64, MIPS,
 2185    etc.), you will save the build time of the toolchain at each
 2186    complete rebuild, approximately 15 to 20 minutes. Note that
 2187    temporarily using an external toolchain does not prevent you to
 2188    switch back to an internal toolchain (that may provide a higher
 2189    level of customization) once the rest of your system is working;
 2190 </li><li class="listitem">
 2191 Use the <code class="literal">ccache</code> compiler cache (see: <a class="xref" href="#ccache" title="8.14.3. Using ccache in Buildroot">Section 8.14.3, “Using <code class="literal">ccache</code> in Buildroot”</a>);
 2192 </li><li class="listitem">
 2193 Learn about rebuilding only the few packages you actually care
 2194    about (see <a class="xref" href="#rebuild-pkg" title="8.3. Understanding how to rebuild packages">Section 8.3, “Understanding how to rebuild packages”</a>), but beware that sometimes full
 2195    rebuilds are anyway necessary (see <a class="xref" href="#full-rebuild" title="8.2. Understanding when a full rebuild is necessary">Section 8.2, “Understanding when a full rebuild is necessary”</a>);
 2196 </li><li class="listitem">
 2197 Make sure you are not using a virtual machine for the Linux system
 2198    used to run Buildroot. Most of the virtual machine technologies are
 2199    known to cause a significant performance impact on I/O, which is
 2200    really important for building source code;
 2201 </li><li class="listitem">
 2202 Make sure that you’re using only local files: do not attempt to do
 2203    a build over NFS, which significantly slows down the build. Having
 2204    the Buildroot download folder available locally also helps a bit.
 2205 </li><li class="listitem">
 2206 Buy new hardware. SSDs and lots of RAM are key to speeding up the
 2207    builds.
 2208 </li><li class="listitem">
 2209 Experiment with top-level parallel build, see
 2210    <a class="xref" href="#top-level-parallel-build" title="8.12. Top-level parallel build">Section 8.12, “Top-level parallel build”</a>.
 2211 </li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_known_issues"></a>Chapter 12. Known issues</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2212 It is not possible to pass extra linker options via <code class="literal">BR2_TARGET_LDFLAGS</code>
 2213   if such options contain a <code class="literal">$</code> sign. For example, the following is known
 2214   to break: <code class="literal">BR2_TARGET_LDFLAGS="-Wl,-rpath='$ORIGIN/../lib'"</code>
 2215 </li><li class="listitem">
 2216 The <code class="literal">libffi</code> package is not supported on the SuperH 2 and ARC
 2217   architectures.
 2218 </li><li class="listitem">
 2219 The <code class="literal">prboom</code> package triggers a compiler failure with the SuperH 4
 2220   compiler from Sourcery CodeBench, version 2012.09.
 2221 </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="legal-info"></a>Chapter 13. Legal notice and licensing</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_complying_with_open_source_licenses"></a>13.1. Complying with open source licenses</h2></div></div></div><p>All of the end products of Buildroot (toolchain, root filesystem, kernel,
 2222 bootloaders) contain open source software, released under various licenses.</p><p>Using open source software gives you the freedom to build rich embedded
 2223 systems, choosing from a wide range of packages, but also imposes some
 2224 obligations that you must know and honour.
 2225 Some licenses require you to publish the license text in the documentation of
 2226 your product. Others require you to redistribute the source code of the
 2227 software to those that receive your product.</p><p>The exact requirements of each license are documented in each package, and
 2228 it is your responsibility (or that of your legal office) to comply with those
 2229 requirements.
 2230 To make this easier for you, Buildroot can collect for you some material you
 2231 will probably need. To produce this material, after you have configured
 2232 Buildroot with <code class="literal">make menuconfig</code>, <code class="literal">make xconfig</code> or <code class="literal">make gconfig</code>, run:</p><pre class="screen">make legal-info</pre><p>Buildroot will collect legally-relevant material in your output directory,
 2233 under the <code class="literal">legal-info/</code> subdirectory.
 2234 There you will find:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2235 A <code class="literal">README</code> file, that summarizes the produced material and contains warnings
 2236   about material that Buildroot could not produce.
 2237 </li><li class="listitem">
 2238 <code class="literal">buildroot.config</code>: this is the Buildroot configuration file that is usually
 2239   produced with <code class="literal">make menuconfig</code>, and which is necessary to reproduce the
 2240   build.
 2241 </li><li class="listitem">
 2242 The source code for all packages; this is saved in the <code class="literal">sources/</code> and
 2243   <code class="literal">host-sources/</code> subdirectories for target and host packages respectively.
 2244   The source code for packages that set <code class="literal">&lt;PKG&gt;_REDISTRIBUTE = NO</code> will not be
 2245   saved.
 2246   Patches that were applied are also saved, along with a file named <code class="literal">series</code>
 2247   that lists the patches in the order they were applied. Patches are under the
 2248   same license as the files that they modify.
 2249   Note: Buildroot applies additional patches to Libtool scripts of
 2250   autotools-based packages. These patches can be found under
 2251   <code class="literal">support/libtool</code> in the Buildroot source and, due to technical
 2252   limitations, are not saved with the package sources. You may need to
 2253   collect them manually.
 2254 </li><li class="listitem">
 2255 A manifest file (one for host and one for target packages) listing the
 2256   configured packages, their version, license and related information.
 2257   Some of this information might not be defined in Buildroot; such items are
 2258   marked as "unknown".
 2259 </li><li class="listitem">
 2260 The license texts of all packages, in the <code class="literal">licenses/</code> and <code class="literal">host-licenses/</code>
 2261   subdirectories for target and host packages respectively.
 2262   If the license file(s) are not defined in Buildroot, the file is not produced
 2263   and a warning in the <code class="literal">README</code> indicates this.
 2264 </li></ul></div><p>Please note that the aim of the <code class="literal">legal-info</code> feature of Buildroot is to
 2265 produce all the material that is somehow relevant for legal compliance with the
 2266 package licenses. Buildroot does not try to produce the exact material that
 2267 you must somehow make public. Certainly, more material is produced than is
 2268 needed for a strict legal compliance. For example, it produces the source code
 2269 for packages released under BSD-like licenses, that you are not required to
 2270 redistribute in source form.</p><p>Moreover, due to technical limitations, Buildroot does not produce some
 2271 material that you will or may need, such as the toolchain source code for
 2272 some of the external toolchains and the Buildroot source code itself.
 2273 When you run <code class="literal">make legal-info</code>, Buildroot produces warnings in the <code class="literal">README</code>
 2274 file to inform you of relevant material that could not be saved.</p><p>Finally, keep in mind that the output of <code class="literal">make legal-info</code> is based on
 2275 declarative statements in each of the packages recipes. The Buildroot
 2276 developers try to do their best to keep those declarative statements as
 2277 accurate as possible, to the best of their knowledge. However, it is very
 2278 well possible that those declarative statements are not all fully accurate
 2279 nor exhaustive. You (or your legal department) <span class="emphasis"><em>have</em></span> to check the output
 2280 of <code class="literal">make legal-info</code> before using it as your own compliance delivery. See
 2281 the <span class="emphasis"><em>NO WARRANTY</em></span> clauses (clauses 11 and 12) in the <code class="literal">COPYING</code> file at the
 2282 root of the Buildroot distribution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="legal-info-buildroot"></a>13.2. Complying with the Buildroot license</h2></div></div></div><p>Buildroot itself is an open source software, released under the
 2283 <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU General
 2284 Public License, version 2</a> or (at your option) any later version, with
 2285 the exception of the package patches detailed below.
 2286 However, being a build system, it is not normally part of the end product:
 2287 if you develop the root filesystem, kernel, bootloader or toolchain for a
 2288 device, the code of Buildroot is only present on the development machine, not
 2289 in the device storage.</p><p>Nevertheless, the general view of the Buildroot developers is that you should
 2290 release the Buildroot source code along with the source code of other packages
 2291 when releasing a product that contains GPL-licensed software.
 2292 This is because the
 2293 <a class="ulink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GNU GPL</a>
 2294 defines the "<span class="emphasis"><em>complete source code</em></span>" for an executable work as "<span class="emphasis"><em>all the
 2295 source code for all modules it contains, plus any associated interface
 2296 definition files, plus the scripts used to control compilation and installation
 2297 of the executable</em></span>".
 2298 Buildroot is part of the <span class="emphasis"><em>scripts used to control compilation and
 2299 installation of the executable</em></span>, and as such it is considered part of the
 2300 material that must be redistributed.</p><p>Keep in mind that this is only the Buildroot developers' opinion, and you
 2301 should consult your legal department or lawyer in case of any doubt.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_patches_to_packages"></a>13.2.1. Patches to packages</h3></div></div></div><p>Buildroot also bundles patch files, which are applied to the sources
 2302 of the various packages. Those patches are not covered by the license
 2303 of Buildroot. Instead, they are covered by the license of the software
 2304 to which the patches are applied. When said software is available
 2305 under multiple licenses, the Buildroot patches are only provided under
 2306 the publicly accessible licenses.</p><p>See <a class="xref" href="#patch-policy" title="Chapter 19. Patching a package">Chapter 19, <em>Patching a package</em></a> for the technical details.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_beyond_buildroot"></a>Chapter 14. Beyond Buildroot</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_boot_the_generated_images"></a>14.1. Boot the generated images</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_nfs_boot"></a>14.1.1. NFS boot</h3></div></div></div><p>To achieve NFS-boot, enable <span class="emphasis"><em>tar root filesystem</em></span> in the <span class="emphasis"><em>Filesystem
 2307 images</em></span> menu.</p><p>After a complete build, just run the following commands to setup the
 2308 NFS-root directory:</p><pre class="screen">sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir</pre><p>Remember to add this path to <code class="literal">/etc/exports</code>.</p><p>Then, you can execute a NFS-boot from your target.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_live_cd"></a>14.1.2. Live CD</h3></div></div></div><p>To build a live CD image, enable the <span class="emphasis"><em>iso image</em></span> option in the
 2309 <span class="emphasis"><em>Filesystem images</em></span> menu. Note that this option is only available on
 2310 the x86 and x86-64 architectures, and if you are building your kernel
 2311 with Buildroot.</p><p>You can build a live CD image with either IsoLinux, Grub or Grub 2 as
 2312 a bootloader, but only Isolinux supports making this image usable both
 2313 as a live CD and live USB (through the <span class="emphasis"><em>Build hybrid image</em></span> option).</p><p>You can test your live CD image using QEMU:</p><pre class="screen">qemu-system-i386 -cdrom output/images/rootfs.iso9660</pre><p>Or use it as a hard-drive image if it is a hybrid ISO:</p><pre class="screen">qemu-system-i386 -hda output/images/rootfs.iso9660</pre><p>It can be easily flashed to a USB drive with <code class="literal">dd</code>:</p><pre class="screen">dd if=output/images/rootfs.iso9660 of=/dev/sdb</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_chroot"></a>14.2. Chroot</h2></div></div></div><p>If you want to chroot in a generated image, then there are few thing
 2314 you should be aware of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2315 you should setup the new root from the <span class="emphasis"><em>tar root filesystem</em></span> image;
 2316 </li><li class="listitem">
 2317 either the selected target architecture is compatible with your host
 2318   machine, or you should use some <code class="literal">qemu-*</code> binary and correctly set it
 2319   within the <code class="literal">binfmt</code> properties to be able to run the binaries built
 2320   for the target on your host machine;
 2321 </li><li class="listitem">
 2322 Buildroot does not currently provide <code class="literal">host-qemu</code> and <code class="literal">binfmt</code>
 2323   correctly built and set for that kind of use.
 2324 </li></ul></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a id="_developer_guide"></a>Part III. Developer guide</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_how_buildroot_works"></a>Chapter 15. How Buildroot works</h2></div></div></div><p>As mentioned above, Buildroot is basically a set of Makefiles that
 2325 download, configure, and compile software with the correct options. It
 2326 also includes patches for various software packages - mainly the ones
 2327 involved in the cross-compilation toolchain (<code class="literal">gcc</code>, <code class="literal">binutils</code> and
 2328 <code class="literal">uClibc</code>).</p><p>There is basically one Makefile per software package, and they are
 2329 named with the <code class="literal">.mk</code> extension. Makefiles are split into many different
 2330 parts.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2331 The <code class="literal">toolchain/</code> directory contains the Makefiles
 2332   and associated files for all software related to the
 2333   cross-compilation toolchain: <code class="literal">binutils</code>, <code class="literal">gcc</code>, <code class="literal">gdb</code>,
 2334   <code class="literal">kernel-headers</code> and <code class="literal">uClibc</code>.
 2335 </li><li class="listitem">
 2336 The <code class="literal">arch/</code> directory contains the definitions for all the processor
 2337   architectures that are supported by Buildroot.
 2338 </li><li class="listitem">
 2339 The <code class="literal">package/</code> directory contains the Makefiles and
 2340   associated files for all user-space tools and libraries that Buildroot
 2341   can compile and add to the target root filesystem. There is one
 2342   sub-directory per package.
 2343 </li><li class="listitem">
 2344 The <code class="literal">linux/</code> directory contains the Makefiles and associated files for
 2345   the Linux kernel.
 2346 </li><li class="listitem">
 2347 The <code class="literal">boot/</code> directory contains the Makefiles and associated files for
 2348   the bootloaders supported by Buildroot.
 2349 </li><li class="listitem">
 2350 The <code class="literal">system/</code> directory contains support for system integration, e.g.
 2351   the target filesystem skeleton and the selection of an init system.
 2352 </li><li class="listitem">
 2353 The <code class="literal">fs/</code> directory contains the Makefiles and
 2354   associated files for software related to the generation of the
 2355   target root filesystem image.
 2356 </li></ul></div><p>Each directory contains at least 2 files:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2357 <code class="literal">something.mk</code> is the Makefile that downloads, configures,
 2358   compiles and installs the package <code class="literal">something</code>.
 2359 </li><li class="listitem">
 2360 <code class="literal">Config.in</code> is a part of the configuration tool
 2361   description file. It describes the options related to the
 2362   package.
 2363 </li></ul></div><p>The main Makefile performs the following steps (once the
 2364 configuration is done):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2365 Create all the output directories: <code class="literal">staging</code>, <code class="literal">target</code>, <code class="literal">build</code>,
 2366   etc. in the output directory (<code class="literal">output/</code> by default,
 2367   another value can be specified using <code class="literal">O=</code>)
 2368 </li><li class="listitem">
 2369 Generate the toolchain target. When an internal toolchain is used, this
 2370   means generating the cross-compilation toolchain. When an external
 2371   toolchain is used, this means checking the features of the external
 2372   toolchain and importing it into the Buildroot environment.
 2373 </li><li class="listitem">
 2374 Generate all the targets listed in the <code class="literal">TARGETS</code> variable. This
 2375   variable is filled by all the individual components'
 2376   Makefiles. Generating these targets will trigger the compilation of
 2377   the userspace packages (libraries, programs), the kernel, the
 2378   bootloader and the generation of the root filesystem images,
 2379   depending on the configuration.
 2380 </li></ul></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="_coding_style"></a>Chapter 16. Coding style</h2></div></div></div><p>Overall, these coding style rules are here to help you to add new files in
 2381 Buildroot or refactor existing ones.</p><p>If you slightly modify some existing file, the important thing is
 2382 to keep the consistency of the whole file, so you can:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2383 either follow the potentially deprecated coding style used in this
 2384 file,
 2385 </li><li class="listitem">
 2386 or entirely rework it in order to make it comply with these rules.
 2387 </li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="writing-rules-config-in"></a>16.1<code class="literal">Config.in</code> file</h2></div></div></div><p><code class="literal">Config.in</code> files contain entries for almost anything configurable in
 2388 Buildroot.</p><p>An entry has the following pattern:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
 2389         bool "libfoo"
 2390         depends on BR2_PACKAGE_LIBBAZ
 2391         select BR2_PACKAGE_LIBBAR
 2392         help
 2393           This is a comment that explains what libfoo is. The help text
 2394           should be wrapped.
 2396           http://foosoftware.org/libfoo/</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2397 The <code class="literal">bool</code>, <code class="literal">depends on</code>, <code class="literal">select</code> and <code class="literal">help</code> lines are indented
 2398   with one tab.
 2399 </li><li class="listitem">
 2400 The help text itself should be indented with one tab and two
 2401   spaces.
 2402 </li><li class="listitem">
 2403 The help text should be wrapped to fit 72 columns, where tab counts
 2404   for 8, so 62 characters in the text itself.
 2405 </li></ul></div><p>The <code class="literal">Config.in</code> files are the input for the configuration tool
 2406 used in Buildroot, which is the regular <span class="emphasis"><em>Kconfig</em></span>. For further
 2407 details about the <span class="emphasis"><em>Kconfig</em></span> language, refer to
 2408 <a class="ulink" href="http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt" target="_top">http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="writing-rules-mk"></a>16.2. The <code class="literal">.mk</code> file</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
 2409 Header: The file starts with a header. It contains the module name,
 2410 preferably in lowercase, enclosed between separators made of 80 hashes. A
 2411 blank line is mandatory after the header:
 2412 </p><pre class="screen">################################################################################
 2413 #
 2414 # libfoo
 2415 #
 2416 ################################################################################</pre></li><li class="listitem"><p class="simpara">
 2417 Assignment: use <code class="literal">=</code> preceded and followed by one space:
 2418 </p><pre class="screen">LIBFOO_VERSION = 1.0
 2419 LIBFOO_CONF_OPTS += --without-python-support</pre><p class="simpara">Do not align the <code class="literal">=</code> signs.</p></li><li class="listitem"><p class="simpara">
 2420 Indentation: use tab only:
 2421 </p><pre class="screen">define LIBFOO_REMOVE_DOC
 2422         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
 2423                 $(TARGET_DIR)/usr/share/man/man3/libfoo*
 2424 endef</pre><p class="simpara">Note that commands inside a <code class="literal">define</code> block should always start with a tab,
 2425 so <span class="emphasis"><em>make</em></span> recognizes them as commands.</p></li><li class="listitem"><p class="simpara">
 2426 Optional dependency:
 2427 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p class="simpara">
 2428 Prefer multi-line syntax.
 2429 </p><p class="simpara">YES:</p><pre class="screen">ifeq ($(BR2_PACKAGE_PYTHON),y)
 2430 LIBFOO_CONF_OPTS += --with-python-support
 2432 else
 2433 LIBFOO_CONF_OPTS += --without-python-support
 2434 endif</pre><p class="simpara">NO:</p><pre class="screen">LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
 2435 LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)</pre></li><li class="listitem">
 2436 Keep configure options and dependencies close together.
 2437 </li></ul></div></li><li class="listitem"><p class="simpara">
 2438 Optional hooks: keep hook definition and assignment together in one
 2439   if block.
 2440 </p><p class="simpara">YES:</p><pre class="screen">ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 2442         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 2443 endef
 2445 endif</pre><p class="simpara">NO:</p><pre class="screen">define LIBFOO_REMOVE_DATA
 2446         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 2447 endef
 2449 ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 2451 endif</pre></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_documentation"></a>16.3. The documentation</h2></div></div></div><p>The documentation uses the
 2452 <a class="ulink" href="http://www.methods.co.nz/asciidoc/" target="_top">asciidoc</a> format.</p><p>For further details about the asciidoc syntax, refer to
 2453 <a class="ulink" href="http://www.methods.co.nz/asciidoc/userguide.html" target="_top">http://www.methods.co.nz/asciidoc/userguide.html</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_support_scripts"></a>16.4. Support scripts</h2></div></div></div><p>Some scripts in the <code class="literal">support/</code> and <code class="literal">utils/</code> directories are written in
 2454 Python and should follow the
 2455 <a class="ulink" href="https://www.python.org/dev/peps/pep-0008/" target="_top">PEP8 Style Guide for Python Code</a>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="adding-board-support"></a>Chapter 17. Adding support for a particular board</h2></div></div></div><p>Buildroot contains basic configurations for several publicly available
 2456 hardware boards, so that users of such a board can easily build a system
 2457 that is known to work. You are welcome to add support for other boards
 2458 to Buildroot too.</p><p>To do so, you need to create a normal Buildroot configuration that
 2459 builds a basic system for the hardware: (internal) toolchain, kernel,
 2460 bootloader, filesystem and a simple BusyBox-only userspace. No specific
 2461 package should be selected: the configuration should be as minimal as
 2462 possible, and should only build a working basic BusyBox system for the
 2463 target platform. You can of course use more complicated configurations
 2464 for your internal projects, but the Buildroot project will only
 2465 integrate basic board configurations. This is because package
 2466 selections are highly application-specific.</p><p>Once you have a known working configuration, run <code class="literal">make
 2467 savedefconfig</code>. This will generate a minimal <code class="literal">defconfig</code> file at the
 2468 root of the Buildroot source tree. Move this file into the <code class="literal">configs/</code>
 2469 directory, and rename it <code class="literal">&lt;boardname&gt;_defconfig</code>. If the configuration
 2470 is a bit more complicated, it is nice to manually reformat it and
 2471 separate it into sections, with a comment before each section. Typical
 2472 sections are <span class="emphasis"><em>Architecture</em></span>, <span class="emphasis"><em>Toolchain options</em></span> (typically just linux
 2473 headers version), <span class="emphasis"><em>Firmware</em></span>, <span class="emphasis"><em>Bootloader</em></span>, <span class="emphasis"><em>Kernel</em></span>, and <span class="emphasis"><em>Filesystem</em></span>.</p><p>Always use fixed versions or commit hashes for the different
 2474 components, not the "latest" version. For example, set
 2475 <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION=y</code> and
 2476 <code class="literal">BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE</code> to the kernel version you tested
 2477 with.</p><p>It is recommended to use as much as possible upstream versions of the
 2478 Linux kernel and bootloaders, and to use as much as possible default
 2479 kernel and bootloader configurations. If they are incorrect for your
 2480 board, or no default exists, we encourage you to send fixes to the
 2481 corresponding upstream projects.</p><p>However, in the mean time, you may want to store kernel or bootloader
 2482 configuration or patches specific to your target platform. To do so,
 2483 create a directory <code class="literal">board/&lt;manufacturer&gt;</code> and a subdirectory
 2484 <code class="literal">board/&lt;manufacturer&gt;/&lt;boardname&gt;</code>. You can then store your patches
 2485 and configurations in these directories, and reference them from the main
 2486 Buildroot configuration. Refer to <a class="xref" href="#customize" title="Chapter 9. Project-specific customization">Chapter 9, <em>Project-specific customization</em></a> for more details.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="adding-packages"></a>Chapter 18. Adding new packages to Buildroot</h2></div></div></div><p>This section covers how new packages (userspace libraries or
 2487 applications) can be integrated into Buildroot. It also shows how
 2488 existing packages are integrated, which is needed for fixing issues or
 2489 tuning their configuration.</p><p>When you add a new package, be sure to test it in various conditions
 2490 (see <a class="xref" href="#testing-package" title="18.24.3. How to test your package">Section 18.24.3, “How to test your package”</a>) and also check it for coding style (see
 2491 <a class="xref" href="#check-package" title="18.24.2. How to check the coding style">Section 18.24.2, “How to check the coding style”</a>).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_package_directory"></a>18.1. Package directory</h2></div></div></div><p>First of all, create a directory under the <code class="literal">package</code> directory for
 2492 your software, for example <code class="literal">libfoo</code>.</p><p>Some packages have been grouped by topic in a sub-directory:
 2493 <code class="literal">x11r7</code>, <code class="literal">qt5</code> and <code class="literal">gstreamer</code>. If your package fits in
 2494 one of these categories, then create your package directory in these.
 2495 New subdirectories are discouraged, however.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_config_files"></a>18.2. Config files</h2></div></div></div><p>For the package to be displayed in the configuration tool, you need to
 2496 create a Config file in your package directory. There are two types:
 2497 <code class="literal">Config.in</code> and <code class="literal">Config.in.host</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_config_in_literal_file"></a>18.2.1<code class="literal">Config.in</code> file</h3></div></div></div><p>For packages used on the target, create a file named <code class="literal">Config.in</code>. This
 2498 file will contain the option descriptions related to our <code class="literal">libfoo</code> software
 2499 that will be used and displayed in the configuration tool. It should basically
 2500 contain:</p><pre class="screen">config BR2_PACKAGE_LIBFOO
 2501         bool "libfoo"
 2502         help
 2503           This is a comment that explains what libfoo is. The help text
 2504           should be wrapped.
 2506           http://foosoftware.org/libfoo/</pre><p>The <code class="literal">bool</code> line, <code class="literal">help</code> line and other metadata information about the
 2507 configuration option must be indented with one tab. The help text
 2508 itself should be indented with one tab and two spaces, lines should
 2509 be wrapped to fit 72 columns, where tab counts for 8, so 62 characters
 2510 in the text itself. The help text must mention the upstream URL of the
 2511 project after an empty line.</p><p>As a convention specific to Buildroot, the ordering of the attributes
 2512 is as follows:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
 2513 The type of option: <code class="literal">bool</code>, <code class="literal">string</code>… with the prompt
 2514 </li><li class="listitem">
 2515 If needed, the <code class="literal">default</code> value(s)
 2516 </li><li class="listitem">
 2517 Any dependencies on the target in <code class="literal">depends on</code> form
 2518 </li><li class="listitem">
 2519 Any dependencies on the toolchain in <code class="literal">depends on</code> form
 2520 </li><li class="listitem">
 2521 Any dependencies on other packages in <code class="literal">depends on</code> form
 2522 </li><li class="listitem">
 2523 Any dependency of the <code class="literal">select</code> form
 2524 </li><li class="listitem">
 2525 The help keyword and help text.
 2526 </li></ol></div><p>You can add other sub-options into a <code class="literal">if BR2_PACKAGE_LIBFOO…endif</code>
 2527 statement to configure particular things in your software. You can look at
 2528 examples in other packages. The syntax of the <code class="literal">Config.in</code> file is the same
 2529 as the one for the kernel Kconfig file. The documentation for this syntax is
 2530 available at <a class="ulink" href="http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt" target="_top">http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt</a></p><p>Finally you have to add your new <code class="literal">libfoo/Config.in</code> to
 2531 <code class="literal">package/Config.in</code> (or in a category subdirectory if you decided to
 2532 put your package in one of the existing categories). The files
 2533 included there are <span class="emphasis"><em>sorted alphabetically</em></span> per category and are <span class="emphasis"><em>NOT</em></span>
 2534 supposed to contain anything but the <span class="emphasis"><em>bare</em></span> name of the package.</p><pre class="screen">source "package/libfoo/Config.in"</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_literal_config_in_host_literal_file"></a>18.2.2<code class="literal">Config.in.host</code> file</h3></div></div></div><p>Some packages also need to be built for the host system. There are two
 2535 options here:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2536 The host package is only required to satisfy build-time
 2537   dependencies of one or more target packages. In this case, add
 2538   <code class="literal">host-foo</code> to the target package’s <code class="literal">BAR_DEPENDENCIES</code> variable. No
 2539   <code class="literal">Config.in.host</code> file should be created.
 2540 </li><li class="listitem"><p class="simpara">
 2541 The host package should be explicitly selectable by the user from
 2542   the configuration menu. In this case, create a <code class="literal">Config.in.host</code> file
 2543   for that host package:
 2544 </p><pre class="screen">config BR2_PACKAGE_HOST_FOO
 2545         bool "host foo"
 2546         help
 2547           This is a comment that explains what foo for the host is.
 2549           http://foosoftware.org/foo/</pre><p class="simpara">The same coding style and options as for the <code class="literal">Config.in</code> file are valid.</p><p class="simpara">Finally you have to add your new <code class="literal">libfoo/Config.in.host</code> to
 2550 <code class="literal">package/Config.in.host</code>. The files included there are <span class="emphasis"><em>sorted alphabetically</em></span>
 2551 and are <span class="emphasis"><em>NOT</em></span> supposed to contain anything but the <span class="emphasis"><em>bare</em></span> name of the package.</p><pre class="screen">source "package/foo/Config.in.host"</pre><p class="simpara">The host package will then be available from the <code class="literal">Host utilities</code> menu.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="depends-on-vs-select"></a>18.2.3. Choosing <code class="literal">depends on</code> or <code class="literal">select</code></h3></div></div></div><p>The <code class="literal">Config.in</code> file of your package must also ensure that
 2552 dependencies are enabled. Typically, Buildroot uses the following
 2553 rules:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2554 Use a <code class="literal">select</code> type of dependency for dependencies on
 2555   libraries. These dependencies are generally not obvious and it
 2556   therefore make sense to have the kconfig system ensure that the
 2557   dependencies are selected. For example, the <span class="emphasis"><em>libgtk2</em></span> package uses
 2558   <code class="literal">select BR2_PACKAGE_LIBGLIB2</code> to make sure this library is also
 2559   enabled.
 2560   The <code class="literal">select</code> keyword expresses the dependency with a backward
 2561   semantic.
 2562 </li><li class="listitem">
 2563 Use a <code class="literal">depends on</code> type of dependency when the user really needs to
 2564   be aware of the dependency. Typically, Buildroot uses this type of
 2565   dependency for dependencies on target architecture, MMU support and
 2566   toolchain options (see <a class="xref" href="#dependencies-target-toolchain-options" title="18.2.4. Dependencies on target and toolchain options">Section 18.2.4, “Dependencies on target and toolchain options”</a>),
 2567   or for dependencies on "big" things, such as the X.org system.
 2568   The <code class="literal">depends on</code> keyword expresses the dependency with a forward
 2569   semantic.
 2570 </li></ul></div><p><strong>Note. </strong>The current problem with the <span class="emphasis"><em>kconfig</em></span> language is that these two
 2571 dependency semantics are not internally linked. Therefore, it may be
 2572 possible to select a package, whom one of its dependencies/requirement
 2573 is not met.</p><p>An example illustrates both the usage of <code class="literal">select</code> and <code class="literal">depends on</code>.</p><pre class="screen">config BR2_PACKAGE_RRDTOOL
 2574         bool "rrdtool"
 2575         depends on BR2_USE_WCHAR
 2576         select BR2_PACKAGE_FREETYPE
 2577         select BR2_PACKAGE_LIBART
 2578         select BR2_PACKAGE_LIBPNG
 2579         select BR2_PACKAGE_ZLIB
 2580         help
 2581           RRDtool is the OpenSource industry standard, high performance
 2582           data logging and graphing system for time series data.
 2584           http://oss.oetiker.ch/rrdtool/
 2586 comment "rrdtool needs a toolchain w/ wchar"
 2587         depends on !BR2_USE_WCHAR</pre><p>Note that these two dependency types are only transitive with the
 2588 dependencies of the same kind.</p><p>This means, in the following example:</p><pre class="screen">config BR2_PACKAGE_A
 2589         bool "Package A"
 2591 config BR2_PACKAGE_B
 2592         bool "Package B"
 2593         depends on BR2_PACKAGE_A
 2595 config BR2_PACKAGE_C
 2596         bool "Package C"
 2597         depends on BR2_PACKAGE_B
 2599 config BR2_PACKAGE_D
 2600         bool "Package D"
 2601         select BR2_PACKAGE_B
 2603 config BR2_PACKAGE_E
 2604         bool "Package E"
 2605         select BR2_PACKAGE_D</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2606 Selecting <code class="literal">Package C</code> will be visible if <code class="literal">Package B</code> has been
 2607   selected, which in turn is only visible if <code class="literal">Package A</code> has been
 2608   selected.
 2609 </li><li class="listitem">
 2610 Selecting <code class="literal">Package E</code> will select <code class="literal">Package D</code>, which will select
 2611   <code class="literal">Package B</code>, it will not check for the dependencies of <code class="literal">Package B</code>,
 2612   so it will not select <code class="literal">Package A</code>.
 2613 </li><li class="listitem">
 2614 Since <code class="literal">Package B</code> is selected but <code class="literal">Package A</code> is not, this violates
 2615   the dependency of <code class="literal">Package B</code> on <code class="literal">Package A</code>. Therefore, in such a
 2616   situation, the transitive dependency has to be added explicitly:
 2617 </li></ul></div><pre class="screen">config BR2_PACKAGE_D
 2618         bool "Package D"
 2619         select BR2_PACKAGE_B
 2620         depends on BR2_PACKAGE_A
 2622 config BR2_PACKAGE_E
 2623         bool "Package E"
 2624         select BR2_PACKAGE_D
 2625         depends on BR2_PACKAGE_A</pre><p>Overall, for package library dependencies, <code class="literal">select</code> should be
 2626 preferred.</p><p>Note that such dependencies will ensure that the dependency option
 2627 is also enabled, but not necessarily built before your package. To do
 2628 so, the dependency also needs to be expressed in the <code class="literal">.mk</code> file of the
 2629 package.</p><p>Further formatting details: see <a class="link" href="#writing-rules-config-in" title="16.1. Config.in file">the
 2630 coding style</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="dependencies-target-toolchain-options"></a>18.2.4. Dependencies on target and toolchain options</h3></div></div></div><p>Many packages depend on certain options of the toolchain: the choice of
 2631 C library, C++ support, thread support, RPC support, wchar support,
 2632 or dynamic library support. Some packages can only be built on certain
 2633 target architectures, or if an MMU is available in the processor.</p><p>These dependencies have to be expressed with the appropriate <span class="emphasis"><em>depends
 2634 on</em></span> statements in the Config.in file. Additionally, for dependencies on
 2635 toolchain options, a <code class="literal">comment</code> should be displayed when the option is
 2636 not enabled, so that the user knows why the package is not available.
 2637 Dependencies on target architecture or MMU support should not be
 2638 made visible in a comment: since it is unlikely that the user can
 2639 freely choose another target, it makes little sense to show these
 2640 dependencies explicitly.</p><p>The <code class="literal">comment</code> should only be visible if the <code class="literal">config</code> option itself would
 2641 be visible when the toolchain option dependencies are met. This means
 2642 that all other dependencies of the package (including dependencies on
 2643 target architecture and MMU support) have to be repeated on the
 2644 <code class="literal">comment</code> definition. To keep it clear, the <code class="literal">depends on</code> statement for
 2645 these non-toolchain option should be kept separate from the <code class="literal">depends on</code>
 2646 statement for the toolchain options.
 2647 If there is a dependency on a config option in that same file (typically
 2648 the main package) it is preferable to have a global <code class="literal">if … endif</code>
 2649 construct rather than repeating the <code class="literal">depends on</code> statement on the
 2650 comment and other config options.</p><p>The general format of a dependency <code class="literal">comment</code> for package foo is:</p><pre class="screen">foo needs a toolchain w/ featA, featB, featC</pre><p>for example:</p><pre class="screen">mpd needs a toolchain w/ C++, threads, wchar</pre><p>or</p><pre class="screen">crda needs a toolchain w/ threads</pre><p>Note that this text is kept brief on purpose, so that it will fit on a
 2651 80-character terminal.</p><p>The rest of this section enumerates the different target and toolchain
 2652 options, the corresponding config symbols to depend on, and the text to
 2653 use in the comment.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
 2654 Target architecture
 2655 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2656 Dependency symbol: <code class="literal">BR2_powerpc</code>, <code class="literal">BR2_mips</code>, … (see <code class="literal">arch/Config.in</code>)
 2657 </li><li class="listitem">
 2658 Comment string: no comment to be added
 2659 </li></ul></div></li><li class="listitem"><p class="simpara">
 2660 MMU support
 2661 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2662 Dependency symbol: <code class="literal">BR2_USE_MMU</code>
 2663 </li><li class="listitem">
 2664 Comment string: no comment to be added
 2665 </li></ul></div></li><li class="listitem"><p class="simpara">
 2666 Gcc <code class="literal"><span class="emphasis"><em>_sync</em></span>*</code> built-ins used for atomic operations. They are
 2667   available in variants operating on 1 byte, 2 bytes, 4 bytes and 8
 2668   bytes. Since different architectures support atomic operations on
 2669   different sizes, one dependency symbol is available for each size:
 2670 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2671 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_1</code> for 1 byte,
 2672    <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_2</code> for 2 bytes,
 2673    <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_4</code> for 4 bytes, <code class="literal">BR2_TOOLCHAIN_HAS_SYNC_8</code>
 2674    for 8 bytes.
 2675 </li><li class="listitem">
 2676 Comment string: no comment to be added
 2677 </li></ul></div></li><li class="listitem"><p class="simpara">
 2678 Gcc <code class="literal"><span class="emphasis"><em>_atomic</em></span>*</code> built-ins used for atomic operations.
 2679 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2680 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_ATOMIC</code>.
 2681 </li><li class="listitem">
 2682 Comment string: no comment to be added
 2683 </li></ul></div></li><li class="listitem"><p class="simpara">
 2684 Kernel headers
 2685 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2686 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y</code>, (replace
 2687    <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
 2688 </li><li class="listitem">
 2689 Comment string: <code class="literal">headers &gt;= X.Y</code> and/or <code class="literal">headers &lt;= X.Y</code> (replace
 2690    <code class="literal">X.Y</code> with the proper version)
 2691 </li></ul></div></li><li class="listitem"><p class="simpara">
 2692 GCC version
 2693 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2694 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y</code>, (replace
 2695    <code class="literal">X_Y</code> with the proper version, see <code class="literal">toolchain/Config.in</code>)
 2696 </li><li class="listitem">
 2697 Comment string: <code class="literal">gcc &gt;= X.Y</code> and/or <code class="literal">gcc &lt;= X.Y</code> (replace
 2698    <code class="literal">X.Y</code> with the proper version)
 2699 </li></ul></div></li><li class="listitem"><p class="simpara">
 2700 Host GCC version
 2701 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2702 Dependency symbol: <code class="literal">BR2_HOST_GCC_AT_LEAST_X_Y</code>, (replace
 2703    <code class="literal">X_Y</code> with the proper version, see <code class="literal">Config.in</code>)
 2704 </li><li class="listitem">
 2705 Comment string: no comment to be added
 2706 </li><li class="listitem">
 2707 Note that it is usually not the package itself that has a minimum
 2708    host GCC version, but rather a host-package on which it depends.
 2709 </li></ul></div></li><li class="listitem"><p class="simpara">
 2710 C library
 2711 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2712 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_USES_GLIBC</code>,
 2713    <code class="literal">BR2_TOOLCHAIN_USES_MUSL</code>, <code class="literal">BR2_TOOLCHAIN_USES_UCLIBC</code>
 2714 </li><li class="listitem">
 2715 Comment string: for the C library, a slightly different comment text
 2716    is used: <code class="literal">foo needs a glibc toolchain</code>, or <code class="literal">foo needs a glibc
 2717    toolchain w/ C++</code>
 2718 </li></ul></div></li><li class="listitem"><p class="simpara">
 2719 C++ support
 2720 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2721 Dependency symbol: <code class="literal">BR2_INSTALL_LIBSTDCPP</code>
 2722 </li><li class="listitem">
 2723 Comment string: <code class="literal">C++</code>
 2724 </li></ul></div></li><li class="listitem"><p class="simpara">
 2725 D support
 2726 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2727 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_DLANG</code>
 2728 </li><li class="listitem">
 2729 Comment string: <code class="literal">Dlang</code>
 2730 </li></ul></div></li><li class="listitem"><p class="simpara">
 2731 Fortran support
 2732 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2733 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_FORTRAN</code>
 2734 </li><li class="listitem">
 2735 Comment string: <code class="literal">fortran</code>
 2736 </li></ul></div></li><li class="listitem"><p class="simpara">
 2737 thread support
 2738 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2739 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS</code>
 2740 </li><li class="listitem">
 2741 Comment string: <code class="literal">threads</code> (unless <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
 2742    is also needed, in which case, specifying only <code class="literal">NPTL</code> is sufficient)
 2743 </li></ul></div></li><li class="listitem"><p class="simpara">
 2744 NPTL thread support
 2745 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2746 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_THREADS_NPTL</code>
 2747 </li><li class="listitem">
 2748 Comment string: <code class="literal">NPTL</code>
 2749 </li></ul></div></li><li class="listitem"><p class="simpara">
 2750 RPC support
 2751 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2752 Dependency symbol: <code class="literal">BR2_TOOLCHAIN_HAS_NATIVE_RPC</code>
 2753 </li><li class="listitem">
 2754 Comment string: <code class="literal">RPC</code>
 2755 </li></ul></div></li><li class="listitem"><p class="simpara">
 2756 wchar support
 2757 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2758 Dependency symbol: <code class="literal">BR2_USE_WCHAR</code>
 2759 </li><li class="listitem">
 2760 Comment string: <code class="literal">wchar</code>
 2761 </li></ul></div></li><li class="listitem"><p class="simpara">
 2762 dynamic library
 2763 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2764 Dependency symbol: <code class="literal">!BR2_STATIC_LIBS</code>
 2765 </li><li class="listitem">
 2766 Comment string: <code class="literal">dynamic library</code>
 2767 </li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_a_linux_kernel_built_by_buildroot"></a>18.2.5. Dependencies on a Linux kernel built by buildroot</h3></div></div></div><p>Some packages need a Linux kernel to be built by buildroot. These are
 2768 typically kernel modules or firmware. A comment should be added in the
 2769 Config.in file to express this dependency, similar to dependencies on
 2770 toolchain options. The general format is:</p><pre class="screen">foo needs a Linux kernel to be built</pre><p>If there is a dependency on both toolchain options and the Linux
 2771 kernel, use this format:</p><pre class="screen">foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_udev_dev_management"></a>18.2.6. Dependencies on udev /dev management</h3></div></div></div><p>If a package needs udev /dev management, it should depend on symbol
 2772 <code class="literal">BR2_PACKAGE_HAS_UDEV</code>, and the following comment should be added:</p><pre class="screen">foo needs udev /dev management</pre><p>If there is a dependency on both toolchain options and udev /dev
 2773 management, use this format:</p><pre class="screen">foo needs udev /dev management and a toolchain w/ featA, featB, featC</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_dependencies_on_features_provided_by_virtual_packages"></a>18.2.7. Dependencies on features provided by virtual packages</h3></div></div></div><p>Some features can be provided by more than one package, such as the
 2774 openGL libraries.</p><p>See <a class="xref" href="#virtual-package-tutorial">Section 18.11, “Infrastructure for virtual packages”</a> for more on the virtual packages.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_the_literal_mk_literal_file"></a>18.3. The <code class="literal">.mk</code> file</h2></div></div></div><p><a id="adding-packages-mk"></a>Finally, here’s the hardest part. Create a file named <code class="literal">libfoo.mk</code>. It
 2775 describes how the package should be downloaded, configured, built,
 2776 installed, etc.</p><p>Depending on the package type, the <code class="literal">.mk</code> file must be written in a
 2777 different way, using different infrastructures:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
 2778 <span class="strong"><strong>Makefiles for generic packages</strong></span> (not using autotools or CMake):
 2779   These are based on an infrastructure similar to the one used for
 2780   autotools-based packages, but require a little more work from the
 2781   developer. They specify what should be done for the configuration,
 2782   compilation and installation of the package. This
 2783   infrastructure must be used for all packages that do not use the
 2784   autotools as their build system. In the future, other specialized
 2785   infrastructures might be written for other build systems. We cover
 2786   them through in a <a class="link" href="#generic-package-tutorial" title="18.5.1. generic-package tutorial">tutorial</a> and a
 2787   <a class="link" href="#generic-package-reference" title="18.5.2. generic-package reference">reference</a>.
 2788 </li><li class="listitem">
 2789 <span class="strong"><strong>Makefiles for autotools-based software</strong></span> (autoconf, automake, etc.):
 2790   We provide a dedicated infrastructure for such packages, since
 2791   autotools is a very common build system. This infrastructure <span class="emphasis"><em>must</em></span>
 2792   be used for new packages that rely on the autotools as their build
 2793   system. We cover them through a <a class="link" href="#autotools-package-tutorial" title="18.6.1. autotools-package tutorial">tutorial</a>
 2794   and <a class="link" href="#autotools-package-reference" title="18.6.2. autotools-package reference">reference</a>.
 2795 </li><li class="listitem">
 2796 <span class="strong"><strong>Makefiles for cmake-based software</strong></span>: We provide a dedicated
 2797    infrastructure for such packages, as CMake is a more and more
 2798    commonly used build system and has a standardized behaviour. This
 2799    infrastructure <span class="emphasis"><em>must</em></span> be used for new packages that rely on
 2800    CMake. We cover them through a <a class="link" href="#cmake-package-tutorial" title="18.7.1. cmake-package tutorial">tutorial</a>
 2801    and <a class="link" href="#cmake-package-reference" title="18.7.2. cmake-package reference">reference</a>.
 2802 </li><li class="listitem">
 2803 <span class="strong"><strong>Makefiles for Python modules</strong></span>: We have a dedicated infrastructure
 2804    for Python modules that use either the <code class="literal">distutils</code> or the
 2805    <code class="literal">setuptools</code> mechanism. We cover them through a
 2806    <a class="link" href="#python-package-tutorial" title="18.8.1. python-package tutorial">tutorial</a> and a
 2807    <a class="link" href="#python-package-reference" title="18.8.2. python-package reference">reference</a>.
 2808 </li><li class="listitem">
 2809 <span class="strong"><strong>Makefiles for Lua modules</strong></span>: We have a dedicated infrastructure for
 2810    Lua modules available through the LuaRocks web site. We cover them
 2811    through a <a class="link" href="#luarocks-package-tutorial" title="18.9.1. luarocks-package tutorial">tutorial</a> and a
 2812    <a class="link" href="#luarocks-package-reference" title="18.9.2. luarocks-package reference">reference</a>.
 2813 </li></ul></div><p>Further formatting details: see <a class="link" href="#writing-rules-mk" title="16.2. The .mk file">the writing
 2814 rules</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adding-packages-hash"></a>18.4. The <code class="literal">.hash</code> file</h2></div></div></div><p>When possible, you must add a third file, named <code class="literal">libfoo.hash</code>, that
 2815 contains the hashes of the downloaded files for the <code class="literal">libfoo</code>
 2816 package. The only reason for not adding a <code class="literal">.hash</code> file is when hash
 2817 checking is not possible due to how the package is downloaded.</p><p>When a package has a version selection choice, then the hash file may be
 2818 stored in a subdirectory named after the version, e.g.
 2819 <code class="literal">package/libfoo/1.2.3/libfoo.hash</code>. This is especially important if the
 2820 different versions have different licensing terms, but they are stored
 2821 in the same file. Otherwise, the hash file should stay in the package’s
 2822 directory.</p><p>The hashes stored in that file are used to validate the integrity of the
 2823 downloaded files and of the license files.</p><p>The format of this file is one line for each file for which to check the
 2824 hash, each line with the following three fields separated by two spaces:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
 2825 the type of hash, one of:
 2826 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2827 <code class="literal">md5</code>, <code class="literal">sha1</code>, <code class="literal">sha224</code>, <code class="literal">sha256</code>, <code class="literal">sha384</code>, <code class="literal">sha512</code>, <code class="literal">none</code>
 2828 </li></ul></div></li><li class="listitem"><p class="simpara">
 2829 the hash of the file:
 2830 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2831 for <code class="literal">none</code>, one or more non-space chars, usually just the string <code class="literal">xxx</code>
 2832 </li><li class="listitem">
 2833 for <code class="literal">md5</code>, 32 hexadecimal characters
 2834 </li><li class="listitem">
 2835 for <code class="literal">sha1</code>, 40 hexadecimal characters
 2836 </li><li class="listitem">
 2837 for <code class="literal">sha224</code>, 56 hexadecimal characters
 2838 </li><li class="listitem">
 2839 for <code class="literal">sha256</code>, 64 hexadecimal characters
 2840 </li><li class="listitem">
 2841 for <code class="literal">sha384</code>, 96 hexadecimal characters
 2842 </li><li class="listitem">
 2843 for <code class="literal">sha512</code>, 128 hexadecimal characters
 2844 </li></ul></div></li><li class="listitem"><p class="simpara">
 2845 the name of the file:
 2846 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 2847 for a source archive: the basename of the file, without any directory
 2848    component,
 2849 </li><li class="listitem">
 2850 for a license file: the path as it appears in <code class="literal">FOO_LICENSE_FILES</code>.
 2851 </li></ul></div></li></ul></div><p>Lines starting with a <code class="literal">#</code> sign are considered comments, and ignored. Empty
 2852 lines are ignored.</p><p>There can be more than one hash for a single file, each on its own line. In
 2853 this case, all hashes must match.</p><p><strong>Note. </strong>Ideally, the hashes stored in this file should match the hashes published by
 2854 upstream, e.g. on their website, in the e-mail announcement… If upstream
 2855 provides more than one type of hash (e.g. <code class="literal">sha1</code> and <code class="literal">sha512</code>), then it is
 2856 best to add all those hashes in the <code class="literal">.hash</code> file. If upstream does not
 2857 provide any hash, or only provides an <code class="literal">md5</code> hash, then compute at least one
 2858 strong hash yourself (preferably <code class="literal">sha256</code>, but not <code class="literal">md5</code>), and mention
 2859 this in a comment line above the hashes.</p><p><strong>Note. </strong>The hashes for license files are used to detect a license change when a
 2860 package version is bumped. The hashes are checked during the make legal-info
 2861 target run. For a package with multiple versions (like Qt5),
 2862 create the hash file in a subdirectory <code class="literal">&lt;packageversion&gt;</code> of that package
 2863 (see also <a class="xref" href="#patch-apply-order" title="19.2. How patches are applied">Section 19.2, “How patches are applied”</a>).</p><p>The <code class="literal">none</code> hash type is reserved to those archives downloaded from a
 2864 repository, like a <span class="emphasis"><em>git clone</em></span>, a <span class="emphasis"><em>subversion checkout</em></span></p><p>The example below defines a <code class="literal">sha1</code> and a <code class="literal">sha256</code> published by upstream for
 2865 the main <code class="literal">libfoo-1.2.3.tar.bz2</code> tarball, an <code class="literal">md5</code> from upstream and a
 2866 locally-computed <code class="literal">sha256</code> hashes for a binary blob, a <code class="literal">sha256</code> for a
 2867 downloaded patch, and an archive with no hash:</p><pre class="screen"># Hashes from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.{sha1,sha256}:
 2868 sha1  486fb55c3efa71148fe07895fd713ea3a5ae343a  libfoo-1.2.3.tar.bz2
 2869 sha256  efc8103cc3bcb06bda6a781532d12701eb081ad83e8f90004b39ab81b65d4369  libfoo-1.2.3.tar.bz2
 2871 # md5 from: http://www.foosoftware.org/download/libfoo-1.2.3.tar.bz2.md5, sha256 locally computed:
 2872 md5  2d608f3c318c6b7557d551a5a09314f03452f1a1  libfoo-data.bin
 2873 sha256  01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b  libfoo-data.bin
 2875 # Locally computed:
 2876 sha256  ff52101fb90bbfc3fe9475e425688c660f46216d7e751c4bbdb1dc85cdccacb9  libfoo-fix-blabla.patch
 2878 # No hash for 1234:
 2879 none  xxx  libfoo-1234.tar.gz
 2881 # Hash for license files:
 2882 sha256  a45a845012742796534f7e91fe623262ccfb99460a2bd04015bd28d66fba95b8  COPYING
 2883 sha256  01b1f9f2c8ee648a7a596a1abe8aa4ed7899b1c9e5551bda06da6e422b04aa55  doc/COPYING.LGPL</pre><p>If the <code class="literal">.hash</code> file is present, and it contains one or more hashes for a
 2884 downloaded file, the hash(es) computed by Buildroot (after download) must
 2885 match the hash(es) stored in the <code class="literal">.hash</code> file. If one or more hashes do
 2886 not match, Buildroot considers this an error, deletes the downloaded file,
 2887 and aborts.</p><p>If the <code class="literal">.hash</code> file is present, but it does not contain a hash for a
 2888 downloaded file, Buildroot considers this an error and aborts. However,
 2889 the downloaded file is left in the download directory since this
 2890 typically indicates that the <code class="literal">.hash</code> file is wrong but the downloaded
 2891 file is probably OK.</p><p>Hashes are currently checked for files fetched from http/ftp servers,
 2892 Git repositories, files copied using scp and local files. Hashes are
 2893 not checked for other version control systems (such as Subversion,
 2894 CVS, etc.) because Buildroot currently does not generate reproducible
 2895 tarballs when source code is fetched from such version control
 2896 systems.</p><p>Hashes should only be added in <code class="literal">.hash</code> files for files that are
 2897 guaranteed to be stable. For example, patches auto-generated by Github
 2898 are not guaranteed to be stable, and therefore their hashes can change
 2899 over time. Such patches should not be downloaded, and instead be added
 2900 locally to the package folder.</p><p>If the <code class="literal">.hash</code> file is missing, then no check is done at all.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_infrastructure_for_packages_with_specific_build_systems"></a>18.5. Infrastructure for packages with specific build systems</h2></div></div></div><p>By <span class="emphasis"><em>packages with specific build systems</em></span> we mean all the packages
 2901 whose build system is not one of the standard ones, such as
 2902 <span class="emphasis"><em>autotools</em></span> or <span class="emphasis"><em>CMake</em></span>. This typically includes packages whose build
 2903 system is based on hand-written Makefiles or shell scripts.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="generic-package-tutorial"></a>18.5.1<code class="literal">generic-package</code> tutorial</h3></div></div></div><pre class="screen">01: ################################################################################
 2904 02: #
 2905 03: # libfoo
 2906 04: #
 2907 05: ################################################################################
 2908 06:
 2909 07: LIBFOO_VERSION = 1.0
 2910 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
 2911 09: LIBFOO_SITE = http://www.foosoftware.org/download
 2912 10: LIBFOO_LICENSE = GPL-3.0+
 2915 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
 2916 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
 2917 15:
 2918 16: define LIBFOO_BUILD_CMDS
 2919 17:     $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
 2920 18: endef
 2921 19:
 2923 21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
 2924 22:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
 2925 23:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
 2926 24: endef
 2927 25:
 2929 27:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
 2930 28:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
 2931 29: endef
 2932 30:
 2933 31: define LIBFOO_USERS
 2934 32:     foo -1 libfoo -1 * - - - LibFoo daemon
 2935 33: endef
 2936 34:
 2937 35: define LIBFOO_DEVICES
 2938 36:     /dev/foo  c  666  0  0  42  0  -  -  -
 2939 37: endef
 2940 38:
 2941 39: define LIBFOO_PERMISSIONS
 2942 40:     /bin/foo  f  4755  foo  libfoo   -  -  -  -  -
 2943 41: endef
 2944 42:
 2945 43: $(eval $(generic-package))</pre><p>The Makefile begins on line 7 to 11 with metadata information: the
 2946 version of the package (<code class="literal">LIBFOO_VERSION</code>), the name of the
 2947 tarball containing the package (<code class="literal">LIBFOO_SOURCE</code>) (xz-ed tarball recommended)
 2948 the Internet location at which the tarball can be downloaded from
 2949 (<code class="literal">LIBFOO_SITE</code>), the license (<code class="literal">LIBFOO_LICENSE</code>) and file with the
 2950 license text (<code class="literal">LIBFOO_LICENSE_FILES</code>). All variables must start with
 2951 the same prefix, <code class="literal">LIBFOO_</code> in this case. This prefix is always the
 2952 uppercased version of the package name (see below to understand where
 2953 the package name is defined).</p><p>On line 12, we specify that this package wants to install something to
 2954 the staging space. This is often needed for libraries, since they must
 2955 install header files and other development files in the staging space.
 2956 This will ensure that the commands listed in the
 2957 <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> variable will be executed.</p><p>On line 13, we specify that there is some fixing to be done to some
 2958 of the <span class="emphasis"><em>libfoo-config</em></span> files that were installed during
 2959 <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> phase.
 2960 These *-config files are executable shell script files that are
 2961 located in <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> directory and are executed
 2962 by other 3rd party packages to find out the location and the linking
 2963 flags of this particular package.</p><p>The problem is that all these *-config files by default give wrong,
 2964 host system linking flags that are unsuitable for cross-compiling.</p><p>For example:    <span class="emphasis"><em>-I/usr/include</em></span> instead of <span class="emphasis"><em>-I$(STAGING_DIR)/usr/include</em></span>
 2965 or:             <span class="emphasis"><em>-L/usr/lib</em></span> instead of <span class="emphasis"><em>-L$(STAGING_DIR)/usr/lib</em></span></p><p>So some sed magic is done to these scripts to make them give correct
 2966 flags.
 2967 The argument to be given to <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> is the file name(s)
 2968 of the shell script(s) needing fixing. All these names are relative to
 2969 <span class="emphasis"><em>$(STAGING_DIR)/usr/bin</em></span> and if needed multiple names can be given.</p><p>In addition, the scripts listed in <code class="literal">LIBFOO_CONFIG_SCRIPTS</code> are removed
 2970 from <code class="literal">$(TARGET_DIR)/usr/bin</code>, since they are not needed on the target.</p><div class="example"><a id="idm3193"></a><p class="title"><strong>Example 18.1. Config script: <span class="emphasis"><em>divine</em></span> package</strong></p><div class="example-contents"><p>Package divine installs shell script <span class="emphasis"><em>$(STAGING_DIR)/usr/bin/divine-config</em></span>.</p><p>So its fixup would be:</p><pre class="screen">DIVINE_CONFIG_SCRIPTS = divine-config</pre></div></div><br class="example-break" /><div class="example"><a id="idm3200"></a><p class="title"><strong>Example 18.2. Config script: <span class="emphasis"><em>imagemagick</em></span> package:</strong></p><div class="example-contents"><p>Package imagemagick installs the following scripts:
 2971 <span class="emphasis"><em>$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config</em></span></p><p>So it’s fixup would be:</p><pre class="screen">IMAGEMAGICK_CONFIG_SCRIPTS = \
 2972    Magick-config Magick++-config \
 2973    MagickCore-config MagickWand-config Wand-config</pre></div></div><br class="example-break" /><p>On line 14, we specify the list of dependencies this package relies
 2974 on. These dependencies are listed in terms of lower-case package names,
 2975 which can be packages for the target (without the <code class="literal">host-</code>
 2976 prefix) or packages for the host (with the <code class="literal">host-</code>) prefix).
 2977 Buildroot will ensure that all these packages are built and installed
 2978 <span class="emphasis"><em>before</em></span> the current package starts its configuration.</p><p>The rest of the Makefile, lines 16..29, defines what should be done
 2979 at the different steps of the package configuration, compilation and
 2980 installation.
 2981 <code class="literal">LIBFOO_BUILD_CMDS</code> tells what steps should be performed to
 2982 build the package. <code class="literal">LIBFOO_INSTALL_STAGING_CMDS</code> tells what
 2983 steps should be performed to install the package in the staging space.
 2984 <code class="literal">LIBFOO_INSTALL_TARGET_CMDS</code> tells what steps should be
 2985 performed to install the package in the target space.</p><p>All these steps rely on the <code class="literal">$(@D)</code> variable, which
 2986 contains the directory where the source code of the package has been
 2987 extracted.</p><p>On lines 31..33, we define a user that is used by this package (e.g.
 2988 to run a daemon as non-root) (<code class="literal">LIBFOO_USERS</code>).</p><p>On line 35..37, we define a device-node file used by this package
 2989 (<code class="literal">LIBFOO_DEVICES</code>).</p><p>On line 39..41, we define the permissions to set to specific files
 2990 installed by this package (<code class="literal">LIBFOO_PERMISSIONS</code>).</p><p>Finally, on line 43, we call the <code class="literal">generic-package</code> function, which
 2991 generates, according to the variables defined previously, all the
 2992 Makefile code necessary to make your package working.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="generic-package-reference"></a>18.5.2<code class="literal">generic-package</code> reference</h3></div></div></div><p>There are two variants of the generic target. The <code class="literal">generic-package</code> macro is
 2993 used for packages to be cross-compiled for the target. The
 2994 <code class="literal">host-generic-package</code> macro is used for host packages, natively compiled
 2995 for the host. It is possible to call both of them in a single <code class="literal">.mk</code>
 2996 file: once to create the rules to generate a target
 2997 package and once to create the rules to generate a host package:</p><pre class="screen">$(eval $(generic-package))
 2998 $(eval $(host-generic-package))</pre><p>This might be useful if the compilation of the target package requires
 2999 some tools to be installed on the host. If the package name is
 3000 <code class="literal">libfoo</code>, then the name of the package for the target is also
 3001 <code class="literal">libfoo</code>, while the name of the package for the host is
 3002 <code class="literal">host-libfoo</code>. These names should be used in the DEPENDENCIES
 3003 variables of other packages, if they depend on <code class="literal">libfoo</code> or
 3004 <code class="literal">host-libfoo</code>.</p><p>The call to the <code class="literal">generic-package</code> and/or <code class="literal">host-generic-package</code> macro
 3005 <span class="strong"><strong>must</strong></span> be at the end of the <code class="literal">.mk</code> file, after all variable definitions.
 3006 The call to <code class="literal">host-generic-package</code> <span class="strong"><strong>must</strong></span> be after the call to
 3007 <code class="literal">generic-package</code>, if any.</p><p>For the target package, the <code class="literal">generic-package</code> uses the variables defined by
 3008 the .mk file and prefixed by the uppercased package name:
 3009 <code class="literal">LIBFOO_*</code>. <code class="literal">host-generic-package</code> uses the <code class="literal">HOST_LIBFOO_*</code> variables. For
 3010 <span class="emphasis"><em>some</em></span> variables, if the <code class="literal">HOST_LIBFOO_</code> prefixed variable doesn’t
 3011 exist, the package infrastructure uses the corresponding variable
 3012 prefixed by <code class="literal">LIBFOO_</code>. This is done for variables that are likely to
 3013 have the same value for both the target and host packages. See below
 3014 for details.</p><p>The list of variables that can be set in a <code class="literal">.mk</code> file to give metadata
 3015 information is (assuming the package name is <code class="literal">libfoo</code>) :</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">
 3016 <code class="literal">LIBFOO_VERSION</code>, mandatory, must contain the version of the
 3017   package. Note that if <code class="literal">HOST_LIBFOO_VERSION</code> doesn’t exist, it is
 3018   assumed to be the same as <code class="literal">LIBFOO_VERSION</code>. It can also be a
 3019   revision number or a tag for packages that are fetched directly
 3020   from their version control system. Examples:
 3021 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 3022 a version for a release tarball: <code class="literal">LIBFOO_VERSION = 0.1.2</code>
 3023 </li><li class="listitem">
 3024 a sha1 for a git tree: <code class="literal">LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057</code>
 3025 </li><li class="listitem"><p class="simpara">
 3026 a tag for a git tree <code class="literal">LIBFOO_VERSION = v0.1.2</code>
 3027 </p><p><strong>Note: </strong>Using a branch name as <code class="literal">FOO_VERSION</code> is not supported, because it does
 3028 not and can not work as people would expect it should:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
 3029 due to local caching, Buildroot will not re-fetch the repository,
 3030      so people who expect to be able to follow the remote repository
 3031      would be quite surprised and disappointed;
 3032 </li><li class="listitem">
 3033 because two builds can never be perfectly simultaneous, and because
 3034      the remote repository may get new commits on the branch anytime,
 3035      two users, using the same Buildroot tree and building the same
 3036      configuration, may get different source, thus rendering the build
 3037      non reproducible, and people would be quite surprised and
 3038      disappointed.
 3039 </li></ol></div></li></ul></div></li><li class="listitem">
 3040 <code class="literal">LIBFOO_SOURCE</code> may contain the name of the tarball of the package,
 3041   which Buildroot will use to download the tarball from
 3042   <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_SOURCE</code> is not specified, it defaults
 3043   to <code class="literal">LIBFOO_SOURCE</code>. If none are specified, then the value is assumed
 3044   to be <code class="literal">libfoo-$(LIBFOO_VERSION).tar.gz</code>.
 3045   Example: <code class="literal">LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2</code>
 3046 </li><li class="listitem">
 3047 <code class="literal">LIBFOO_PATCH</code> may contain a space-separated list of patch file
 3048   names, that Buildroot will download and apply to the package source
 3049   code. If an entry contains <code class="literal">://</code>, then Buildroot will assume it is a
 3050   full URL and download the patch from this location. Otherwise,
 3051   Buildroot will assume that the patch should be downloaded from
 3052   <code class="literal">LIBFOO_SITE</code>. If <code class="literal">HOST_LIBFOO_PATCH</code> is not specified, it defaults
 3053   to <code class="literal">LIBFOO_PATCH</code>. Note that patches that are included in Buildroot
 3054   itself use a different mechanism: all files of the form
 3055   <code class="literal">*.patch</code> present in the package directory inside
 3056   Buildroot will be applied to the package after extraction (see
 3057   <a class="link" href="#patch-policy" title="Chapter 19. Patching a package">patching a package</a>). Finally, patches listed in
 3058   the <code class="literal">LIBFOO_PATCH</code> variable are applied <span class="emphasis"><em>before</em></span> the patches stored
 3059   in the Buildroot package directory.
 3060 </li><li class="listitem">
 3061 <code class="literal">LIBFOO_SITE</code> provides the location of the package, which can be a
 3062   URL or a local filesystem path. HTTP, FTP and SCP are supported URL
 3063   types for retrieving package tarballs. In these cases don’t include a
 3064   trailing slash: it will be added by Buildroot between the directory
 3065   and the filename as appropriate. Git, Subversion, Mercurial,
 3066   and Bazaar are supported URL types for retrieving packages directly
 3067   from source code management systems. There is a helper function to make
 3068   it easier to download source tarballs from GitHub (refer to
 3069   <a class="xref" href="#github-download-url" title="18.24.4. How to add a package from GitHub">Section 18.24.4, “How to add a package from GitHub”</a> for details). A filesystem path may be used
 3070   to specify either a tarball or a directory containing the package
 3071   source code. See <code class="literal">LIBFOO_SITE_METHOD</code> below for more details on how
 3072   retrieval works.
 3073   Note that SCP URLs should be of the form
 3074   <code class="literal">scp://[user@]host:filepath</code>, and that filepath is relative to the
 3075   user’s home directory, so you may want to prepend the path with a
 3076   slash for absolute paths:
 3077   <code class="literal">scp://[user@]host:/absolutepath</code>.
 3078   If <code class="literal">HOST_LIBFOO_SITE</code> is not specified, it defaults to
 3079   <code class="literal">LIBFOO_SITE</code>.
 3080   Examples:
 3081     <code class="literal">LIBFOO_SITE=http://www.libfoosoftware.org/libfoo</code>
 3082     <code class="literal">LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor</code>
 3083     <code class="literal">LIBFOO_SITE=/opt/software/libfoo.tar.gz</code>
 3084     <code class="literal">LIBFOO_SITE=$(TOPDIR)/../src/libfoo</code>
 3085 </li><li class="listitem">
 3086 <code class="literal">LIBFOO_DL_OPTS</code> is a space-separated list of additional options to
 3087   pass to the downloader. Useful for retrieving documents with
 3088   server-side checking for user logins and passwords, or to use a proxy.
 3089   All download methods valid for <code class="literal">LIBFOO_SITE_METHOD</code> are supported;
 3090   valid options depend on the download method (consult the man page
 3091   for the respective download utilities).
 3092 </li><li class="listitem">
 3093 <code class="literal">LIBFOO_EXTRA_DOWNLOADS</code> is a space-separated list of additional
 3094   files that Buildroot should download. If an entry contains <code class="literal">://</code>
 3095   then Buildroot will assume it is a complete URL and will download
 3096   the file using this URL. Otherwise, Buildroot will assume the file
 3097   to be downloaded is located at <code class="literal">LIBFOO_SITE</code>. Buildroot will not do
 3098   anything with those additional files, except download them: it will
 3099   be up to the package recipe to use them from <code class="literal">$(LIBFOO_DL_DIR)</code>.
 3100 </li><li class="listitem"><p class="simpara">
 3101 <code class="literal">LIBFOO_SITE_METHOD</code> determines the method used to fetch or copy the
 3102   package source code. In many cases, Buildroot guesses the method
 3103   from the contents of <code class="literal">LIBFOO_SITE</code> and setting <code class="literal">LIBFOO_SITE_METHOD</code>
 3104   is unnecessary. When <code class="literal">HOST_LIBFOO_SITE_METHOD</code> is not specified, it
 3105   defaults to the value of <code class="literal">LIBFOO_SITE_METHOD</code>.
 3106   The possible values of <code class="literal">LIBFOO_SITE_METHOD</code> are:
 3107 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
 3108 <code class="literal">wget</code> for normal FTP/HTTP downloads of tarballs. Used by
 3109      default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">http://</code>, <code class="literal">https://</code> or
 3110      <code class="literal">ftp://</code>.
 3111 </li><li class="listitem">
 3112 <code class="literal">scp</code> for downloads of tarballs over SSH with scp. Used by
 3113      default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">scp://</code>.
 3114 </li><li class="listitem">
 3115 <code class="literal">svn</code> for retrieving source code from a Subversion repository.
 3116      Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">svn://</code>. When a
 3117      <code class="literal">http://</code> Subversion repository URL is specified in
 3118      <code class="literal">LIBFOO_SITE</code>, one <span class="emphasis"><em>must</em></span> specify <code class="literal">LIBFOO_SITE_METHOD=svn</code>.
 3119      Buildroot performs a checkout which is preserved as a tarball in
 3120      the download cache; subsequent builds use the tarball instead of
 3121      performing another checkout.
 3122 </li><li class="listitem">
 3123 <code class="literal">cvs</code> for retrieving source code from a CVS repository.
 3124      Used by default when <code class="literal">LIBFOO_SITE</code> begins with <code class="literal">cvs://</code>.
 3125      The downloaded source code is cached as with the <code class="literal">svn</code> method.
 3126      Anonymous pserver mode is assumed otherwise explicitly defined
 3127      on <code class="literal">LIBFOO_SITE</code>. Both
 3128      <code class="literal">LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo</code> and
 3129      <code class="literal">LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo</code>
 3130      are accepted, on the former anonymous pserver access mode is
 3131      assumed.
 3132      <code class="literal">LIBFOO_SITE</code> <span class="emphasis"><em>must</em></span> contain the source URL as well as the remote
 3133      repository directory. The module is the package name.
 3134      <code class="literal">LIBFOO_VERSION</code> is <span class="emphasis"><em>mandatory</em></span> and <span class="emphasis"><em>must</em></span> be a tag, a branch, or