1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
// -*- 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 +tools/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:
----
$ ./tools/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):
----
$ ./tools/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:
----
$ ./tools/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.
|
