docs/manual/writing-rules.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 == Coding style
   5
   6 Overall, these coding style rules are here to help you to add new files in
   7 Buildroot or refactor existing ones.
   8
   9 If you slightly modify some existing file, the important thing is
  10 to keep the consistency of the whole file, so you can:
  11
  12 * either follow the potentially deprecated coding style used in this
  13 file,
  14
  15 * or entirely rework it in order to make it comply with these rules.
  16
  17 [[writing-rules-config-in]]
  18
  19 === +Config.in+ file
  20
  21 +Config.in+ files contain entries for almost anything configurable in
  22 Buildroot.
  23
  24 An entry has the following pattern:
  25
  26 ---------------------
  27 config BR2_PACKAGE_LIBFOO
  28         bool "libfoo"
  29         depends on BR2_PACKAGE_LIBBAZ
  30         select BR2_PACKAGE_LIBBAR
  31         help
  32           This is a comment that explains what libfoo is.
  33
  34           http://foosoftware.org/libfoo/
  35 ---------------------
  36
  37 * The +bool+, +depends on+, +select+ and +help+ lines are indented
  38   with one tab.
  39
  40 * The help text itself should be indented with one tab and two
  41   spaces.
  42
  43 * The help text should be wrapped to fit 72 columns.
  44
  45 The +Config.in+ files are the input for the configuration tool
  46 used in Buildroot, which is the regular _Kconfig_. For further
  47 details about the _Kconfig_ language, refer to
  48 http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
  49
  50 [[writing-rules-mk]]
  51
  52 === The +.mk+ file
  53
  54 * Header: The file starts with a header. It contains the module name,
  55 preferably in lowercase, enclosed between separators made of 80 hashes. A
  56 blank line is mandatory after the header:
  57 +
  58 ---------------------
  59 ################################################################################
  60 #
  61 # libfoo
  62 #
  63 ################################################################################
  64 ---------------------
  65 +
  66 * Assignment: use +=+ preceded and followed by one space:
  67 +
  68 ---------------------
  69 LIBFOO_VERSION = 1.0
  70 LIBFOO_CONF_OPTS += --without-python-support
  71 ---------------------
  72 +
  73 Do not align the +=+ signs.
  74
  75 * Indentation: use tab only:
  76 +
  77 ---------------------
  78 define LIBFOO_REMOVE_DOC
  79         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
  80                 $(TARGET_DIR)/usr/share/man/man3/libfoo*
  81 endef
  82 ---------------------
  83 +
  84 Note that commands inside a +define+ block should always start with a tab,
  85 so _make_ recognizes them as commands.
  86
  87 * Optional dependency:
  88
  89 ** Prefer multi-line syntax.
  90 +
  91 YES:
  92 +
  93 ---------------------
  94 ifeq ($(BR2_PACKAGE_PYTHON),y)
  95 LIBFOO_CONF_OPTS += --with-python-support
  96 LIBFOO_DEPENDENCIES += python
  97 else
  98 LIBFOO_CONF_OPTS += --without-python-support
  99 endif
 100 ---------------------
 101 +
 102 NO:
 103 +
 104 ---------------------
 105 LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
 106 LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
 107 ---------------------
 108
 109 ** Keep configure options and dependencies close together.
 110
 111 * Optional hooks: keep hook definition and assignment together in one
 112   if block.
 113 +
 114 YES:
 115 +
 116 ---------------------
 117 ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 118 define LIBFOO_REMOVE_DATA
 119         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 120 endef
 121 LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 122 endif
 123 ---------------------
 124 +
 125 NO:
 126 +
 127 ---------------------
 128 define LIBFOO_REMOVE_DATA
 129         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 130 endef
 131
 132 ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 133 LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 134 endif
 135 ---------------------
 136
 137 === The documentation
 138
 139 The documentation uses the
 140 http://www.methods.co.nz/asciidoc/[asciidoc] format.
 141
 142 For further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
 143 syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html[].