docs/manual/customize-directory-structure.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[customize-dir-structure]]
   5 === Recommended directory structure
   6
   7 When customizing Buildroot for your project, you will be creating one or
   8 more project-specific files that need to be stored somewhere. While most
   9 of these files could be placed in _any_ location as their path is to be
  10 specified in the Buildroot configuration, the Buildroot developers
  11 recommend a specific directory structure which is described in this
  12 section.
  13
  14 Orthogonal to this directory structure, you can choose _where_ you place
  15 this structure itself: either inside the Buildroot tree, or outside of
  16 it using +BR2_EXTERNAL+. Both options are valid, the choice is up to you.
  17
  18 -----
  19 +-- board/
  20 |   +-- <company>/
  21 |       +-- <boardname>/
  22 |           +-- linux.config
  23 |           +-- busybox.config
  24 |           +-- <other configuration files>
  25 |           +-- post_build.sh
  26 |           +-- post_image.sh
  27 |           +-- rootfs_overlay/
  28 |           |   +-- etc/
  29 |           |   +-- <some file>
  30 |           +-- patches/
  31 |               +-- foo/
  32 |               |   +-- <some patch>
  33 |               +-- libbar/
  34 |                   +-- <some other patches>
  35 |
  36 +-- configs/
  37 |   +-- <boardname>_defconfig
  38 |
  39 +-- package/
  40 |   +-- <company>/
  41 |       +-- Config.in (if not using BR2_EXTERNAL)
  42 |       +-- <company>.mk (if not using BR2_EXTERNAL)
  43 |       +-- package1/
  44 |       |    +-- Config.in
  45 |       |    +-- package1.mk
  46 |       +-- package2/
  47 |           +-- Config.in
  48 |           +-- package2.mk
  49 |
  50 +-- Config.in (if using BR2_EXTERNAL)
  51 +-- external.mk (if using BR2_EXTERNAL)
  52 ------
  53
  54 Details on the files shown above are given further in this chapter.
  55
  56 Note: if you choose to place this structure outside of the Buildroot
  57 tree using +BR2_EXTERNAL+, the <company> and possibly <boardname>
  58 components may be superfluous and can be left out.
  59
  60 ==== Implementing layered customizations
  61
  62 It is quite common for a user to have several related projects that partly
  63 need the same customizations. Instead of duplicating these
  64 customizations for each project, it is recommended to use a layered
  65 customization approach, as explained in this section.
  66
  67 Almost all of the customization methods available in Buildroot, like
  68 post-build scripts and root filesystem overlays, accept a
  69 space-separated list of items. The specified items are always treated in
  70 order, from left to right. By creating more than one such item, one for
  71 the common customizations and another one for the really
  72 project-specific customizations, you can avoid unnecessary duplication.
  73 Each layer is typically embodied by a separate directory inside
  74 +board/<company>/+. Depending on your projects, you could even introduce
  75 more than two layers.
  76
  77 An example directory structure for where a user has two customization
  78 layers 'common' and 'fooboard' is:
  79
  80 -----
  81 +-- board/
  82     +-- <company>/
  83         +-- common/
  84         |   +-- post_build.sh
  85         |   +-- rootfs_overlay/
  86         |   |   +-- ...
  87         |   +-- patches/
  88         |       +-- ...
  89         |
  90         +-- fooboard/
  91             +-- linux.config
  92             +-- busybox.config
  93             +-- <other configuration files>
  94             +-- post_build.sh
  95             +-- rootfs_overlay/
  96             |   +-- ...
  97             +-- patches/
  98                 +-- ...
  99 -----
 100
 101 For example, if the user has the +BR2_GLOBAL_PATCH_DIR+ configuration
 102 option set as:
 103
 104 -----
 105 BR2_GLOBAL_PATCH_DIR="board/<company>/common/patches board/<company>/fooboard/patches"
 106 -----
 107
 108 then first the patches from the 'common' layer would be applied,
 109 followed by the patches from the 'fooboard' layer.