// -*- 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) -r $(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_PYTHON3),y) LIBFOO_CONF_OPTS += --with-python-support LIBFOO_DEPENDENCIES += python3 else LIBFOO_CONF_OPTS += --without-python-support endif --------------------- + NO: + --------------------- LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON3),,out)-python-support LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON3),python3,) --------------------- ** 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) -r $(TARGET_DIR)/usr/share/libfoo/data endef LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA endif --------------------- + NO: + --------------------- define LIBFOO_REMOVE_DATA $(RM) -r $(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. * Allowed notations for +offset+ and +size+ options are: +G+, +M+, +K+ (not +k+). If it's not possible to express a precise byte count with notations above then use hexadecimal +0x+ prefix or, as last chance, the byte count. In comments instead use +GB+, +MB+, +KB+ (not +kb+) in place of +G+, +M+, +K+. * For GPT partitions, the +partition-type-uuid+ value must be +U+ for the EFI System Partition (expanded to +c12a7328-f81f-11d2-ba4b-00a0c93ec93b+ by _genimage_), +F+ for a FAT partition (expanded to +ebd0a0a2-b9e5-4433-87c0-68b6b72699c7+ by _genimage_) or +L+ for the root filesystem or other filesystems (expanded to +0fc63daf-8483-4772-8e79-3d69d8477de4+ by _genimage_). Even though +L+ is the default value of _genimage_, we prefer to have it explicitly specified in our +genimage.cfg+ files. Finally, these shortcuts should be used without double quotes, e.g +partition-type-uuid = U+. If an explicit GUID is specified, lower-case letters should be used. 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 https://asciidoc-py.github.io/[asciidoc] format. For further details about the asciidoc syntax, refer to https://asciidoc-py.github.io/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].