customize-rootfs.txt 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. [[rootfs-custom]]
  4. === Customizing the generated target filesystem
  5. Besides changing the configuration through +make *config+,
  6. there are a few other ways to customize the resulting target filesystem.
  7. The two recommended methods, which can co-exist, are root filesystem
  8. overlay(s) and post build script(s).
  9. Root filesystem overlays (+BR2_ROOTFS_OVERLAY+)::
  10. +
  11. A filesystem overlay is a tree of files that is copied directly
  12. over the target filesystem after it has been built. To enable this
  13. feature, set config option +BR2_ROOTFS_OVERLAY+ (in the +System
  14. configuration+ menu) to the root of the overlay. You can even specify
  15. multiple overlays, space-separated. If you specify a relative path,
  16. it will be relative to the root of the Buildroot tree. Hidden
  17. directories of version control systems, like +.git+, +.svn+, +.hg+,
  18. etc., files called +.empty+ and files ending in +~+ are excluded from
  19. the copy.
  20. +
  21. When +BR2_ROOTFS_MERGED_USR+ is enabled, then the overlay must not
  22. contain the '/bin', '/lib' or '/sbin' directories, as Buildroot will
  23. create them as symbolic links to the relevant folders in '/usr'. In
  24. such a situation, should the overlay have any programs or libraries,
  25. they should be placed in '/usr/bin', '/usr/sbin' and '/usr/lib'.
  26. +
  27. As shown in xref:customize-dir-structure[], the recommended path for
  28. this overlay is +board/<company>/<boardname>/rootfs-overlay+.
  29. Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+)::
  30. +
  31. Post-build scripts are shell scripts called 'after' Buildroot builds
  32. all the selected software, but 'before' the rootfs images are
  33. assembled. To enable this feature, specify a space-separated list of
  34. post-build scripts in config option +BR2_ROOTFS_POST_BUILD_SCRIPT+ (in
  35. the +System configuration+ menu). If you specify a relative path, it
  36. will be relative to the root of the Buildroot tree.
  37. +
  38. Using post-build scripts, you can remove or modify any file in your
  39. target filesystem. You should, however, use this feature with care.
  40. Whenever you find that a certain package generates wrong or unneeded
  41. files, you should fix that package rather than work around it with some
  42. post-build cleanup scripts.
  43. +
  44. As shown in xref:customize-dir-structure[], the recommended path for
  45. this script is +board/<company>/<boardname>/post_build.sh+.
  46. +
  47. The post-build scripts are run with the main Buildroot tree as current
  48. working directory. The path to the target filesystem is passed as the
  49. first argument to each script. If the config option
  50. +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these arguments will be
  51. passed to the script too. All the scripts will be passed the exact
  52. same set of arguments, it is not possible to pass different sets of
  53. arguments to each script.
  54. +
  55. In addition, you may also use these environment variables:
  56. - +BR2_CONFIG+: the path to the Buildroot .config file
  57. - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
  58. xref:generic-package-reference[]
  59. - +BUILD_DIR+: the directory where packages are extracted and built
  60. - +BINARIES_DIR+: the place where all binary files (aka images) are
  61. stored
  62. - +BASE_DIR+: the base output directory
  63. Below three more methods of customizing the target filesystem are
  64. described, but they are not recommended.
  65. Direct modification of the target filesystem::
  66. +
  67. For temporary modifications, you can modify the target filesystem
  68. directly and rebuild the image. The target filesystem is available
  69. under +output/target/+. After making your changes, run +make+ to
  70. rebuild the target filesystem image.
  71. +
  72. This method allows you to do anything to the target filesystem, but if
  73. you need to clean your Buildroot tree using +make clean+, these
  74. changes will be lost. Such cleaning is necessary in several cases,
  75. refer to xref:full-rebuild[] for details. This solution is therefore
  76. only useful for quick tests: _changes do not survive the +make clean+
  77. command_. Once you have validated your changes, you should make sure
  78. that they will persist after a +make clean+, using a root filesystem
  79. overlay or a post-build script.
  80. Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+)::
  81. +
  82. The root filesystem image is created from a target skeleton, on top of
  83. which all packages install their files. The skeleton is copied to the
  84. target directory +output/target+ before any package is built and
  85. installed. The default target skeleton provides the standard Unix
  86. filesystem layout and some basic init scripts and configuration files.
  87. +
  88. If the default skeleton (available under +system/skeleton+) does not
  89. match your needs, you would typically use a root filesystem overlay or
  90. post-build script to adapt it. However, if the default skeleton is
  91. entirely different than what you need, using a custom skeleton may be
  92. more suitable.
  93. +
  94. To enable this feature, enable config option
  95. +BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+
  96. to the path of your custom skeleton. Both options are available in the
  97. +System configuration+ menu. If you specify a relative path, it will
  98. be relative to the root of the Buildroot tree.
  99. +
  100. Custom skeletons don't need to contain the '/bin', '/lib' or '/sbin'
  101. directories, since they are created automatically during the build.
  102. When +BR2_ROOTFS_MERGED_USR+ is enabled, then the custom skeleton must
  103. not contain the '/bin', '/lib' or '/sbin' directories, as Buildroot
  104. will create them as symbolic links to the relevant folders in '/usr'.
  105. In such a situation, should the skeleton have any programs or
  106. libraries, they should be placed in '/usr/bin', '/usr/sbin' and
  107. '/usr/lib'.
  108. +
  109. This method is not recommended because it duplicates the entire
  110. skeleton, which prevents taking advantage of the fixes or improvements
  111. brought to the default skeleton in later Buildroot releases.
  112. Post-fakeroot scripts (+BR2_ROOTFS_POST_FAKEROOT_SCRIPT+)::
  113. +
  114. When aggregating the final images, some parts of the process requires
  115. root rights: creating device nodes in `/dev`, setting permissions or
  116. ownership to files and directories... To avoid requiring actual root
  117. rights, Buildroot uses +fakeroot+ to simulate root rights. This is not
  118. a complete substitute for actually being root, but is enough for what
  119. Buildroot needs.
  120. +
  121. Post-fakeroot scripts are shell scripts that are called at the 'end' of
  122. the fakeroot phase, 'right before' the filesystem image generator is
  123. called. As such, they are called in the fakeroot context.
  124. +
  125. Post-fakeroot scripts can be useful in case you need to tweak the
  126. filesystem to do modifications that are usually only available to the
  127. root user.
  128. +
  129. .Note:
  130. It is recommended to use the existing mechanisms to set file permissions
  131. or create entries in `/dev` (see xref:customize-device-permission[]) or
  132. to create users (see xref:customize-users[])
  133. +
  134. .Note:
  135. The difference between post-build scripts (above) and fakeroot scripts,
  136. is that post-build scripts are not called in the fakeroot context.
  137. +
  138. .Note:
  139. Using `fakeroot` is not an absolute substitute for actually being root.
  140. `fakeroot` only ever fakes the file access rights and types (regular,
  141. block-or-char device...) and uid/gid; these are emulated in-memory.
  142. include::customize-device-permission-tables.txt[]