customize-directory-structure.txt 3.6 KB

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