cirros-testvm/src-cirros/buildroot-2015.05/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 +Config.in+ files are the input for the configuration tool
  44 used in Buildroot, which is the regular _Kconfig_. For further
  45 details about the _Kconfig_ language, refer to
  46 http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
  47
  48 [[writing-rules-mk]]
  49
  50 === The +.mk+ file
  51
  52 * Header: The file starts with a header. It contains the module name,
  53 preferably in lowercase, enclosed between separators made of 80 hashes. A
  54 blank line is mandatory after the header:
  55 +
  56 ---------------------
  57 ################################################################################
  58 #
  59 # libfoo
  60 #
  61 ################################################################################
  62 ---------------------
  63 +
  64 * Assignment: use +=+ preceded and followed by one space:
  65 +
  66 ---------------------
  67 LIBFOO_VERSION = 1.0
  68 LIBFOO_CONF_OPTS += --without-python-support
  69 ---------------------
  70 +
  71 Do not align the +=+ signs.
  72
  73 * Indentation: use tab only:
  74 +
  75 ---------------------
  76 define LIBFOO_REMOVE_DOC
  77         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
  78                 $(TARGET_DIR)/usr/share/man/man3/libfoo*
  79 endef
  80 ---------------------
  81 +
  82 Note that commands inside a +define+ block should always start with a tab,
  83 so _make_ recognizes them as commands.
  84
  85 * Optional dependency:
  86
  87 ** Prefer multi-line syntax.
  88 +
  89 YES:
  90 +
  91 ---------------------
  92 ifeq ($(BR2_PACKAGE_PYTHON),y)
  93 LIBFOO_CONF_OPTS += --with-python-support
  94 LIBFOO_DEPENDENCIES += python
  95 else
  96 LIBFOO_CONF_OPTS += --without-python-support
  97 endif
  98 ---------------------
  99 +
 100 NO:
 101 +
 102 ---------------------
 103 LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
 104 LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
 105 ---------------------
 106
 107 ** Keep configure options and dependencies close together.
 108
 109 * Optional hooks: keep hook definition and assignment together in one
 110   if block.
 111 +
 112 YES:
 113 +
 114 ---------------------
 115 ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 116 define LIBFOO_REMOVE_DATA
 117         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 118 endef
 119 LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 120 endif
 121 ---------------------
 122 +
 123 NO:
 124 +
 125 ---------------------
 126 define LIBFOO_REMOVE_DATA
 127         $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
 128 endef
 129
 130 ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
 131 LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
 132 endif
 133 ---------------------
 134
 135 === The documentation
 136
 137 The documentation uses the
 138 http://www.methods.co.nz/asciidoc/[asciidoc] format.
 139
 140 For further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
 141 syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html[].