writing-rules.txt 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  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. === The documentation
  115. The documentation uses the
  116. http://www.methods.co.nz/asciidoc/[asciidoc] format.
  117. For further details about the asciidoc syntax, refer to
  118. http://www.methods.co.nz/asciidoc/userguide.html[].
  119. === Support scripts
  120. Some scripts in the +support/+ and +utils/+ directories are written in
  121. Python and should follow the
  122. https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code].