writing-rules.txt 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. == Coding style
  4. Overall, these coding style rules are here to help you to add new files in
  5. Buildroot or refactor existing ones.
  6. If you slightly modify some existing file, the important thing is
  7. to keep the consistency of the whole file, so you can:
  8. * either follow the potentially deprecated coding style used in this
  9. file,
  10. * or entirely rework it in order to make it comply with these rules.
  11. [[writing-rules-config-in]]
  12. === +Config.in+ file
  13. +Config.in+ files contain entries for almost anything configurable in
  14. Buildroot.
  15. An entry has the following pattern:
  16. ---------------------
  17. config BR2_PACKAGE_LIBFOO
  18. bool "libfoo"
  19. depends on BR2_PACKAGE_LIBBAZ
  20. select BR2_PACKAGE_LIBBAR
  21. help
  22. This is a comment that explains what libfoo is. The help text
  23. should be wrapped.
  24. http://foosoftware.org/libfoo/
  25. ---------------------
  26. * The +bool+, +depends on+, +select+ and +help+ lines are indented
  27. with one tab.
  28. * The help text itself should be indented with one tab and two
  29. spaces.
  30. * The help text should be wrapped to fit 72 columns, where tab counts
  31. for 8, so 62 characters in the text itself.
  32. The +Config.in+ files are the input for the configuration tool
  33. used in Buildroot, which is the regular _Kconfig_. For further
  34. details about the _Kconfig_ language, refer to
  35. http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
  36. [[writing-rules-mk]]
  37. === The +.mk+ file
  38. * Header: The file starts with a header. It contains the module name,
  39. preferably in lowercase, enclosed between separators made of 80 hashes. A
  40. blank line is mandatory after the header:
  41. +
  42. ---------------------
  43. ################################################################################
  44. #
  45. # libfoo
  46. #
  47. ################################################################################
  48. ---------------------
  49. +
  50. * Assignment: use +=+ preceded and followed by one space:
  51. +
  52. ---------------------
  53. LIBFOO_VERSION = 1.0
  54. LIBFOO_CONF_OPTS += --without-python-support
  55. ---------------------
  56. +
  57. Do not align the +=+ signs.
  58. * Indentation: use tab only:
  59. +
  60. ---------------------
  61. define LIBFOO_REMOVE_DOC
  62. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
  63. $(TARGET_DIR)/usr/share/man/man3/libfoo*
  64. endef
  65. ---------------------
  66. +
  67. Note that commands inside a +define+ block should always start with a tab,
  68. so _make_ recognizes them as commands.
  69. * Optional dependency:
  70. ** Prefer multi-line syntax.
  71. +
  72. YES:
  73. +
  74. ---------------------
  75. ifeq ($(BR2_PACKAGE_PYTHON),y)
  76. LIBFOO_CONF_OPTS += --with-python-support
  77. LIBFOO_DEPENDENCIES += python
  78. else
  79. LIBFOO_CONF_OPTS += --without-python-support
  80. endif
  81. ---------------------
  82. +
  83. NO:
  84. +
  85. ---------------------
  86. LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
  87. LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
  88. ---------------------
  89. ** Keep configure options and dependencies close together.
  90. * Optional hooks: keep hook definition and assignment together in one
  91. if block.
  92. +
  93. YES:
  94. +
  95. ---------------------
  96. ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  97. define LIBFOO_REMOVE_DATA
  98. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  99. endef
  100. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  101. endif
  102. ---------------------
  103. +
  104. NO:
  105. +
  106. ---------------------
  107. define LIBFOO_REMOVE_DATA
  108. $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
  109. endef
  110. ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
  111. LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
  112. endif
  113. ---------------------
  114. [[writing-genimage-cfg]]
  115. === The +genimage.cfg+ file
  116. +genimage.cfg+ files contain the output image layout that genimage utility
  117. uses to create final .img file.
  118. An example follows:
  119. ---------------------
  120. image efi-part.vfat {
  121. vfat {
  122. file EFI {
  123. image = "efi-part/EFI"
  124. }
  125. file Image {
  126. image = "Image"
  127. }
  128. }
  129. size = 32M
  130. }
  131. image sdimage.img {
  132. hdimage {
  133. }
  134. partition u-boot {
  135. image = "efi-part.vfat"
  136. offset = 8K
  137. }
  138. partition root {
  139. image = "rootfs.ext2"
  140. size = 512M
  141. }
  142. }
  143. ---------------------
  144. * Every +section+(i.e. hdimage, vfat etc.), +partition+ must be indented
  145. with one tab.
  146. * Every +file+ or other +subnode+ must be indented with two tabs.
  147. * Every node(+section+, +partition+, +file+, +subnode+) must have an open
  148. curly bracket on the same line of the node's name, while the closing one
  149. must be on a newline and after it a newline must be added except for the
  150. last one node. Same goes for its option, for example option +size = +.
  151. * Every +option+(i.e. +image+, +offset+, +size+) must have the +=+
  152. assignment one space from it and one space from the value specified.
  153. * Filename must at least begin with genimage prefix and have the .cfg
  154. extension to be easy to recognize.
  155. The +genimage.cfg+ files are the input for the genimage tool used in
  156. Buildroot to generate the final image file(i.e. sdcard.img). For further
  157. details about the _genimage_ language, refer to
  158. https://github.com/pengutronix/genimage/blob/master/README.rst[].
  159. === The documentation
  160. The documentation uses the
  161. http://www.methods.co.nz/asciidoc/[asciidoc] format.
  162. For further details about the asciidoc syntax, refer to
  163. http://www.methods.co.nz/asciidoc/userguide.html[].
  164. === Support scripts
  165. Some scripts in the +support/+ and +utils/+ directories are written in
  166. Python and should follow the
  167. https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code].