docs/writing-rules.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 Coding style
   5 ------------
   6
   7 Overall, these coding style rules are here to help you to add new files in
   8 OpenADK or refactor existing ones.
   9
  10 [[writing-rules-config-in]]
  11
  12 +Config.in+
  13 ~~~~~~~~~~~
  14
  15 +Config.in+ files contain entries for almost anything configurable in
  16 OpenADK. Mostly all Config.in files for packages are autogenerated and
  17 should not be manually edited. The following rules apply for the top level
  18 Config.in, for the files in target/config and target/linux/config.
  19
  20 An entry has the following pattern:
  21
  22 ---------------------
  23 config ADK_TARGET_FOO
  24         prompt "foo"
  25         boolean
  26         select BR2_PACKAGE_LIBBAR
  27         depends on ADK_PACKAGE_LIBBAZ
  28         default n
  29         help
  30           This is a comment that explains what foo is.
  31
  32           http://foo.org/foo/
  33 ---------------------
  34
  35 * The +boolean+, +depends on+, +default+, +select+ and +help+ lines are indented
  36   with one tab.
  37
  38 * The help text itself should be indented with one tab and two
  39   spaces.
  40
  41 The +Config.in+ files are the input for the configuration tool
  42 used in OpenADK, which is the regular _Kconfig_. For further
  43 details about the _Kconfig_ language, refer to
  44 http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
  45
  46 [[writing-rules-mk]]
  47
  48 +Makefile+
  49 ~~~~~~~~~~
  50
  51 * Header: The file starts with a license header.
  52 +
  53 ---------------------
  54 # This file is part of the OpenADK project. OpenADK is copyrighted
  55 # material, please see the LICENCE file in the top-level directory.
  56 ---------------------
  57 +
  58 * Assignment: use +:=+ or ++=+ followed by two tabs:
  59 +
  60 ---------------------
  61 PKG_VERSION:=           1.0
  62 PKG_BUILDDEP+=          libfoo
  63 ---------------------
  64 +
  65
  66 * Indentation: use tab only:
  67 +
  68 ---------------------
  69 libfoo-install:
  70         $(CP) $(WRKINST)/usr/lib/libfoo*.so* \
  71                 $(IDIR_LIBFOO)/usr/lib
  72 ---------------------
  73 +
  74
  75 * Optional dependency:
  76
  77 ** Prefer multi-line syntax.
  78 ---------------------
  79 ifeq ($(ADK_PACKAGE_LIBFOO_WITH_PYTHON),y)
  80 CONFIGURE_ARGS+=        --with-python-support
  81 else
  82 CONFIGURE_ARGS+=        --without-python-support
  83 endif
  84 ---------------------
  85
  86 Documentation
  87 ~~~~~~~~~~~~~
  88
  89 The documentation uses the
  90 http://www.methods.co.nz/asciidoc/[asciidoc] format.
  91
  92 For further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
  93 syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html[].