2012-11-11 04:14:57 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:57 +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
|
|
|
=== Tips and tricks
|
2012-11-11 04:14:57 +01:00
|
|
|
|
|
|
|
|
[[package-name-variable-relation]]
|
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
|
|
|
==== Package name, config entry name and makefile variable relationship
|
2012-11-11 04:14:57 +01:00
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
In Buildroot, there is some relationship between:
|
2012-11-11 04:14:57 +01:00
|
|
|
|
|
|
|
|
* the _package name_, which is the package directory name (and the
|
|
|
|
|
name of the +*.mk+ file);
|
|
|
|
|
|
|
|
|
|
* the config entry name that is declared in the +Config.in+ file;
|
|
|
|
|
|
|
|
|
|
* the makefile variable prefix.
|
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
It is mandatory to maintain consistency between these elements,
|
|
|
|
|
using the following rules:
|
2012-11-11 04:14:57 +01:00
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
* the package directory and the +*.mk+ name are the _package name_
|
|
|
|
|
itself (e.g.: +package/foo-bar_boo/foo-bar_boo.mk+);
|
|
|
|
|
|
|
|
|
|
* the _make_ target name is the _package name_ itself (e.g.:
|
2012-11-11 04:14:57 +01:00
|
|
|
+foo-bar_boo+);
|
|
|
|
|
|
|
|
|
|
* the config entry is the upper case _package name_ with `.` and `-`
|
|
|
|
|
characters substituted with `_`, prefixed with +BR2_PACKAGE_+ (e.g.:
|
|
|
|
|
+BR2_PACKAGE_FOO_BAR_BOO+);
|
|
|
|
|
|
|
|
|
|
* the +*.mk+ file variable prefix is the upper case _package name_
|
2014-03-20 23:07:30 +01:00
|
|
|
with `.` and `-` characters substituted with `_` (e.g.:
|
2012-11-11 04:14:57 +01:00
|
|
|
+FOO_BAR_BOO_VERSION+).
|
|
|
|
|
|
2018-04-02 00:31:56 +02:00
|
|
|
[[check-package]]
|
|
|
|
|
==== How to check the coding style
|
|
|
|
|
|
|
|
|
|
Buildroot provides a script in +utils/check-package+ that checks new or
|
|
|
|
|
changed files for coding style. It is not a complete language validator,
|
|
|
|
|
but it catches many common mistakes. It is meant to run in the actual
|
|
|
|
|
files you created or modified, before creating the patch for submission.
|
|
|
|
|
|
|
|
|
|
This script can be used for packages, filesystem makefiles, Config.in
|
|
|
|
|
files, etc. It does not check the files defining the package
|
|
|
|
|
infrastructures and some other files containing similar common code.
|
|
|
|
|
|
|
|
|
|
To use it, run the +check-package+ script, by telling which files you
|
|
|
|
|
created or changed:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
$ ./utils/check-package package/new-package/*
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
If you have the +utils+ directory in your path you can also run:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
$ cd package/new-package/
|
|
|
|
|
$ check-package *
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The tool can also be used for packages in a br2-external:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
$ check-package -b /path/to/br2-ext-tree/package/my-package/*
|
|
|
|
|
----
|
|
|
|
|
|
2017-04-06 20:18:41 +02:00
|
|
|
[[testing-package]]
|
|
|
|
|
==== How to test your package
|
|
|
|
|
|
|
|
|
|
Once you have added your new package, it is important that you test it
|
|
|
|
|
under various conditions: does it build for all architectures? Does it
|
|
|
|
|
build with the different C libraries? Does it need threads, NPTL? And
|
|
|
|
|
so on...
|
|
|
|
|
|
|
|
|
|
Buildroot runs http://autobuild.buildroot.org/[autobuilders] which
|
|
|
|
|
continuously test random configurations. However, these only build the
|
|
|
|
|
`master` branch of the git tree, and your new fancy package is not yet
|
|
|
|
|
there.
|
|
|
|
|
|
2017-07-01 18:07:00 +02:00
|
|
|
Buildroot provides a script in +utils/test-pkg+ that uses the same base
|
2017-07-01 16:31:01 +02:00
|
|
|
configurations as used by the autobuilders so you can test your package
|
|
|
|
|
in the same conditions.
|
2017-04-06 20:18:41 +02:00
|
|
|
|
|
|
|
|
First, create a config snippet that contains all the necessary options
|
|
|
|
|
needed to enable your package, but without any architecture or toolchain
|
|
|
|
|
option. For example, let's create a config snippet that just enables
|
|
|
|
|
+libcurl+, without any TLS backend:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
$ cat libcurl.config
|
|
|
|
|
BR2_PACKAGE_LIBCURL=y
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
If your package needs more configuration options, you can add them to the
|
|
|
|
|
config snippet. For example, here's how you would test +libcurl+ with
|
|
|
|
|
+openssl+ as a TLS backend and the +curl+ program:
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
$ cat libcurl.config
|
|
|
|
|
BR2_PACKAGE_LIBCURL=y
|
2020-02-10 13:06:59 +01:00
|
|
|
BR2_PACKAGE_LIBCURL_CURL=y
|
2017-04-06 20:18:41 +02:00
|
|
|
BR2_PACKAGE_OPENSSL=y
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Then run the +test-pkg+ script, by telling it what config snippet to use
|
|
|
|
|
and what package to test:
|
|
|
|
|
|
|
|
|
|
----
|
2017-07-01 18:07:00 +02:00
|
|
|
$ ./utils/test-pkg -c libcurl.config -p libcurl
|
2017-04-06 20:18:41 +02:00
|
|
|
----
|
|
|
|
|
|
2018-03-23 22:48:15 +01:00
|
|
|
By default, +test-pkg+ will build your package against a subset of the
|
|
|
|
|
toolchains used by the autobuilders, which has been selected by the
|
|
|
|
|
Buildroot developers as being the most useful and representative
|
|
|
|
|
subset. If you want to test all toolchains, pass the +-a+ option. Note
|
|
|
|
|
that in any case, internal toolchains are excluded as they take too
|
|
|
|
|
long to build.
|
|
|
|
|
|
|
|
|
|
The output lists all toolchains that are tested and the corresponding
|
2017-04-06 20:18:41 +02:00
|
|
|
result (excerpt, results are fake):
|
|
|
|
|
|
|
|
|
|
----
|
2017-07-01 18:07:00 +02:00
|
|
|
$ ./utils/test-pkg -c libcurl.config -p libcurl
|
2017-04-06 20:18:42 +02:00
|
|
|
armv5-ctng-linux-gnueabi [ 1/11]: OK
|
|
|
|
|
armv7-ctng-linux-gnueabihf [ 2/11]: OK
|
|
|
|
|
br-aarch64-glibc [ 3/11]: SKIPPED
|
|
|
|
|
br-arcle-hs38 [ 4/11]: SKIPPED
|
|
|
|
|
br-arm-basic [ 5/11]: FAILED
|
|
|
|
|
br-arm-cortex-a9-glibc [ 6/11]: OK
|
|
|
|
|
br-arm-cortex-a9-musl [ 7/11]: FAILED
|
|
|
|
|
br-arm-cortex-m4-full [ 8/11]: OK
|
|
|
|
|
br-arm-full [ 9/11]: OK
|
2017-04-07 13:16:17 +02:00
|
|
|
br-arm-full-nothread [10/11]: FAILED
|
2017-04-06 20:18:42 +02:00
|
|
|
br-arm-full-static [11/11]: OK
|
2017-04-07 13:16:17 +02:00
|
|
|
11 builds, 2 skipped, 2 build failed, 1 legal-info failed
|
2017-04-06 20:18:41 +02:00
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The results mean:
|
|
|
|
|
|
|
|
|
|
* `OK`: the build was successful.
|
|
|
|
|
* `SKIPPED`: one or more configuration options listed in the config
|
|
|
|
|
snippet were not present in the final configuration. This is due to
|
|
|
|
|
options having dependencies not satisfied by the toolchain, such as
|
|
|
|
|
for example a package that +depends on BR2_USE_MMU+ with a noMMU
|
2017-07-01 23:36:35 +02:00
|
|
|
toolchain. The missing options are reported in +missing.config+ in
|
2017-04-06 20:18:41 +02:00
|
|
|
the output build directory (+~/br-test-pkg/TOOLCHAIN_NAME/+ by
|
|
|
|
|
default).
|
|
|
|
|
* `FAILED`: the build failed. Inspect the +logfile+ file in the output
|
|
|
|
|
build directory to see what went wrong:
|
|
|
|
|
** the actual build failed,
|
2017-04-07 13:16:17 +02:00
|
|
|
** the legal-info failed,
|
2017-04-06 20:18:41 +02:00
|
|
|
** one of the preliminary steps (downloading the config file, applying
|
|
|
|
|
the configuration, running `dirclean` for the package) failed.
|
|
|
|
|
|
|
|
|
|
When there are failures, you can just re-run the script with the same
|
|
|
|
|
options (after you fixed your package); the script will attempt to
|
|
|
|
|
re-build the package specified with +-p+ for all toolchains, without
|
|
|
|
|
the need to re-build all the dependencies of that package.
|
|
|
|
|
|
|
|
|
|
The +test-pkg+ script accepts a few options, for which you can get some
|
|
|
|
|
help by running:
|
|
|
|
|
|
|
|
|
|
----
|
2017-07-01 18:07:00 +02:00
|
|
|
$ ./utils/test-pkg -h
|
2017-04-06 20:18:41 +02:00
|
|
|
----
|
2012-11-11 04:14:57 +01:00
|
|
|
|
|
|
|
|
[[github-download-url]]
|
2014-06-02 17:55:59 +02:00
|
|
|
==== How to add a package from GitHub
|
2012-11-11 04:14:57 +01:00
|
|
|
|
2014-06-02 17:55:59 +02:00
|
|
|
Packages on GitHub often don't have a download area with release tarballs.
|
2012-11-27 12:59:17 +01:00
|
|
|
However, it is possible to download tarballs directly from the repository
|
2014-06-02 17:55:59 +02:00
|
|
|
on GitHub. As GitHub is known to have changed download mechanisms in the
|
2013-12-05 18:20:45 +01:00
|
|
|
past, the 'github' helper function should be used as shown below.
|
2012-11-11 04:14:57 +01:00
|
|
|
|
2012-11-27 12:59:17 +01:00
|
|
|
------------------------
|
2015-04-27 01:40:21 +02:00
|
|
|
# Use a tag or a full commit ID
|
2021-03-28 21:13:48 +02:00
|
|
|
FOO_VERSION = 1.0
|
|
|
|
|
FOO_SITE = $(call github,<user>,<package>,v$(FOO_VERSION))
|
2012-11-27 12:59:17 +01:00
|
|
|
------------------------
|
|
|
|
|
|
2013-06-07 10:48:45 +02:00
|
|
|
.Notes
|
|
|
|
|
- The FOO_VERSION can either be a tag or a commit ID.
|
|
|
|
|
- The tarball name generated by github matches the default one from
|
2013-11-02 15:57:27 +01:00
|
|
|
Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
|
2013-06-07 10:48:45 +02:00
|
|
|
so it is not necessary to specify it in the +.mk+ file.
|
2013-11-02 15:57:27 +01:00
|
|
|
- When using a commit ID as version, you should use the full 40 hex characters.
|
2021-03-28 21:13:48 +02:00
|
|
|
- When the tag contains a prefix such as +v+ in +v1.0+, then the
|
|
|
|
|
+VERSION+ variable should contain just +1.0+, and the +v+ should be
|
|
|
|
|
added directly in the +SITE+ variable, as illustrated above. This
|
|
|
|
|
ensures that the +VERSION+ variable value can be used to match
|
|
|
|
|
against http://www.release-monitoring.org/[release-monitoring.org]
|
|
|
|
|
results.
|
2014-10-15 14:24:20 +02:00
|
|
|
|
|
|
|
|
If the package you wish to add does have a release section on GitHub, the
|
|
|
|
|
maintainer may have uploaded a release tarball, or the release may just point
|
|
|
|
|
to the automatically generated tarball from the git tag. If there is a
|
|
|
|
|
release tarball uploaded by the maintainer, we prefer to use that since it
|
|
|
|
|
may be slightly different (e.g. it contains a configure script so we don't
|
|
|
|
|
need to do AUTORECONF).
|
|
|
|
|
|
|
|
|
|
You can see on the release page if it's an uploaded tarball or a git tag:
|
2014-11-11 19:33:56 +01:00
|
|
|
|
2015-07-28 00:40:04 +02:00
|
|
|
image::github_hash_mongrel2.png[]
|
|
|
|
|
|
|
|
|
|
- If it looks like the image above then it was uploaded by the
|
|
|
|
|
maintainer and you should use that link (in that example:
|
|
|
|
|
'mongrel2-v1.9.2.tar.bz2') to specify +FOO_SITE+, and not use the
|
|
|
|
|
'github' helper.
|
|
|
|
|
|
|
|
|
|
- On the other hand, if there's is *only* the "Source code" link, then
|
|
|
|
|
it's an automatically generated tarball and you should use the
|
|
|
|
|
'github' helper function.
|
2021-03-28 21:13:50 +02:00
|
|
|
|
|
|
|
|
[[gitlab-download-url]]
|
|
|
|
|
==== How to add a package from Gitlab
|
|
|
|
|
|
|
|
|
|
In a similar way to the +github+ macro described in
|
|
|
|
|
xref:github-download-url[], Buildroot also provides the +gitlab+ macro
|
|
|
|
|
to download from Gitlab repositories. It can be used to download
|
|
|
|
|
auto-generated tarballs produced by Gitlab, either for specific tags
|
|
|
|
|
or commits:
|
|
|
|
|
|
|
|
|
|
------------------------
|
|
|
|
|
# Use a tag or a full commit ID
|
|
|
|
|
FOO_VERSION = 1.0
|
|
|
|
|
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
By default, it will use a +.tar.gz+ tarball, but Gitlab also provides
|
|
|
|
|
+.tar.bz2+ tarballs, so by adding a +<pkg>_SOURCE+ variable, this
|
|
|
|
|
+.tar.bz2+ tarball can be used:
|
|
|
|
|
|
|
|
|
|
------------------------
|
|
|
|
|
# Use a tag or a full commit ID
|
|
|
|
|
FOO_VERSION = 1.0
|
|
|
|
|
FOO_SITE = $(call gitlab,<user>,<package>,v$(FOO_VERSION))
|
|
|
|
|
FOO_SOURCE = foo-$(FOO_VERSION).tar.bz2
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
If there is a specific tarball uploaded by the upstream developers in
|
|
|
|
|
+https://gitlab.com/<project>/releases/+, do not use this macro, but
|
|
|
|
|
rather use directly the link to the tarball.
|
