docs/manual/writing-rules.txt - buildroot - Git at Google

 // -*- 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].
	// -- 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].