123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213 |
- // -*- mode:doc; -*-
- // vim: set syntax=asciidoc:
- == Coding style
- Overall, these coding style rules are here to help you to add new files in
- Buildroot or refactor existing ones.
- If you slightly modify some existing file, the important thing is
- to keep the consistency of the whole file, so you can:
- * either follow the potentially deprecated coding style used in this
- file,
- * or entirely rework it in order to make it comply with these rules.
- [[writing-rules-config-in]]
- === +Config.in+ file
- +Config.in+ files contain entries for almost anything configurable in
- Buildroot.
- An entry has the following pattern:
- ---------------------
- config BR2_PACKAGE_LIBFOO
- bool "libfoo"
- depends on BR2_PACKAGE_LIBBAZ
- select BR2_PACKAGE_LIBBAR
- help
- This is a comment that explains what libfoo is. The help text
- should be wrapped.
- http://foosoftware.org/libfoo/
- ---------------------
- * The +bool+, +depends on+, +select+ and +help+ lines are indented
- with one tab.
- * The help text itself should be indented with one tab and two
- spaces.
- * The help text should be wrapped to fit 72 columns, where tab counts
- for 8, so 62 characters in the text itself.
- The +Config.in+ files are the input for the configuration tool
- used in Buildroot, which is the regular _Kconfig_. For further
- details about the _Kconfig_ language, refer to
- http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
- [[writing-rules-mk]]
- === The +.mk+ file
- * Header: The file starts with a header. It contains the module name,
- preferably in lowercase, enclosed between separators made of 80 hashes. A
- blank line is mandatory after the header:
- +
- ---------------------
- ################################################################################
- #
- # libfoo
- #
- ################################################################################
- ---------------------
- +
- * Assignment: use +=+ preceded and followed by one space:
- +
- ---------------------
- LIBFOO_VERSION = 1.0
- LIBFOO_CONF_OPTS += --without-python-support
- ---------------------
- +
- Do not align the +=+ signs.
- * Indentation: use tab only:
- +
- ---------------------
- define LIBFOO_REMOVE_DOC
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
- $(TARGET_DIR)/usr/share/man/man3/libfoo*
- endef
- ---------------------
- +
- Note that commands inside a +define+ block should always start with a tab,
- so _make_ recognizes them as commands.
- * Optional dependency:
- ** Prefer multi-line syntax.
- +
- YES:
- +
- ---------------------
- ifeq ($(BR2_PACKAGE_PYTHON),y)
- LIBFOO_CONF_OPTS += --with-python-support
- LIBFOO_DEPENDENCIES += python
- else
- LIBFOO_CONF_OPTS += --without-python-support
- endif
- ---------------------
- +
- NO:
- +
- ---------------------
- LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support
- LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,)
- ---------------------
- ** Keep configure options and dependencies close together.
- * Optional hooks: keep hook definition and assignment together in one
- if block.
- +
- YES:
- +
- ---------------------
- ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
- define LIBFOO_REMOVE_DATA
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
- endef
- LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
- endif
- ---------------------
- +
- NO:
- +
- ---------------------
- define LIBFOO_REMOVE_DATA
- $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data
- endef
- ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
- LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
- endif
- ---------------------
- [[writing-genimage-cfg]]
- === The +genimage.cfg+ file
- +genimage.cfg+ files contain the output image layout that genimage utility
- uses to create final .img file.
- An example follows:
- ---------------------
- image efi-part.vfat {
- vfat {
- file EFI {
- image = "efi-part/EFI"
- }
- file Image {
- image = "Image"
- }
- }
- size = 32M
- }
- image sdimage.img {
- hdimage {
- }
- partition u-boot {
- image = "efi-part.vfat"
- offset = 8K
- }
- partition root {
- image = "rootfs.ext2"
- size = 512M
- }
- }
- ---------------------
- * Every +section+(i.e. hdimage, vfat etc.), +partition+ must be indented
- with one tab.
- * Every +file+ or other +subnode+ must be indented with two tabs.
- * Every node(+section+, +partition+, +file+, +subnode+) must have an open
- curly bracket on the same line of the node's name, while the closing one
- must be on a newline and after it a newline must be added except for the
- last one node. Same goes for its option, for example option +size = +.
- * Every +option+(i.e. +image+, +offset+, +size+) must have the +=+
- assignment one space from it and one space from the value specified.
- * Filename must at least begin with genimage prefix and have the .cfg
- extension to be easy to recognize.
- The +genimage.cfg+ files are the input for the genimage tool used in
- Buildroot to generate the final image file(i.e. sdcard.img). For further
- details about the _genimage_ language, refer to
- https://github.com/pengutronix/genimage/blob/master/README.rst[].
- === The documentation
- The documentation uses the
- http://www.methods.co.nz/asciidoc/[asciidoc] format.
- For further details about the asciidoc syntax, refer to
- http://www.methods.co.nz/asciidoc/userguide.html[].
- === Support scripts
- Some scripts in the +support/+ and +utils/+ directories are written in
- Python and should follow the
- https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code].
|