1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc:
3
4== Coding style
5
6Overall, these coding style rules are here to help you to add new files in
7Buildroot or refactor existing ones.
8
9If you slightly modify some existing file, the important thing is
10to keep the consistency of the whole file, so you can:
11
12* either follow the potentially deprecated coding style used in this
13file,
14
15* or entirely rework it in order to make it comply with these rules.
16
17[[writing-rules-config-in]]
18
19=== +Config.in+ file
20
21+Config.in+ files contain entries for almost anything configurable in
22Buildroot.
23
24An entry has the following pattern:
25
26---------------------
27config BR2_PACKAGE_LIBFOO
28	bool "libfoo"
29	depends on BR2_PACKAGE_LIBBAZ
30	select BR2_PACKAGE_LIBBAR
31	help
32	  This is a comment that explains what libfoo is. The help text
33	  should be wrapped.
34
35	  http://foosoftware.org/libfoo/
36---------------------
37
38* The +bool+, +depends on+, +select+ and +help+ lines are indented
39  with one tab.
40
41* The help text itself should be indented with one tab and two
42  spaces.
43
44* The help text should be wrapped to fit 72 columns, where tab counts
45  for 8, so 62 characters in the text itself.
46
47The +Config.in+ files are the input for the configuration tool
48used in Buildroot, which is the regular _Kconfig_. For further
49details about the _Kconfig_ language, refer to
50http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
51
52[[writing-rules-mk]]
53
54=== The +.mk+ file
55
56* Header: The file starts with a header. It contains the module name,
57preferably in lowercase, enclosed between separators made of 80 hashes. A
58blank line is mandatory after the header:
59+
60---------------------
61################################################################################
62#
63# libfoo
64#
65################################################################################
66---------------------
67+
68* Assignment: use +=+ preceded and followed by one space:
69+
70---------------------
71LIBFOO_VERSION = 1.0
72LIBFOO_CONF_OPTS += --without-python-support
73---------------------
74+
75Do not align the +=+ signs.
76
77* Indentation: use tab only:
78+
79---------------------
80define LIBFOO_REMOVE_DOC
81	$(RM) -r $(TARGET_DIR)/usr/share/libfoo/doc \
82		$(TARGET_DIR)/usr/share/man/man3/libfoo*
83endef
84---------------------
85+
86Note that commands inside a +define+ block should always start with a tab,
87so _make_ recognizes them as commands.
88
89* Optional dependency:
90
91** Prefer multi-line syntax.
92+
93YES:
94+
95---------------------
96ifeq ($(BR2_PACKAGE_PYTHON3),y)
97LIBFOO_CONF_OPTS += --with-python-support
98LIBFOO_DEPENDENCIES += python3
99else
100LIBFOO_CONF_OPTS += --without-python-support
101endif
102---------------------
103+
104NO:
105+
106---------------------
107LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON3),,out)-python-support
108LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON3),python3,)
109---------------------
110
111** Keep configure options and dependencies close together.
112
113* Optional hooks: keep hook definition and assignment together in one
114  if block.
115+
116YES:
117+
118---------------------
119ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
120define LIBFOO_REMOVE_DATA
121	$(RM) -r $(TARGET_DIR)/usr/share/libfoo/data
122endef
123LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
124endif
125---------------------
126+
127NO:
128+
129---------------------
130define LIBFOO_REMOVE_DATA
131	$(RM) -r $(TARGET_DIR)/usr/share/libfoo/data
132endef
133
134ifneq ($(BR2_LIBFOO_INSTALL_DATA),y)
135LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA
136endif
137---------------------
138
139[[writing-genimage-cfg]]
140
141=== The +genimage.cfg+ file
142
143+genimage.cfg+ files contain the output image layout that genimage utility
144uses to create final .img file.
145
146An example follows:
147
148---------------------
149image efi-part.vfat {
150	vfat {
151		file EFI {
152			image = "efi-part/EFI"
153		}
154
155		file Image {
156			image = "Image"
157		}
158	}
159
160	size = 32M
161}
162
163image sdimage.img {
164	hdimage {
165	}
166
167	partition u-boot {
168		image = "efi-part.vfat"
169		offset = 8K
170	}
171
172	partition root {
173		image = "rootfs.ext2"
174		size = 512M
175	}
176}
177---------------------
178
179* Every +section+(i.e. hdimage, vfat etc.), +partition+ must be indented
180  with one tab.
181
182* Every +file+ or other +subnode+ must be indented with two tabs.
183
184* Every node(+section+, +partition+, +file+, +subnode+) must have an open
185  curly bracket on the same line of the node's name, while the closing one
186  must be on a newline and after it a newline must be added except for the
187  last one node. Same goes for its option, for example option +size+ +=+.
188
189* Every +option+(i.e. +image+, +offset+, +size+) must have the +=+
190  assignment one space from it and one space from the value specified.
191
192* Filename must at least begin with genimage prefix and have the .cfg
193  extension to be easy to recognize.
194
195* Allowed notations for +offset+ and +size+ options are: +G+, +M+, +K+
196  (not +k+).  If it's not possible to express a precise byte count
197  with notations above then use hexadecimal +0x+ prefix or, as last
198  chance, the byte count.  In comments instead use +GB+, +MB+, +KB+
199  (not +kb+) in place of +G+, +M+, +K+.
200
201* For GPT partitions, the +partition-type-uuid+ value must be +U+ for
202  the EFI System Partition (expanded to
203  +c12a7328-f81f-11d2-ba4b-00a0c93ec93b+ by _genimage_), +F+ for a FAT
204  partition (expanded to +ebd0a0a2-b9e5-4433-87c0-68b6b72699c7+ by
205  _genimage_) or +L+ for the root filesystem or other filesystems
206  (expanded to +0fc63daf-8483-4772-8e79-3d69d8477de4+ by
207  _genimage_). Even though +L+ is the default value of _genimage_, we
208  prefer to have it explicitly specified in our +genimage.cfg+
209  files. Finally, these shortcuts should be used without double
210  quotes, e.g +partition-type-uuid = U+. If an explicit GUID is
211  specified, lower-case letters should be used.
212
213The +genimage.cfg+ files are the input for the genimage tool used in
214Buildroot to generate the final image file(i.e. sdcard.img). For further
215details about the _genimage_ language, refer to
216https://github.com/pengutronix/genimage/blob/master/README.rst[].
217
218
219=== The documentation
220
221The documentation uses the
222https://asciidoc-py.github.io/[asciidoc] format.
223
224For further details about the asciidoc syntax, refer to
225https://asciidoc-py.github.io/userguide.html[].
226
227=== Support scripts
228
229Some scripts in the +support/+ and +utils/+ directories are written in
230Python and should follow the
231https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code].
232