37308b979a
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
170 lines
6.2 KiB
Plaintext
170 lines
6.2 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc:
|
|
|
|
=== Tips and tricks
|
|
|
|
[[package-name-variable-relation]]
|
|
==== Package name, config entry name and makefile variable relationship
|
|
|
|
In Buildroot, there is some relationship between:
|
|
|
|
* 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.
|
|
|
|
It is mandatory to maintain consistency between these elements,
|
|
using the following rules:
|
|
|
|
* 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.:
|
|
+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_
|
|
with `.` and `-` characters substituted with `_` (e.g.:
|
|
+FOO_BAR_BOO_VERSION+).
|
|
|
|
[[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.
|
|
|
|
Buildroot provides a script in +support/scripts/test-pkg+ that uses the
|
|
same base configurations as used by the autobuilders so you can test
|
|
your package in the same conditions.
|
|
|
|
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
|
|
BR2_PACKAGE_CURL=y
|
|
BR2_PACKAGE_OPENSSL=y
|
|
----
|
|
|
|
Then run the +test-pkg+ script, by telling it what config snippet to use
|
|
and what package to test:
|
|
|
|
----
|
|
$ ./support/scripts/test-pkg -c libcurl.config -p libcurl
|
|
----
|
|
|
|
This will try to build your package against all the toolchains used
|
|
by the autobuilders (except for the internal toolchains, because it takes
|
|
too long to do so). The output lists all toolchains and the corresponding
|
|
result (excerpt, results are fake):
|
|
|
|
----
|
|
$ ./support/scripts/test-pkg -c libcurl.config -p libcurl
|
|
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
|
|
br-arm-full-nothread [10/11]: FAILED
|
|
br-arm-full-static [11/11]: OK
|
|
11 builds, 2 skipped, 2 build failed, 1 legal-info failed
|
|
----
|
|
|
|
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
|
|
toolchain. The missing options are reported in +config.missing+ in
|
|
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,
|
|
** the legal-info failed,
|
|
** 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:
|
|
|
|
----
|
|
$ ./support/scripts/test-pkg -h
|
|
----
|
|
|
|
[[github-download-url]]
|
|
==== How to add a package from GitHub
|
|
|
|
Packages on GitHub often don't have a download area with release tarballs.
|
|
However, it is possible to download tarballs directly from the repository
|
|
on GitHub. As GitHub is known to have changed download mechanisms in the
|
|
past, the 'github' helper function should be used as shown below.
|
|
|
|
------------------------
|
|
# Use a tag or a full commit ID
|
|
FOO_VERSION = v1.0
|
|
FOO_SITE = $(call github,<user>,<package>,$(FOO_VERSION))
|
|
------------------------
|
|
|
|
.Notes
|
|
- The FOO_VERSION can either be a tag or a commit ID.
|
|
- The tarball name generated by github matches the default one from
|
|
Buildroot (e.g.: +foo-f6fb6654af62045239caed5950bc6c7971965e60.tar.gz+),
|
|
so it is not necessary to specify it in the +.mk+ file.
|
|
- When using a commit ID as version, you should use the full 40 hex characters.
|
|
|
|
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:
|
|
|
|
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.
|