Bump buildroot to 2019.02
This commit is contained in:
@@ -46,9 +46,11 @@ is as follows:
|
||||
|
||||
1. The type of option: +bool+, +string+... with the prompt
|
||||
2. If needed, the +default+ value(s)
|
||||
3. Any dependency of the +depends on+ form
|
||||
4. Any dependency of the +select+ form
|
||||
5. The help keyword and help text.
|
||||
3. Any dependencies on the target in +depends on+ form
|
||||
4. Any dependencies on the toolchain in +depends on+ form
|
||||
5. Any dependencies on other packages in +depends on+ form
|
||||
6. Any dependency of the +select+ form
|
||||
7. The help keyword and help text.
|
||||
|
||||
You can add other sub-options into a +if BR2_PACKAGE_LIBFOO...endif+
|
||||
statement to configure particular things in your software. You can look at
|
||||
@@ -292,13 +294,13 @@ use in the comment.
|
||||
|
||||
* Kernel headers
|
||||
** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
|
||||
+X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
|
||||
+X_Y+ with the proper version, see +toolchain/Config.in+)
|
||||
** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
|
||||
+X.Y+ with the proper version)
|
||||
|
||||
* GCC version
|
||||
** Dependency symbol: +BR2_TOOLCHAIN_GCC_AT_LEAST_X_Y+, (replace
|
||||
+X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
|
||||
+X_Y+ with the proper version, see +toolchain/Config.in+)
|
||||
** Comment string: +gcc >= X.Y+ and/or `gcc <= X.Y` (replace
|
||||
+X.Y+ with the proper version)
|
||||
|
||||
@@ -444,6 +446,13 @@ contains the hashes of the downloaded files for the +libfoo+
|
||||
package. The only reason for not adding a +.hash+ file is when hash
|
||||
checking is not possible due to how the package is downloaded.
|
||||
|
||||
When a package has a version selection choice, then the hash file may be
|
||||
stored in a subdirectory named after the version, e.g.
|
||||
+package/libfoo/1.2.3/libfoo.hash+. This is especially important if the
|
||||
different versions have different licensing terms, but they are stored
|
||||
in the same file. Otherwise, the hash file should stay in the package's
|
||||
directory.
|
||||
|
||||
The hashes stored in that file are used to validate the integrity of the
|
||||
downloaded files and of the license files.
|
||||
|
||||
|
||||
@@ -179,8 +179,10 @@ some tools to be installed on the host. If the package name is
|
||||
variables of other packages, if they depend on +libfoo+ or
|
||||
+host-libfoo+.
|
||||
|
||||
The call to the +generic-package+ and/or +host-generic-package+ macro *must* be
|
||||
at the end of the +.mk+ file, after all variable definitions.
|
||||
The call to the +generic-package+ and/or +host-generic-package+ macro
|
||||
*must* be at the end of the +.mk+ file, after all variable definitions.
|
||||
The call to +host-generic-package+ *must* be after the call to
|
||||
+generic-package+, if any.
|
||||
|
||||
For the target package, the +generic-package+ uses the variables defined by
|
||||
the .mk file and prefixed by the uppercased package name:
|
||||
@@ -276,7 +278,7 @@ not and can not work as people would expect it should:
|
||||
the file using this URL. Otherwise, Buildroot will assume the file
|
||||
to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do
|
||||
anything with those additional files, except download them: it will
|
||||
be up to the package recipe to use them from +$(DL_DIR)+.
|
||||
be up to the package recipe to use them from +$(LIBFOO_DL_DIR)+.
|
||||
|
||||
* +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
|
||||
package source code. In many cases, Buildroot guesses the method
|
||||
@@ -360,6 +362,13 @@ not and can not work as people would expect it should:
|
||||
a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
|
||||
the current host package.
|
||||
|
||||
* +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of
|
||||
package name) that are required for the current target package to be
|
||||
extracted. These dependencies are guaranteed to be compiled and
|
||||
installed before the extract step of the current package
|
||||
starts. This is only used internally by the package infrastructure,
|
||||
and should typically not be used directly by packages.
|
||||
|
||||
* +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of
|
||||
package name) that are required for the current package to be
|
||||
patched. These dependencies are guaranteed to be extracted and
|
||||
@@ -560,8 +569,8 @@ In the action definitions, you can use the following variables:
|
||||
* +$(@D)+, which contains the directory in which the package source
|
||||
code has been uncompressed.
|
||||
|
||||
* +$(DL_DIR)+ contains the path to the directory where all the downloads made
|
||||
by Buildroot are stored.
|
||||
* +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads
|
||||
made by Buildroot for +libfoo+ are stored in.
|
||||
|
||||
* +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
|
||||
cross-compilation utilities
|
||||
|
||||
119
bsp/buildroot/docs/manual/adding-packages-golang.txt
Normal file
119
bsp/buildroot/docs/manual/adding-packages-golang.txt
Normal file
@@ -0,0 +1,119 @@
|
||||
// -*- mode:doc; -*-
|
||||
// vim: set syntax=asciidoc:
|
||||
|
||||
=== Infrastructure for Go packages
|
||||
|
||||
This infrastructure applies to Go packages that use the standard
|
||||
build system and use bundled dependencies.
|
||||
|
||||
[[golang-package-tutorial]]
|
||||
|
||||
==== +golang-package+ tutorial
|
||||
|
||||
First, let's see how to write a +.mk+ file for a go package,
|
||||
with an example :
|
||||
|
||||
------------------------
|
||||
01: ################################################################################
|
||||
02: #
|
||||
03: # foo
|
||||
04: #
|
||||
05: ################################################################################
|
||||
06:
|
||||
07: FOO_VERSION = 1.0
|
||||
08: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))
|
||||
09: FOO_LICENSE = BSD-3-Clause
|
||||
10: FOO_LICENSE_FILES = LICENSE
|
||||
11:
|
||||
12: $(eval $(golang-package))
|
||||
------------------------
|
||||
|
||||
On line 7, we declare the version of the package.
|
||||
|
||||
On line 8, we declare the upstream location of the package, here
|
||||
fetched from Github, since a large number of Go packages are hosted on
|
||||
Github.
|
||||
|
||||
On line 9 and 10, we give licensing details about the package.
|
||||
|
||||
Finally, on line 12, we invoke the +golang-package+ macro that
|
||||
generates all the Makefile rules that actually allow the package to be
|
||||
built.
|
||||
|
||||
[[golang-package-reference]]
|
||||
|
||||
==== +golang-package+ reference
|
||||
|
||||
In their +Config.in+ file, packages using the +golang-package+
|
||||
infrastructure should depend on +BR2_PACKAGE_HOST_GO_ARCH_SUPPORTS+
|
||||
and +BR2_PACKAGE_HOST_GO_CGO_LINKING_SUPPORTS+ because Buildroot will
|
||||
automatically add a dependency on +host-go+ to such packages.
|
||||
|
||||
The main macro of the Go package infrastructure is
|
||||
+golang-package+. It is similar to the +generic-package+ macro. Only
|
||||
target packages are supported with +golang-package+.
|
||||
|
||||
Just like the generic infrastructure, the Go infrastructure works
|
||||
by defining a number of variables before calling the +golang-package+.
|
||||
|
||||
All the package metadata information variables that exist in the
|
||||
xref:generic-package-reference[generic package infrastructure] also
|
||||
exist in the Go infrastructure: +FOO_VERSION+, +FOO_SOURCE+,
|
||||
+FOO_PATCH+, +FOO_SITE+, +FOO_SUBDIR+, +FOO_DEPENDENCIES+,
|
||||
+FOO_LICENSE+, +FOO_LICENSE_FILES+, +FOO_INSTALL_STAGING+, etc.
|
||||
|
||||
Note that it is not necessary to add +host-go+ in the
|
||||
+FOO_DEPENDENCIES+ variable of a package, since this basic dependency
|
||||
is automatically added as needed by the Go package infrastructure.
|
||||
|
||||
A few additional variables, specific to the Go infrastructure, can
|
||||
optionally be defined, depending on the package's needs. Many of them
|
||||
are only useful in very specific cases, typical packages will
|
||||
therefore only use a few of them, or none.
|
||||
|
||||
* If your package need a custom +GOPATH+ to be compiled in, you can
|
||||
use the +FOO_WORKSPACE+ variable. The +GOPATH+ being used will be
|
||||
+<package-srcdir>/<FOO_WORKSPACE>+. If +FOO_WORKSPACE+ is not
|
||||
specified, it defaults to +_gopath+.
|
||||
|
||||
* +FOO_SRC_SUBDIR+ is the sub-directory where your source will be
|
||||
compiled relatively to the +GOPATH+. An example value is
|
||||
+github.com/bar/foo+. If +FOO_SRC_SUBDIR+ is not specified, it
|
||||
defaults to a value infered from the +FOO_SITE+ variable.
|
||||
|
||||
* +FOO_LDFLAGS+ and +FOO_TAGS+ can be used to pass respectively the
|
||||
+LDFLAGS+ or the +TAGS+ to the +go+ build command.
|
||||
|
||||
* +FOO_BUILD_TARGETS+ can be used to pass the list of targets that
|
||||
should be built. If +FOO_BUILD_TARGETS+ is not specified, it
|
||||
defaults to +.+. We then have two cases:
|
||||
|
||||
** +FOO_BUILD_TARGETS+ is +.+. In this case, we assume only one binary
|
||||
will be produced, and that by default we name it after the package
|
||||
name. If that is not appropriate, the name of the produced binary
|
||||
can be overridden using +FOO_BIN_NAME+.
|
||||
|
||||
** +FOO_BUILD_TARGETS+ is not +.+. In this case, we iterate over the
|
||||
values to build each target, and for each produced a binary that is
|
||||
the non-directory component of the target. For example if
|
||||
+FOO_BUILD_TARGETS = cmd/docker cmd/dockerd+ the binaries produced
|
||||
are +docker+ and +dockerd+.
|
||||
|
||||
* +FOO_INSTALL_BINS+ can be used to pass the list of binaries that
|
||||
should be installed in +/usr/bin+ on the target. If
|
||||
+FOO_INSTALL_BINS+ is not specified, it defaults to the lower-case
|
||||
name of package.
|
||||
|
||||
With the Go infrastructure, all the steps required to build and
|
||||
install the packages are already defined, and they generally work well
|
||||
for most Go-based packages. However, when required, it is still
|
||||
possible to customize what is done in any particular step:
|
||||
|
||||
* By adding a post-operation hook (after extract, patch, configure,
|
||||
build or install). See xref:hooks[] for details.
|
||||
|
||||
* By overriding one of the steps. For example, even if the Go
|
||||
infrastructure is used, if the package +.mk+ file defines its own
|
||||
+FOO_BUILD_CMDS+ variable, it will be used instead of the default Go
|
||||
one. However, using this method should be restricted to very
|
||||
specific cases. Do not use it in the general case.
|
||||
@@ -81,3 +81,7 @@ be set to suit the needs of the package under consideration:
|
||||
be well suited for all packages that use the standard kconfig
|
||||
infrastructure as inherited from the Linux kernel; some packages use
|
||||
a derivative of kconfig that use a different location.
|
||||
|
||||
* +FOO_KCONFIG_DEPENDENCIES+: the list of packages (most probably, host
|
||||
packages) that need to be built before this package's kconfig is
|
||||
interpreted. Seldom used. By default, empty.
|
||||
|
||||
@@ -50,6 +50,16 @@ Finally, on line 16, we invoke the +luarocks-package+
|
||||
macro that generates all the Makefile rules that actually allows the
|
||||
package to be built.
|
||||
|
||||
Most of these details can be retrieved from the +rock+ and +rockspec+.
|
||||
So, this file and the Config.in file can be generated by running the
|
||||
command +luarocks buildroot foo lua-foo+ in the Buildroot
|
||||
directory. This command runs a specific Buildroot addon of +luarocks+
|
||||
that will automatically generate a Buildroot package. The result must
|
||||
still be manually inspected and possibly modified.
|
||||
|
||||
* The +package/Config.in+ file has to be updated manually to include the
|
||||
generated Config.in files.
|
||||
|
||||
[[luarocks-package-reference]]
|
||||
|
||||
==== +luarocks-package+ reference
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
// -*- mode:doc; -*-
|
||||
// vim: set syntax=asciidoc:
|
||||
|
||||
=== Integration of Meson-based packages
|
||||
=== Infrastructure for Meson-based packages
|
||||
|
||||
[[meson-package-tutorial]]
|
||||
|
||||
==== +meson-package+ tutorial
|
||||
|
||||
http://mesonbuild.com[Meson] is an open source build system meant to be both
|
||||
extremely fast, and, even more importantly, as user friendly as possible.
|
||||
extremely fast, and, even more importantly, as user friendly as possible. It
|
||||
uses https://ninja-build.org[Ninja] as a companion tool to perform the actual
|
||||
build operations.
|
||||
|
||||
Buildroot does not (yet) provide a dedicated package infrastructure for
|
||||
meson-based packages. So, we will explain how to write a +.mk+ file for such a
|
||||
package. Let's start with an example:
|
||||
Let's see how to write a +.mk+ file for a Meson-based package, with an example:
|
||||
|
||||
------------------------------
|
||||
01: ################################################################################
|
||||
@@ -28,74 +28,78 @@ package. Let's start with an example:
|
||||
11: FOO_LICENSE_FILES = COPYING
|
||||
12: FOO_INSTALL_STAGING = YES
|
||||
13:
|
||||
14: FOO_DEPENDENCIES = host-meson host-pkgconf bar
|
||||
14: FOO_DEPENDENCIES = host-pkgconf bar
|
||||
15:
|
||||
16: FOO_CONF_OPTS += \
|
||||
17: --prefix=/usr \
|
||||
18: --buildtype $(if $(BR2_ENABLE_DEBUG),debug,release) \
|
||||
19: --cross-file $(HOST_DIR)/etc/meson/cross-compilation.conf
|
||||
20:
|
||||
21: FOO_NINJA_OPTS = $(if $(VERBOSE),-v) -j$(PARALLEL_JOBS)
|
||||
16: ifeq ($(BR2_PACKAGE_BAZ),y)
|
||||
17: FOO_CONF_OPTS += -Dbaz=true
|
||||
18: FOO_DEPENDENCIES += baz
|
||||
19: else
|
||||
20: FOO_CONF_OPTS += -Dbaz=false
|
||||
21: endif
|
||||
22:
|
||||
23: ifeq ($(BR2_PACKAGE_BAZ),y)
|
||||
24: FOO_CONF_OPTS += -Dbaz
|
||||
25: endif
|
||||
26:
|
||||
27: define FOO_CONFIGURE_CMDS
|
||||
28: rm -rf $(@D)/build
|
||||
29: mkdir -p $(@D)/build
|
||||
30: $(TARGET_MAKE_ENV) meson $(FOO_CONF_OPTS) $(@D) $(@D)/build
|
||||
31: endef
|
||||
32:
|
||||
33: define FOO_BUILD_CMDS
|
||||
34: $(TARGET_MAKE_ENV) ninja $(FOO_NINJA_OPTS) -C $(@D)/build
|
||||
35: endef
|
||||
36:
|
||||
37: define FOO_INSTALL_TARGET_CMDS
|
||||
38: $(TARGET_MAKE_ENV) DESTDIR=$(TARGET_DIR) ninja $(FOO_NINJA_OPTS) \
|
||||
39: -C $(@D)/build install
|
||||
40: endef
|
||||
41:
|
||||
42: define FOO_INSTALL_STAGING_CMDS
|
||||
43: $(TARGET_MAKE_ENV) DESTDIR=$(STAGING_DIR) ninja $(FOO_NINJA_OPTS) \
|
||||
44: -C $(@D)/build install
|
||||
45: endef
|
||||
46:
|
||||
47: $(eval $(generic-package))
|
||||
23: $(eval $(meson-package))
|
||||
--------------------------------
|
||||
|
||||
The Makefile starts with the definition of the standard variables for package
|
||||
declaration (lines 7 to 11).
|
||||
|
||||
As seen in line 47, it is based on the
|
||||
xref:generic-package-tutorial[+generic-package+ infrastructure]. So, it defines
|
||||
the variables required by this particular infrastructure, where Meson and its
|
||||
companion tool, Ninja, are invoked:
|
||||
On line line 23, we invoke the +meson-package+ macro that generates all the
|
||||
Makefile rules that actually allows the package to be built.
|
||||
|
||||
* +FOO_CONFIGURE_CMDS+: the build directory required by Meson is created, and
|
||||
Meson is invoked to generate the Ninja build file. The options required to
|
||||
configure the cross-compilation of the package are passed via
|
||||
+FOO_CONF_OPTS+.
|
||||
In the example, +host-pkgconf+ and +bar+ are declared as dependencies in
|
||||
+FOO_DEPENDENCIES+ at line 14 because the Meson build file of +foo+ uses
|
||||
`pkg-config` to determine the compilation flags and libraries of package +bar+.
|
||||
|
||||
* +FOO_BUILD_CMDS+: Ninja is invoked to perform the build.
|
||||
Note that it is not necessary to add +host-meson+ in the +FOO_DEPENDENCIES+
|
||||
variable of a package, since this basic dependency is automatically added as
|
||||
needed by the Meson package infrastructure.
|
||||
|
||||
* +FOO_INSTALL_TARGET_CMDS+: Ninja is invoked to install the files generated
|
||||
during the build step in the target directory.
|
||||
|
||||
* +FOO_INSTALL_STAGING_CMDS+: Ninja is invoked to install the files generated
|
||||
during the build step in the staging directory, as +FOO_INSTALL_STAGING+ is
|
||||
set to "YES".
|
||||
|
||||
In order to have Meson available for the build, +FOO_DEPENDENCIES+ needs to
|
||||
contain +host-meson+. In the example, +host-pkgconf+ and +bar+ are also
|
||||
declared as dependencies because the Meson build file of +foo+ uses `pkg-config`
|
||||
to determine the compilation flags and libraries of package +bar+.
|
||||
|
||||
If the "baz" package is selected, then support for the "baz" feature in "foo"
|
||||
is activated by adding +-Dbaz+ to +FOO_CONF_OPTS+, as specified in the
|
||||
+meson_options.txt+ file in "foo" source tree.
|
||||
If the "baz" package is selected, then support for the "baz" feature in "foo" is
|
||||
activated by adding +-Dbaz=true+ to +FOO_CONF_OPTS+ at line 17, as specified in
|
||||
the +meson_options.txt+ file in "foo" source tree. The "baz" package is also
|
||||
added to +FOO_DEPENDENCIES+. Note that the support for +baz+ is explicitly
|
||||
disabled at line 20, if the package is not selected.
|
||||
|
||||
To sum it up, to add a new meson-based package, the Makefile example can be
|
||||
copied verbatim then edited to replace all occurences of +FOO+ with the
|
||||
uppercase name of the new package and update the values of the standard
|
||||
variables.
|
||||
|
||||
[[meson-package-reference]]
|
||||
|
||||
==== +meson-package+ reference
|
||||
|
||||
The main macro of the Meson package infrastructure is +meson-package+. It is
|
||||
similar to the +generic-package+ macro. The ability to have target and host
|
||||
packages is also available, with the +host-meson-package+ macro.
|
||||
|
||||
Just like the generic infrastructure, the Meson infrastructure works by defining
|
||||
a number of variables before calling the +meson-package+ macro.
|
||||
|
||||
First, all the package metadata information variables that exist in the generic
|
||||
infrastructure also exist in the Meson infrastructure: +FOO_VERSION+,
|
||||
+FOO_SOURCE+, +FOO_PATCH+, +FOO_SITE+, +FOO_SUBDIR+, +FOO_DEPENDENCIES+,
|
||||
+FOO_INSTALL_STAGING+, +FOO_INSTALL_TARGET+.
|
||||
|
||||
A few additional variables, specific to the Meson infrastructure, can also be
|
||||
defined. Many of them are only useful in very specific cases, typical packages
|
||||
will therefore only use a few of them.
|
||||
|
||||
* +FOO_SUBDIR+ may contain the name of a subdirectory inside the
|
||||
package that contains the main meson.build file. This is useful,
|
||||
if for example, the main meson.build file is not at the root of
|
||||
the tree extracted by the tarball. If +HOST_FOO_SUBDIR+ is not
|
||||
specified, it defaults to +FOO_SUBDIR+.
|
||||
|
||||
* +FOO_CONF_ENV+, to specify additional environment variables to pass to
|
||||
+meson+ for the configuration step. By default, empty.
|
||||
|
||||
* +FOO_CONF_OPTS+, to specify additional options to pass to +meson+ for the
|
||||
configuration step. By default, empty.
|
||||
|
||||
* +FOO_NINJA_ENV+, to specify additional environment variables to pass to
|
||||
+ninja+, meson companion tool in charge of the build operations. By default,
|
||||
empty.
|
||||
|
||||
* +FOO_NINJA_OPTS+, to specify a space-separated list of targets to build. By
|
||||
default, empty, to build the default target(s).
|
||||
|
||||
@@ -23,8 +23,9 @@ with an example :
|
||||
10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
|
||||
11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
|
||||
12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
|
||||
13:
|
||||
14: $(eval $(perl-package))
|
||||
13: PERL_FOO_BAR_DISTNAME = Foo-Bar
|
||||
14:
|
||||
15: $(eval $(perl-package))
|
||||
------------------------
|
||||
|
||||
On line 7, we declare the version of the package.
|
||||
@@ -40,7 +41,10 @@ On line 11 and 12, we give licensing details about the package (its
|
||||
license on line 11, and the file containing the license text on line
|
||||
12).
|
||||
|
||||
Finally, on line 14, we invoke the +perl-package+ macro that
|
||||
On line 13, the name of the distribution as needed by the script
|
||||
+utils/scancpan+ (in order to regenerate/upgrade these package files).
|
||||
|
||||
Finally, on line 15, we invoke the +perl-package+ macro that
|
||||
generates all the Makefile rules that actually allow the package to be
|
||||
built.
|
||||
|
||||
|
||||
@@ -113,6 +113,12 @@ optionally be defined, depending on the package's needs. Many of them
|
||||
are only useful in very specific cases, typical packages will
|
||||
therefore only use a few of them, or none.
|
||||
|
||||
* +PYTHON_FOO_SUBDIR+ may contain the name of a subdirectory inside the
|
||||
package that contains the main +setup.py+ file. This is useful,
|
||||
if for example, the main +setup.py+ file is not at the root of
|
||||
the tree extracted by the tarball. If +HOST_PYTHON_FOO_SUBDIR+ is not
|
||||
specified, it defaults to +PYTHON_FOO_SUBDIR+.
|
||||
|
||||
* +PYTHON_FOO_ENV+, to specify additional environment variables to
|
||||
pass to the Python +setup.py+ script (for both the build and install
|
||||
steps). Note that the infrastructure is automatically passing
|
||||
|
||||
@@ -86,6 +86,12 @@ If the package bundles a _rebar_ utility, but can use the generic
|
||||
* +ERLANG_FOOBAR_REBAR_ENV+, to specify additional environment
|
||||
variables to pass to the _rebar_ utility.
|
||||
|
||||
* +ERLANG_FOOBAR_KEEP_DEPENDENCIES+, to keep the dependencies
|
||||
described in the rebar.config file. Valid values are +YES+ or +NO+
|
||||
(the default). Unless this variable is set to +YES+, the _rebar_
|
||||
infrastructure removes such dependencies in a post-patch hook to
|
||||
ensure rebar does not download nor compile them.
|
||||
|
||||
With the rebar infrastructure, all the steps required to build
|
||||
and install the packages are already defined, and they generally work
|
||||
well for most rebar-based packages. However, when required, it is
|
||||
|
||||
@@ -32,6 +32,38 @@ using the following rules:
|
||||
with `.` and `-` characters substituted with `_` (e.g.:
|
||||
+FOO_BAR_BOO_VERSION+).
|
||||
|
||||
[[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/*
|
||||
----
|
||||
|
||||
[[testing-package]]
|
||||
==== How to test your package
|
||||
|
||||
@@ -77,9 +109,14 @@ and what package to test:
|
||||
$ ./utils/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
|
||||
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
|
||||
result (excerpt, results are fake):
|
||||
|
||||
----
|
||||
|
||||
@@ -60,10 +60,16 @@ the generic infrastructure also exist in the Waf infrastructure:
|
||||
An additional variable, specific to the Waf infrastructure, can
|
||||
also be defined.
|
||||
|
||||
* +LIBFOO_SUBDIR+ may contain the name of a subdirectory inside the
|
||||
package that contains the main wscript file. This is useful,
|
||||
if for example, the main wscript file is not at the root of
|
||||
the tree extracted by the tarball. If +HOST_LIBFOO_SUBDIR+ is not
|
||||
specified, it defaults to +LIBFOO_SUBDIR+.
|
||||
|
||||
* +LIBFOO_NEEDS_EXTERNAL_WAF+ can be set to +YES+ or +NO+ to tell
|
||||
Buildroot to use the bundled +waf+ executable. If set to +NO+, the
|
||||
default, then Buildroot will use the waf executable provided in the
|
||||
package source tree; if set to +YES+, then Buidlroot will download,
|
||||
package source tree; if set to +YES+, then Buildroot will download,
|
||||
install waf as a host tool and use it to build the package.
|
||||
|
||||
* +LIBFOO_WAF_OPTS+, to specify additional options to pass to the
|
||||
|
||||
@@ -9,8 +9,9 @@ applications) can be integrated into Buildroot. It also shows how
|
||||
existing packages are integrated, which is needed for fixing issues or
|
||||
tuning their configuration.
|
||||
|
||||
When you add a new package, be sure to test it in various conditions;
|
||||
see xref:testing-package[]
|
||||
When you add a new package, be sure to test it in various conditions
|
||||
(see xref:testing-package[]) and also check it for coding style (see
|
||||
xref:check-package[]).
|
||||
|
||||
include::adding-packages-directory.txt[]
|
||||
|
||||
@@ -38,6 +39,8 @@ include::adding-packages-meson.txt[]
|
||||
|
||||
include::adding-packages-cargo.txt[]
|
||||
|
||||
include::adding-packages-golang.txt[]
|
||||
|
||||
include::adding-packages-kernel-module.txt[]
|
||||
|
||||
include::adding-packages-asciidoc.txt[]
|
||||
|
||||
@@ -224,12 +224,12 @@ The +graph-depends+ behaviour can be controlled by setting options in the
|
||||
* +--transitive+, +--no-transitive+, to draw (or not) the transitive
|
||||
dependencies. The default is to not draw transitive dependencies.
|
||||
|
||||
* +--colours R,T,H+, the comma-separated list of colours to draw the
|
||||
* +--colors R,T,H+, the comma-separated list of colors to draw the
|
||||
root package (+R+), the target packages (+T+) and the host packages
|
||||
(+H+). Defaults to: +lightblue,grey,gainsboro+
|
||||
|
||||
--------------------------------
|
||||
BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colours=red,green,blue' make graph-depends
|
||||
BR2_GRAPH_DEPS_OPTS='-d 3 --no-transitive --colors=red,green,blue' make graph-depends
|
||||
--------------------------------
|
||||
|
||||
=== Graphing the build duration
|
||||
|
||||
@@ -194,14 +194,29 @@ bisect+ to locate the origin of a problem.
|
||||
|
||||
First of all, it is essential that the patch has a good commit
|
||||
message. The commit message should start with a separate line with a
|
||||
brief summary of the change, starting with the name of the affected
|
||||
package. The body of the commit message should describe _why_ this
|
||||
brief summary of the change, prefixed by the area touched by the
|
||||
patch. A few examples of good commit titles:
|
||||
|
||||
* +package/linuxptp: bump version to 2.0+
|
||||
|
||||
* +configs/imx23evk: bump Linux version to 4.19+
|
||||
|
||||
* +package/pkg-generic: postpone evaluation of dependency conditions+
|
||||
|
||||
* +boot/uboot: needs host-{flex,bison}+
|
||||
|
||||
* +support/testing: add python-ubjson tests+
|
||||
|
||||
The description that follows the prefix should start with a lower case
|
||||
letter (i.e "bump", "needs", "postpone", "add" in the above examples).
|
||||
|
||||
Second, the body of the commit message should describe _why_ this
|
||||
change is needed, and if necessary also give details about _how_ it
|
||||
was done. When writing the commit message, think of how the reviewers
|
||||
will read it, but also think about how you will read it when you look
|
||||
at this change again a few years down the line.
|
||||
|
||||
Second, the patch itself should do only one change, but do it
|
||||
Third, the patch itself should do only one change, but do it
|
||||
completely. Two unrelated or weakly related changes should usually be
|
||||
done in two separate patches. This usually means that a patch affects
|
||||
only a single package. If several changes are related, it is often
|
||||
@@ -264,6 +279,10 @@ yourself to the DEVELOPERS file. This should be done in the same patch
|
||||
creating or modifying the package. See xref:DEVELOPERS[the DEVELOPERS file]
|
||||
for more information.
|
||||
|
||||
Buildroot provides a handy tool to check for common coding style
|
||||
mistakes on files you created or modified, called +check-package+ (see
|
||||
xref:check-package[] for more information).
|
||||
|
||||
==== Preparing a patch series
|
||||
|
||||
Starting from the changes committed in your local git view, _rebase_
|
||||
@@ -304,6 +323,28 @@ Use the output of +get-developers+ to send your patches:
|
||||
$ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*
|
||||
---------------------
|
||||
|
||||
Alternatively, +get-developers -e+ can be used directly with the
|
||||
+--cc-cmd+ argument to +git send-email+ to automatically CC the
|
||||
affected developers:
|
||||
|
||||
---------------------
|
||||
$ git send-email --to buildroot@buildroot.org \
|
||||
--cc-cmd './utils/get-developers -e' origin/master
|
||||
---------------------
|
||||
|
||||
+git+ can be configured to automatically do this out of the box with:
|
||||
|
||||
---------------------
|
||||
$ git config sendemail.to buildroot@buildroot.org
|
||||
$ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"
|
||||
---------------------
|
||||
|
||||
And then just do:
|
||||
|
||||
---------------------
|
||||
$ git send-email origin/master
|
||||
---------------------
|
||||
|
||||
Note that +git+ should be configured to use your mail account.
|
||||
To configure +git+, see +man git-send-email+ or google it.
|
||||
|
||||
|
||||
@@ -22,6 +22,12 @@ A filesystem overlay is a tree of files that is copied directly
|
||||
etc., files called +.empty+ and files ending in +~+ are excluded from
|
||||
the copy.
|
||||
+
|
||||
When +BR2_ROOTFS_MERGED_USR+ is enabled, then the overlay must not
|
||||
contain the '/bin', '/lib' or '/sbin' directories, as Buildroot will
|
||||
create them as symbolic links to the relevant folders in '/usr'. In
|
||||
such a situation, should the overlay have any programs or libraries,
|
||||
they should be placed in '/usr/bin', '/usr/sbin' and '/usr/lib'.
|
||||
+
|
||||
As shown in xref:customize-dir-structure[], the recommended path for
|
||||
this overlay is +board/<company>/<boardname>/rootfs-overlay+.
|
||||
|
||||
@@ -100,6 +106,15 @@ To enable this feature, enable config option
|
||||
+System configuration+ menu. If you specify a relative path, it will
|
||||
be relative to the root of the Buildroot tree.
|
||||
+
|
||||
Custom skeletons don't need to contain the '/bin', '/lib' or '/sbin'
|
||||
directories, since they are created automatically during the build.
|
||||
When +BR2_ROOTFS_MERGED_USR+ is enabled, then the custom skeleton must
|
||||
not contain the '/bin', '/lib' or '/sbin' directories, as Buildroot
|
||||
will create them as symbolic links to the relevant folders in '/usr'.
|
||||
In such a situation, should the skeleton have any programs or
|
||||
libraries, they should be placed in '/usr/bin', '/usr/sbin' and
|
||||
'/usr/lib'.
|
||||
+
|
||||
This method is not recommended because it duplicates the entire
|
||||
skeleton, which prevents taking advantage of the fixes or improvements
|
||||
brought to the default skeleton in later Buildroot releases.
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
The main Buildroot directory contains a file named +DEVELOPERS+ that
|
||||
lists the developers involved with various areas of Buildroot. Thanks
|
||||
to this file, the +get-developer+ tool allows to:
|
||||
to this file, the +get-developers+ tool allows to:
|
||||
|
||||
- Calculate the list of developers to whom patches should be sent, by
|
||||
parsing the patches and matching the modified files with the
|
||||
@@ -26,20 +26,21 @@ to include in his patch the appropriate modification to the
|
||||
The +DEVELOPERS+ file format is documented in detail inside the file
|
||||
itself.
|
||||
|
||||
The +get-developer+ tool, located in +utils/+ allows to use
|
||||
The +get-developers+ tool, located in +utils/+ allows to use
|
||||
the +DEVELOPERS+ file for various tasks:
|
||||
|
||||
- When passing one or several patches as command line argument,
|
||||
+get-developer+ will return the appropriate +git send-email+
|
||||
command.
|
||||
+get-developers+ will return the appropriate +git send-email+
|
||||
command. If the +-e+ option is passed, only the email addresses are
|
||||
printed in a format suitable for +git send-email --cc-cmd+.
|
||||
|
||||
- When using the +-a <arch>+ command line option, +get-developer+ will
|
||||
- When using the +-a <arch>+ command line option, +get-developers+ will
|
||||
return the list of developers in charge of the given architecture.
|
||||
|
||||
- When using the +-p <package>+ command line option, +get-developer+
|
||||
- When using the +-p <package>+ command line option, +get-developers+
|
||||
will return the list of developers in charge of the given package.
|
||||
|
||||
- When using the +-c+ command line option, +get-developer+ will look
|
||||
- When using the +-c+ command line option, +get-developers+ will look
|
||||
at all files under version control in the Buildroot repository, and
|
||||
list the ones that are not handled by any developer. The purpose of
|
||||
this option is to help completing the +DEVELOPERS+ file.
|
||||
|
||||
File diff suppressed because one or more lines are too long
Binary file not shown.
File diff suppressed because it is too large
Load Diff
@@ -12,7 +12,7 @@ It is licensed under the GNU General Public License, version 2. Refer to the
|
||||
http://git.buildroot.org/buildroot/tree/COPYING?id={sys:git rev-parse HEAD}[COPYING]
|
||||
file in the Buildroot sources for the full text of this license.
|
||||
|
||||
Copyright (C) 2004-2018 The Buildroot developers
|
||||
Copyright (C) 2004-2019 The Buildroot developers
|
||||
|
||||
image::logo.png[]
|
||||
|
||||
|
||||
@@ -59,14 +59,28 @@ Additionally, there are some other useful make targets:
|
||||
|===================================================
|
||||
| command/target | Description
|
||||
|
||||
| +show-depends+ | Displays the dependencies required to build the
|
||||
| +show-depends+ | Displays the first-order dependencies required to build the
|
||||
package
|
||||
|
||||
| +show-recursive-depends+ | Recursively displays the dependencies
|
||||
required to build the package
|
||||
|
||||
| +show-rdepends+ | Displays the first-order reverse dependencies of
|
||||
the package (i.e packages that directly depend on it)
|
||||
|
||||
| +show-recursive-rdepends+ | Recursively displays the reverse
|
||||
dependencies of the package (i.e the packages that depend on it,
|
||||
directly or indirectly)
|
||||
|
||||
| +graph-depends+ | Generate a dependency graph of the package, in the
|
||||
context of the current Buildroot configuration. See
|
||||
xref:graph-depends[this section] for more details about dependency
|
||||
graphs.
|
||||
|
||||
| +graph-rdepends+ | Generate a graph of this package reverse
|
||||
dependencies (i.e the packages that depend on it, directly or
|
||||
indirectly)
|
||||
|
||||
| +dirclean+ | Remove the whole package build directory
|
||||
|
||||
| +reinstall+ | Re-run the install commands
|
||||
|
||||
@@ -32,7 +32,7 @@ between distributions).
|
||||
** +perl+ (version 5.8.7 or any later)
|
||||
** +tar+
|
||||
** +cpio+
|
||||
** +python+ (version 2.6 or any later)
|
||||
** +python+ (version 2.7 or any later)
|
||||
** +unzip+
|
||||
** +rsync+
|
||||
** +file+ (must be in +/usr/bin/file+)
|
||||
|
||||
@@ -81,3 +81,19 @@ make busybox-rebuild all
|
||||
|
||||
the root filesystem image in +output/images+ contains the updated
|
||||
BusyBox.
|
||||
|
||||
Source trees for big projects often contain hundreds or thousands of
|
||||
files which are not needed for building, but will slow down the process
|
||||
of copying the sources with _rsync_. Optionally, it is possible define
|
||||
+<pkg>_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS+ to skip syncing certain files
|
||||
from the source tree. For example, when working on the +webkitgtk+
|
||||
package, the following will exclude the tests and in-tree builds from
|
||||
a local WebKit source tree:
|
||||
|
||||
------------------
|
||||
WEBKITGTK_OVERRIDE_SRCDIR = /home/bob/WebKit
|
||||
WEBKITGTK_OVERRIDE_SRCDIR_RSYNC_EXCLUSIONS = \
|
||||
--exclude JSTests --exclude ManualTests --exclude PerformanceTests \
|
||||
--exclude WebDriverTests --exclude WebKitBuild --exclude WebKitLibraries \
|
||||
--exclude WebKit.xcworkspace --exclude Websites --exclude Examples
|
||||
------------------
|
||||
|
||||
@@ -12,15 +12,23 @@ The toolchain generated by Buildroot is located by default in
|
||||
+output/host/bin/+ to your PATH environment variable and then to
|
||||
use +ARCH-linux-gcc+, +ARCH-linux-objdump+, +ARCH-linux-ld+, etc.
|
||||
|
||||
It is possible to relocate the toolchain, this allows to distribute
|
||||
the toolchain to other developers to build applications for your
|
||||
target. To achieve this:
|
||||
Alternatively, Buildroot can also export the toolchain and the development
|
||||
files of all selected packages, as an SDK, by running the command
|
||||
+make sdk+. This generates a tarball of the content of the host directory
|
||||
+output/host/+, named +<TARGET-TUPLE>_sdk-buildroot.tar.gz+ (which can be
|
||||
overriden by setting the environment variable +BR2_SDK_PREFIX+) and
|
||||
located in the output directory +output/images/+.
|
||||
|
||||
* run +make sdk+, which prepares the toolchain to be relocatable;
|
||||
* tarball the contents of the +output/host+ directory;
|
||||
* distribute the resulting tarball.
|
||||
This tarball can then be distributed to application developers, when
|
||||
they want to develop their applications that are not (yet) packaged as
|
||||
a Buildroot package.
|
||||
|
||||
Once the toolchain is installed to the new location, the user must run
|
||||
the +relocate-sdk.sh+ script to make sure all paths are updated with
|
||||
the new location.
|
||||
Upon extracting the SDK tarball, the user must run the script
|
||||
+relocate-sdk.sh+ (located at the top directory of the SDK), to make
|
||||
sure all paths are updated with the new location.
|
||||
|
||||
Alternatively, if you just want to prepare the SDK without generating
|
||||
the tarball (e.g. because you will just be moving the +host+ directory,
|
||||
or will be generating the tarball on your own), Buildroot also allows
|
||||
you to just prepare the SDK with +make prepare-sdk+ without actually
|
||||
generating a tarball.
|
||||
|
||||
Reference in New Issue
Block a user