Revision as of 04:20, 1 September 2012 by SamuelMartin (talk | contribs) (add toc suggestion)
Jump to: navigation, search

Discussion around the organization of the Buildroot manual

List of topics that must be covered

  • Starting with Buildroot (out-of-box experience, just using menuconfig options to get something, no need to hack anything)
  • Configuration
    • Explain the impact of the target architecture variant selection
    • Explain the toolchain backends
    • Explain the init systems
    • Explain the /dev management strategies. Explain custom device tables.
    • Explain the configuration of the kernel, and real-time extensions
    • Explain the root filesystem types, with specific details on the special initramfs case
    • Explain usage of the board/ directory
    • Explain usage of post-build scripts, give examples (set a root password, etc.), and explain why it's better than custom target skeletons.
  • How to add new packages
    • The different package infrastructures
    • Details on autotools-package infrastructure, on cmake-package infrastructure, generic-package infrastructure
    • Details on how to write the files: when 'depends on' should be used, when 'select' should be used. How to properly handle dependencies on toolchain features (RPC, locale, etc.)
    • Details on hooks
    • Details on adding patches to packages
    • Details on adding licensing information to packages
    • Details on gettext/libiconv handling
    • The different download infrastructures
  • Contribution
    • How to report bugs (bug tracker, IRC). Explain to include the .config file + 100-200 last lines of build log after doing a complete 'make clean; make'
    • How to send patches.

Proposed organization

This toc suggestion is close to the one already posted on the mailing list (see:, and is here to give some starting-point.

  1. About Buildroot
  2. Starting up
    1. System requirements
      1. Mandatory packages
      2. Optional packages
    2. Getting Buildroot
    3. Using Buildroot
  3. Working with Buildroot
    1. make tips
    2. Customization
      1. Customizing the generated target filesystem
      2. Customizing the Busybox configuration
      3. Customizing the uClibc configuration
      4. Customizing the Linux kernel configuration
      5. Customizing the toolchain
        1. Using the external toolchain backend
        2. Using the internal Buildroot toolchain backend
        3. Using the Crosstool-NG backend
    3. Daily use
      1. Understanding how to rebuild packages
      2. Offline builds
      3. Building out-of-tree
      4. Environment variables
    4. Hacking Buildroot
  4. Frequently Asked Questions & Troubleshooting
    1. The boot hangs after Starting network…
    2. module-init-tools fails to build with cannot find -lc
    3. LZO package configuration failure due to incorrect host architecture detection
      1. Typical error output
      2. Solution
  5. Going further in Buildroot’s innards
    1. Embedded system basics & Reasons to use Buildroot
      1. Cross-compilation & cross-toolchain
      2. Why choose Buildroot
    2. How Buildroot works
    3. Advanced usage
      1. Using the generated toolchain outside Buildroot
      2. Using an external toolchain
      3. Using ccache in Buildroot
      4. Location of downloaded packages
      5. Package make targets
  6. Developer Guidelines
    1. Writing rules
      1. file
      2. The .mk file
      3. The documentation
    2. Adding new packages to Buildroot
      1. Package directory
        1. file
        2. The .mk file
      2. Infrastructure for packages with specific build systems
        1. generic-package Tutorial
        2. generic-package Reference
      3. Infrastructure for autotools-based packages
        1. autotools-package tutorial
        2. autotools-package reference
      4. Infrastructure for CMake-based packages
        1. cmake-package tutorial
        2. cmake-package reference
      5. Manual Makefile
      6. Gettext integration and interaction with packages
      7. Conclusion
    3. Patch Policy
      1. Provinding patches
        1. Additionnal tarball
        2. Within Buildroot
      2. How patches are applied
      3. Format and licensing of the package patches
    4. Download infrastructure
    5. Creating your own board support
  7. Getting involved
    1. Mailing List
      1. Subscribing to the mailing list
      2. Searching the List Archives
    2. IRC
    3. Patchwork
    4. Bugtracker
    5. Buildroot wikipage
  8. Contibuting to Buildroot
    1. Submitting patches
    2. Reviewing/Testing patches
    3. Autobuild
  9. Legal notice and licensing
    1. Complying with opensource licenses
    2. Complying with the Buildroot license
  10. Appendix
    1. Makedev syntax documentation
    2. Deprecated list