customize-store.txt 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. [[customize-store-basics]]
  4. === Basics for storing the configuration
  5. When you have a buildroot configuration that you are satisfied with and
  6. you want to share it with others, put it under revision control or move
  7. on to a different buildroot project, you need to store the configuration
  8. so it can be rebuilt later. The configuration that needs to be stored
  9. consists of the buildroot configuration, the configuration files for
  10. packages that you use (kernel, busybox, uClibc, ...), and your rootfs
  11. modifications.
  12. [[customize-store-buildroot-config]]
  13. ==== Buildroot configuration
  14. For storing the buildroot configuration itself, buildroot offers the
  15. following command: +make savedefconfig+.
  16. This strips the buildroot configuration down by removing configuration
  17. options that are at their default value. The result is stored in a file
  18. called +defconfig+. If you want to save it in another place, change
  19. the +BR2_DEFCONFIG+ option, or call make with +make savedefconfig
  20. BR2_DEFCONFIG=<path-to-defconfig>+. The usual place is
  21. +configs/<boardname>_defconfig+. The configuration can then be rebuilt by
  22. running +make <boardname>_defconfig+.
  23. Alternatively, you can copy the file to any other place and rebuild with
  24. +make defconfig BR2_DEFCONFIG=<path-to-defconfig-file>+.
  25. [[customize-store-package-config]]
  26. ==== Other package configuration
  27. The configuration files for busybox, the linux kernel, barebox and
  28. uClibc should be stored as well if changed. For each of these, a
  29. buildroot configuration option exists to point to an input
  30. configuration file, e.g. +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. To
  31. save their configuration, set those configuration options to a path
  32. outside your output directory,
  33. e.g. +board/<manufacturer>/<boardname>/linux.config+. Then, copy the
  34. configuration files to that path.
  35. Make sure that you create a configuration file 'before' changing
  36. the +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+ etc. options. Otherwise,
  37. buildroot will try to access this config file, which doesn't exist
  38. yet, and will fail. You can create the configuration file by running
  39. +make linux-menuconfig+ etc.
  40. Buildroot provides a few helper targets to make the saving of
  41. configuration files easier.
  42. * +make linux-update-defconfig+ saves the linux configuration to the
  43. path specified by +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+. It
  44. simplifies the config file by removing default values. However,
  45. this only works with kernels starting from 2.6.33. For earlier
  46. kernels, use +make linux-update-config+.
  47. * +make busybox-update-config+ saves the busybox configuration to the
  48. path specified by +BR2_PACKAGE_BUSYBOX_CONFIG+.
  49. * +make uclibc-update-config+ saves the uClibc configuration to the
  50. path specified by +BR2_UCLIBC_CONFIG+.
  51. * +make barebox-update-defconfig+ saves the barebox configuration to the
  52. path specified by +BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE+.
  53. * For at91bootstrap3, no helper exists so you have to copy the config
  54. file manually to +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+.
  55. [[customize-store-board-support]]
  56. === Creating your own board support
  57. Creating your own board support in Buildroot allows users of a
  58. particular hardware platform to easily build a system that is known to
  59. work.
  60. To do so, you need to create a normal Buildroot configuration that
  61. builds a basic system for the hardware: toolchain, kernel, bootloader,
  62. filesystem and a simple BusyBox-only userspace. No specific package
  63. should be selected: the configuration should be as minimal as
  64. possible, and should only build a working basic BusyBox system for the
  65. target platform. You can of course use more complicated configurations
  66. for your internal projects, but the Buildroot project will only
  67. integrate basic board configurations. This is because package
  68. selections are highly application-specific.
  69. Once you have a known working configuration, run +make
  70. savedefconfig+. This will generate a minimal +defconfig+ file at the
  71. root of the Buildroot source tree. Move this file into the +configs/+
  72. directory, and rename it +<boardname>_defconfig+.
  73. It is recommended to use as much as possible upstream versions of the
  74. Linux kernel and bootloaders, and to use as much as possible default
  75. kernel and bootloader configurations. If they are incorrect for your
  76. board, or no default exists, we encourage you to send fixes to the
  77. corresponding upstream projects.
  78. However, in the mean time, you may want to store kernel or bootloader
  79. configuration or patches specific to your target platform. To do so,
  80. create a directory +board/<manufacturer>+ and a subdirectory
  81. +board/<manufacturer>/<boardname>+. You can then store your patches
  82. and configurations in these directories, and reference them from the main
  83. Buildroot configuration.
  84. === Step-by-step instructions for storing configuration
  85. To store the configuration for a specific product, device or
  86. application, it is advisable to use the same conventions as for the
  87. board support: put the buildroot defconfig in the +configs+ directory,
  88. and any other files in a subdirectory of the +boards+ directory. This
  89. section gives step-by-step instructions about how to do that. Of course,
  90. you can skip the steps that are not relevant for your use case.
  91. 1. +make menuconfig+ to configure toolchain, packages and kernel.
  92. 1. +make linux-menuconfig+ to update the kernel config, similar for
  93. other configuration.
  94. 1. +mkdir -p board/<manufacturer>/<boardname>+
  95. 1. Set the following options to +board/<manufacturer>/<boardname>/<package>.config+
  96. (as far as they are relevant):
  97. * +BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE+
  98. * +BR2_PACKAGE_BUSYBOX_CONFIG+
  99. * +BR2_UCLIBC_CONFIG+
  100. * +BR2_TARGET_AT91BOOTSTRAP3_CUSTOM_CONFIG_FILE+
  101. * +BR2_TARGET_BAREBOX_CUSTOM_CONFIG_FILE+
  102. 1. Write the configuration files:
  103. * +make linux-update-defconfig+
  104. * +make busybox-update-config+
  105. * +make uclibc-update-config+
  106. * +cp <output>/build/at91bootstrap3-*/.config board/<manufacturer>/<boardname>/at91bootstrap3.config+
  107. * +make barebox-update-defconfig+
  108. 1. Create +board/<manufacturer>/<boardname>/fs-overlay/+ and fill it
  109. with additional files you need on your rootfs, e.g.
  110. +board/<manufacturer>/<boardname>/fs-overlay/etc/inittab+.
  111. Set +BR2_ROOTFS_OVERLAY+
  112. to +board/<manufacturer>/<boardname>/fs-overlay+.
  113. 1. Create a post-build script
  114. +board/<manufacturer>/<boardname>/post-build.sh+. Set
  115. +BR2_ROOTFS_POST_BUILD_SCRIPT+ to
  116. +board/<manufacturer>/<boardname>/post-build.sh+
  117. 1. If additional setuid permissions have to be set or device nodes have
  118. to be created, create +board/<manufacturer>/<boardname>/device_table.txt+
  119. and add that path to +BR2_ROOTFS_DEVICE_TABLE+.
  120. 1. +make savedefconfig+ to save the buildroot configuration.
  121. 1. +cp defconfig configs/<boardname>_defconfig+
  122. 1. To add patches to the linux build, set +BR2_LINUX_KERNEL_PATCH+ to
  123. +board/<manufacturer>/<boardname>/patches/linux/+ and add your
  124. patches in that directory. Each patch should be called
  125. +linux-<num>-<description>.patch+. Similar for U-Boot, barebox,
  126. at91bootstrap and at91bootstrap3.
  127. 1. If you need modifications to other packages, or if you need to add
  128. packages, do that directly in the +packages/+ directory, following the
  129. instructions in xref:adding-packages[].