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) -fr $(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_PYTHON),y) 97LIBFOO_CONF_OPTS += --with-python-support 98LIBFOO_DEPENDENCIES += python 99else 100LIBFOO_CONF_OPTS += --without-python-support 101endif 102--------------------- 103+ 104NO: 105+ 106--------------------- 107LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support 108LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,) 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) -fr $(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) -fr $(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 195The +genimage.cfg+ files are the input for the genimage tool used in 196Buildroot to generate the final image file(i.e. sdcard.img). For further 197details about the _genimage_ language, refer to 198https://github.com/pengutronix/genimage/blob/master/README.rst[]. 199 200 201=== The documentation 202 203The documentation uses the 204http://www.methods.co.nz/asciidoc/[asciidoc] format. 205 206For further details about the asciidoc syntax, refer to 207http://www.methods.co.nz/asciidoc/userguide.html[]. 208 209=== Support scripts 210 211Some scripts in the +support/+ and +utils/+ directories are written in 212Python and should follow the 213https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code]. 214