2012-11-11 04:14:51 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:51 +01:00
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Coding style
|
2012-11-11 04:14:51 +01:00
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
Overall, these coding style rules are here to help you to add new files in
|
2012-11-11 04:14:51 +01:00
|
|
|
Buildroot or refactor existing ones.
|
|
|
|
|
|
|
|
|
|
If you slightly modify some existing file, the important thing is
|
2012-11-27 12:59:17 +01:00
|
|
|
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.
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
[[writing-rules-config-in]]
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== +Config.in+ file
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
+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
|
2017-02-19 23:17:22 +01:00
|
|
|
This is a comment that explains what libfoo is. The help text
|
|
|
|
|
should be wrapped.
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2017-02-19 23:17:22 +01:00
|
|
|
* The help text should be wrapped to fit 72 columns, where tab counts
|
|
|
|
|
for 8, so 62 characters in the text itself.
|
2015-05-17 13:38:31 +02:00
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
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
|
2012-11-11 04:14:51 +01:00
|
|
|
http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
|
|
|
|
|
|
|
|
|
|
[[writing-rules-mk]]
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== The +.mk+ file
|
2012-11-11 04:14:51 +01:00
|
|
|
|
2013-06-08 00:34:38 +02:00
|
|
|
* 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
|
|
|
|
|
#
|
|
|
|
|
################################################################################
|
|
|
|
|
---------------------
|
|
|
|
|
+
|
2012-11-11 04:14:51 +01:00
|
|
|
* Assignment: use +=+ preceded and followed by one space:
|
|
|
|
|
+
|
|
|
|
|
---------------------
|
|
|
|
|
LIBFOO_VERSION = 1.0
|
2014-09-27 21:32:44 +02:00
|
|
|
LIBFOO_CONF_OPTS += --without-python-support
|
2012-11-11 04:14:51 +01:00
|
|
|
---------------------
|
2012-11-27 12:59:17 +01:00
|
|
|
+
|
2014-01-22 17:12:43 +01:00
|
|
|
Do not align the +=+ signs.
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
* Indentation: use tab only:
|
|
|
|
|
+
|
|
|
|
|
---------------------
|
|
|
|
|
define LIBFOO_REMOVE_DOC
|
2012-11-27 12:59:17 +01:00
|
|
|
$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \
|
|
|
|
|
$(TARGET_DIR)/usr/share/man/man3/libfoo*
|
2012-11-11 04:14:51 +01:00
|
|
|
endef
|
|
|
|
|
---------------------
|
2012-11-27 12:59:17 +01:00
|
|
|
+
|
|
|
|
|
Note that commands inside a +define+ block should always start with a tab,
|
|
|
|
|
so _make_ recognizes them as commands.
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
* Optional dependency:
|
|
|
|
|
|
|
|
|
|
** Prefer multi-line syntax.
|
|
|
|
|
+
|
|
|
|
|
YES:
|
|
|
|
|
+
|
|
|
|
|
---------------------
|
2022-02-09 17:52:13 +01:00
|
|
|
ifeq ($(BR2_PACKAGE_PYTHON3),y)
|
2014-09-27 21:32:44 +02:00
|
|
|
LIBFOO_CONF_OPTS += --with-python-support
|
2022-02-09 17:52:13 +01:00
|
|
|
LIBFOO_DEPENDENCIES += python3
|
2012-11-11 04:14:51 +01:00
|
|
|
else
|
2014-09-27 21:32:44 +02:00
|
|
|
LIBFOO_CONF_OPTS += --without-python-support
|
2012-11-11 04:14:51 +01:00
|
|
|
endif
|
|
|
|
|
---------------------
|
|
|
|
|
+
|
|
|
|
|
NO:
|
|
|
|
|
+
|
|
|
|
|
---------------------
|
2022-02-09 17:52:13 +01:00
|
|
|
LIBFOO_CONF_OPTS += --with$(if $(BR2_PACKAGE_PYTHON3),,out)-python-support
|
|
|
|
|
LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON3),python3,)
|
2012-11-11 04:14:51 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
** 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
|
|
|
|
|
---------------------
|
|
|
|
|
|
2021-11-08 20:51:30 +01:00
|
|
|
[[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
|
2022-02-06 10:54:03 +01:00
|
|
|
last one node. Same goes for its option, for example option +size+ +=+.
|
2021-11-08 20:51:30 +01:00
|
|
|
|
|
|
|
|
* 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.
|
|
|
|
|
|
2021-11-09 11:18:43 +01:00
|
|
|
* 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+.
|
|
|
|
|
|
2022-07-22 22:21:45 +02:00
|
|
|
* 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.
|
|
|
|
|
|
2021-11-08 20:51:30 +01:00
|
|
|
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[].
|
|
|
|
|
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== The documentation
|
2012-11-11 04:14:51 +01:00
|
|
|
|
|
|
|
|
The documentation uses the
|
2022-02-28 17:32:38 +01:00
|
|
|
https://asciidoc-py.github.io/[asciidoc] format.
|
2012-11-11 04:14:51 +01:00
|
|
|
|
2020-03-28 15:41:38 +01:00
|
|
|
For further details about the asciidoc syntax, refer to
|
2022-02-28 17:32:38 +01:00
|
|
|
https://asciidoc-py.github.io/userguide.html[].
|
2017-04-24 03:33:56 +02:00
|
|
|
|
|
|
|
|
=== Support scripts
|
|
|
|
|
|
2017-07-01 18:07:00 +02:00
|
|
|
Some scripts in the +support/+ and +utils/+ directories are written in
|
2017-07-01 16:31:07 +02:00
|
|
|
Python and should follow the
|
|
|
|
|
https://www.python.org/dev/peps/pep-0008/[PEP8 Style Guide for Python Code].
|
