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