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
|
|
|
|
|
FOO_VERSION = v1.0
|
Revert "pkg-download: remove explicit PKG_VERSION from github helper"
This reverts commit 1e5a8916b2ab4c9c99548fa6fbd4855eee323881.
The idea was that the version string can be derived because we know the
package name.
However, this patch does not account for the fact that $(pkgname) always
points to the latest pacakge scanned, which in all other situation we're
using it, is the current package, because it is used inside one ot he
xxx-inner macros that are $(eval)ualed. So $(pkgname) is evaluated
"early" and gets the expected value.
However, the github value is not in one of those macros, so it gets
evaluated "late", when doing the actual download. So, by that time,
$(pkgname) will expand to the last package scanned, which is actuall the
manual (without a br2-external tree).
That would require that the _SITE variable be assigned with the :=
assignment operator. This is weird, because that would make it the only
variable to require that, but only when using the github helper, which
is even less obvious and would cause a lot of trouble...
The obvious fixup would seem to be to use $(PKG) instead, because that
already contains the upper-case package name that vcan be used as a
prefix to variables.
However, that does not work either, because we have a check that forbids
a trsailing slash in _SITE, check that is done in pacakge/pkg-generic,
inside the xxx-inner macro, during the $(eval) call.
And at that time, PKG is not yet defined, because it is only defined for
an actual recipe.
So we can't seem to have a workable solution. So, just revert the patch.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Marcin Nowakowski <marcin.nowakowski@imgtec.com>
Cc: Peter Korsgaard <peter@korsgaard.com>
Cc: Arnout Vandecappelle <arnout@mind.be>
Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2017-11-13 23:00:09 +01:00
|
|
|
FOO_SITE = $(call github,<user>,<package>,$(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.
|
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.
|
