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.

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.adoc.

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_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) -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

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 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 PEP8 Style Guide for Python Code.