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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
// -*- mode:doc; -*-
Using Buildroot
---------------
Buildroot has a nice configuration tool similar to the one you can
find in the http://www.kernel.org/[Linux kernel] or in
http://www.busybox.net/[Busybox]. Note that you can *and should build
everything as a normal user*. There is no need to be root to configure
and use Buildroot. The first step is to run the configuration
assistant:
--------------------
$ make menuconfig
--------------------
to run the curses-based configurator, or
--------------------
$ make xconfig
--------------------
or
--------------------
$ make gconfig
--------------------
to run the Qt or GTK-based configurators.
All of these "make" commands will need to build a configuration
utility (including the interface), so you may need to install
"development" packages for relevant libraries used by the
configuration utilities. Check the xref:requirement[] to know what
Buildroot needs, and specifically the xref:requirement-optional[system requirements]
to get the dependencies of favorite interface.
For each menu entry in the configuration tool, you can find associated
help that describes the purpose of the entry.
Once everything is configured, the configuration tool generates a
+.config+ file that contains the description of your
configuration. It will be used by the Makefiles to do what's needed.
Let's go:
--------------------
$ make
--------------------
You *should never* use +make -jN+ with Buildroot: it does not support
'top-level parallel make'. Instead, use the +BR2_JLEVEL+ option to
tell Buildroot to run each package compilation with +make -jN+.
This command will generally perform the following steps:
* Download source files (as required)
* Configure, build and install the cross-compiling toolchain using the
appropriate toolchain backend is used, or simply import a toolchain
if an external toolchain
* Build/install selected target packages
* Build a kernel image, if selected
* Build a bootloader image, if selected
* Create a root filesystem in selected formats
Buildroot output is stored in a single directory, +output/+.
This directory contains several subdirectories:
* +images/+ where all the images (kernel image, bootloader and root
filesystem images) are stored.
* +build/+ where all the components except for the cross-compilation
toolchain are built (this includes tools needed to run Buildroot on
the host and packages compiled for the target). The +build/+
directory contains one subdirectory for each of these components.
* +staging/+ which contains a hierarchy similar to a root filesystem
hierarchy. This directory contains the installation of the
cross-compilation toolchain and all the userspace packages selected
for the target. However, this directory is 'not' intended to be
the root filesystem for the target: it contains a lot of development
files, unstripped binaries and libraries that make it far too big
for an embedded system. These development files are used to compile
libraries and applications for the target that depend on other
libraries.
* +target/+ which contains 'almost' the complete root filesystem for
the target: everything needed is present except the device files in
+/dev/+ (Buildroot can't create them because Buildroot doesn't run
as root and doesn't want to run as root). Therefore, this directory
*should not be used on your target*. Instead, you should use one of
the images built in the +images/+ directory. If you need an
extracted image of the root filesystem for booting over NFS, then
use the tarball image generated in +images/+ and extract it as
root. Compared to +staging/+, +target/+ contains only the files and
libraries needed to run the selected target applications: the
development files (headers, etc.) are not present, unless the
+development files in target filesystem+ option is selected.
* +host/+ contains the installation of tools compiled for the host
that are needed for the proper execution of Buildroot, including the
cross-compilation toolchain.
* +toolchain/+ contains the build directories for the various
components of the cross-compilation toolchain.
These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the
basic ones that allow to easily and quickly generate images fitting
your needs, with all the supports and applications you enabled.
More details about the "make" command usage are given in
xref:make-tips[].
Complying with opensource licenses
----------------------------------
[[legal-info]]
All of the end products of Buildroot (toolchain, root filesystem, kernel,
bootloaders) contain opensource software, released under various licenses.
Using opensource software gives you the freedom to build rich embedded
systems choosing from a wide range of packages, but also gives some
obligations that you must know and honour.
Some licenses require you to publish the license text in the documentation of
your product. Other require you to redistribute the source code of the
software to those that receive your product.
The exact requirements of each license is documented in each package, and it is
your (or your legal office's) responsibility to comply with these requirements.
To make this easier for you, Buildroot can collect for you some material you
will probably need. To produce this material, after you configured Buildroot
with +make menuconfig+, +make xconfig+ or +make gconfig+, run:
--------------------
make legal-info
--------------------
Buildroot will collect legally-relevant material in your output directory,
under the +legal-info/+ subdirectory.
There you will find:
* A +README+ file, that summarizes the produced material and contains warnings
about material that Buildroot could not produce.
* +buildroot.config+: this is the Buildroot configuration file that is usually
produced with +make menuconfig+, and which is necessary to reproduce the
build.
* The source code for all packages; this is saved in the +sources/+
subdirectory (except for proprietary packages, whose source code is not
saved);
patches applied to some packages by Buildroot are distributed with the
Buildroot sources and are not duplicated in the +sources/+ subdirectory.
* A manifest file listing the configured packages, their version, license and
related information.
Some of these information might be not defined in Buildroot; in this case
they are clearly marked as "unknown" or similar.
* A +licenses/+ subdirectory, which contains the license text of packages.
If the license file(s) are not defined in Buildroot, the file is not produced
and a warning in the +README+ indicates this.
Please note that the aim of the +legal-info+ feature of Buildroot is to
produce all the material that is somehow relevant for legal compliance with the
package licenses. Buildroot does not try to produce the exact material that
you must somehow make public. It does surely produce some more material than is
needed for a strict legal compliance. For example, it produces the source code
for packages released under BSD-like licenses, that you might not want to
redistribute in source form.
Moreover, due to technical limitations, Buildroot does not produce some
material that you will or may need, such as the toolchain source code and the
Buildroot source code itself.
When you run +make legal-info+, Buildroot produces warnings in the +README+
file to inform you of relevant material that could not be saved.
Here is a list of the licenses that are most widely used by packages in
Buildroot, with the name used in the manifest file:
* +GPLv2+:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
GNU General Public License, version 2];
* +GPLv2++:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
GNU General Public License, version 2]
or (at your option) any later version;
* +GPLv3+:
http://www.gnu.org/licenses/gpl.html[
GNU General Public License, version 3];
* +GPLv3++:
http://www.gnu.org/licenses/gpl.html[
GNU General Public License, version 3]
or (at your option) any later version;
* +GPL+:
http://www.gnu.org/licenses/gpl.html[
GNU General Public License] (any version);
* +LGPLv2.1+:
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
GNU Lesser General Public License, version 2.1];
* +LGPLv2.1++:
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
GNU Lesser General Public License, version 2.1]
or (at your option) any later version;
* +LGPLv3+:
http://www.gnu.org/licenses/lgpl.html[
GNU Lesser General Public License, version 3];
* +LGPLv3++:
http://www.gnu.org/licenses/lgpl.html[
GNU Lesser General Public License, version 3]
or (at your option) any later version;
* +LGPL+:
http://www.gnu.org/licenses/lgpl.html[
GNU Lesser General Public License] (any version);
* +BSD-4c+: Original BSD 4-clause license;
* +BSD-3c+: BSD 3-clause license;
* +BSD-2c+: BSD 2-clause license;
* +PROPRIETARY+: marks a non-opensource package;
Buildroot does not save any licensing info or source code for these packages.
Complying with the Buildroot license
------------------------------------
Buildroot itself is an opensource software, released under the
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
License, version 2] or (at your option) any later version.
However, being a build system, it is not normally part of the end product:
if you develop the root filesystem, kernel, bootloader or toolchain for a
device, the code of Buildroot is only present on the development machine, not
in the device storage.
Nevertheless, the general view of the Buildroot developers is that you should
release the Buildroot source code along with the source code of other packages
when releasing a product that contains GPL-licensed software.
This is because the
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU GPL]
defines the "'complete source code'" for an executable work as "'all the
source code for all modules it contains, plus any associated interface
definition files, plus the scripts used to control compilation and installation
of the executable'".
Buildroot is part of the 'scripts used to control compilation and
installation of the executable', and as such it is considered part of the
material that must be redistributed.
Keep in mind this is only the Buildroot developers' opinion, and you should
consult your legal department or lawyer in case of any doubt.
|
