2018-03-31 15:27:31 +02:00
|
|
|
// -*- 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 :
|
|
|
|
|
2024-07-12 20:23:24 +02:00
|
|
|
----
|
2018-03-31 15:27:31 +02:00
|
|
|
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))
|
2024-07-12 20:23:24 +02:00
|
|
|
----
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
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+
|
2019-02-06 14:23:57 +01:00
|
|
|
infrastructure should depend on +BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS+
|
|
|
|
because Buildroot will automatically add a dependency on +host-go+
|
|
|
|
to such packages.
|
|
|
|
If you need CGO support in your package, you must add a dependency on
|
|
|
|
+BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS+.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
The main macro of the Go package infrastructure is
|
2019-02-06 14:23:58 +01:00
|
|
|
+golang-package+. It is similar to the +generic-package+ macro. The
|
|
|
|
ability to build host packages is also available, with the
|
|
|
|
+host-golang-package+ macro.
|
|
|
|
Host packages built by +host-golang-package+ macro should depend on
|
docs/manual: standardize references to the generic infra
Currently the text for each package infra that mentions the usage of
variables already provided by the generic infra diverge from each other:
- some (golang, kconfig, python) add a cross-referece to the generic
infra chapter;
- kconfig does not list any example;
- some mention _LICENSE as an example, others don't;
- some (cargo, golang, python) add an 'etc.' at the end of the examples,
giving the idea that can be more symbols provided by the generic
infra than the ones listed;
- most have the text 'works by defining a number of variables before
calling the +<macro-name>+ macro', except golang and kconfig;
- some actually list 'A few additional variables' but keep using some
old reference as 'An additional variable';
- some say 'First, all the package metadata' and other only 'All the
package metadata';
- most mention _SUBDIR as an example of variable supported by the
generic infra, even the generic infra manual not mentioning it.
Improve the correctness for the manual by standardizing the text among
the package infras:
- use the same text "All the package metadata information variables that
exist in the generic package infrastructure also exist in the
<name> infrastructure:" for all of them;
- add the cross-reference for all of them;
- remove the examples of variables inherited from the generic infra -
this also solves the _SUBDIR problem, there no longer is any reference
to _SUBDIR;
- wrap the modified text at 80 columns;
- add "macro" to golang and luarocks infra;
- use "A few additional variables" for qmake and waf.
At same time, add a missing format on golang manual for
BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
Cc: Eric Le Bihan <eric.le.bihan.dev@free.fr>
Cc: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
Signed-off-by: Ricardo Martincoski <ricardo.martincoski@gmail.com>
[Arnout:
- remove the examples;
- add "the" where "macro" was added;
- rewrite the preceding paragraphs for kconfig to make it more
consistent.
]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
(cherry picked from commit 4286c89f9d987f5f3bcbb14dfd58ba440944f4c2)
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2023-01-02 00:36:53 +01:00
|
|
|
+BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS+.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
Just like the generic infrastructure, the Go infrastructure works
|
docs/manual: standardize references to the generic infra
Currently the text for each package infra that mentions the usage of
variables already provided by the generic infra diverge from each other:
- some (golang, kconfig, python) add a cross-referece to the generic
infra chapter;
- kconfig does not list any example;
- some mention _LICENSE as an example, others don't;
- some (cargo, golang, python) add an 'etc.' at the end of the examples,
giving the idea that can be more symbols provided by the generic
infra than the ones listed;
- most have the text 'works by defining a number of variables before
calling the +<macro-name>+ macro', except golang and kconfig;
- some actually list 'A few additional variables' but keep using some
old reference as 'An additional variable';
- some say 'First, all the package metadata' and other only 'All the
package metadata';
- most mention _SUBDIR as an example of variable supported by the
generic infra, even the generic infra manual not mentioning it.
Improve the correctness for the manual by standardizing the text among
the package infras:
- use the same text "All the package metadata information variables that
exist in the generic package infrastructure also exist in the
<name> infrastructure:" for all of them;
- add the cross-reference for all of them;
- remove the examples of variables inherited from the generic infra -
this also solves the _SUBDIR problem, there no longer is any reference
to _SUBDIR;
- wrap the modified text at 80 columns;
- add "macro" to golang and luarocks infra;
- use "A few additional variables" for qmake and waf.
At same time, add a missing format on golang manual for
BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
Cc: Eric Le Bihan <eric.le.bihan.dev@free.fr>
Cc: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
Signed-off-by: Ricardo Martincoski <ricardo.martincoski@gmail.com>
[Arnout:
- remove the examples;
- add "the" where "macro" was added;
- rewrite the preceding paragraphs for kconfig to make it more
consistent.
]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
(cherry picked from commit 4286c89f9d987f5f3bcbb14dfd58ba440944f4c2)
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2023-01-02 00:36:53 +01:00
|
|
|
by defining a number of variables before calling the +golang-package+
|
|
|
|
macro.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
All the package metadata information variables that exist in the
|
|
|
|
xref:generic-package-reference[generic package infrastructure] also
|
docs/manual: standardize references to the generic infra
Currently the text for each package infra that mentions the usage of
variables already provided by the generic infra diverge from each other:
- some (golang, kconfig, python) add a cross-referece to the generic
infra chapter;
- kconfig does not list any example;
- some mention _LICENSE as an example, others don't;
- some (cargo, golang, python) add an 'etc.' at the end of the examples,
giving the idea that can be more symbols provided by the generic
infra than the ones listed;
- most have the text 'works by defining a number of variables before
calling the +<macro-name>+ macro', except golang and kconfig;
- some actually list 'A few additional variables' but keep using some
old reference as 'An additional variable';
- some say 'First, all the package metadata' and other only 'All the
package metadata';
- most mention _SUBDIR as an example of variable supported by the
generic infra, even the generic infra manual not mentioning it.
Improve the correctness for the manual by standardizing the text among
the package infras:
- use the same text "All the package metadata information variables that
exist in the generic package infrastructure also exist in the
<name> infrastructure:" for all of them;
- add the cross-reference for all of them;
- remove the examples of variables inherited from the generic infra -
this also solves the _SUBDIR problem, there no longer is any reference
to _SUBDIR;
- wrap the modified text at 80 columns;
- add "macro" to golang and luarocks infra;
- use "A few additional variables" for qmake and waf.
At same time, add a missing format on golang manual for
BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
Cc: Eric Le Bihan <eric.le.bihan.dev@free.fr>
Cc: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
Signed-off-by: Ricardo Martincoski <ricardo.martincoski@gmail.com>
[Arnout:
- remove the examples;
- add "the" where "macro" was added;
- rewrite the preceding paragraphs for kconfig to make it more
consistent.
]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
(cherry picked from commit 4286c89f9d987f5f3bcbb14dfd58ba440944f4c2)
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2023-01-02 00:36:53 +01:00
|
|
|
exist in the Go infrastructure.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2020-08-29 14:43:11 +02:00
|
|
|
* The package must specify its Go module name in the +FOO_GOMOD+
|
|
|
|
variable. If not specified, it defaults to
|
|
|
|
+URL-domain/1st-part-of-URL/2nd-part-of-URL+, e.g +FOO_GOMOD+ will
|
|
|
|
take the value +github.com/bar/foo+ for a package that specifies
|
|
|
|
+FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))+. The Go package
|
|
|
|
infrastructure will automatically generate a minimal +go.mod+ file
|
|
|
|
in the package source tree if it doesn't exist.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
* +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
|
package/pkg-golang: use 'build' instead of 'install'
So far, we were using the 'go install' mechanism to build a package
and have its binary installed in
$$($(2)_WORKSPACE)/bin/linux_$$(GO_GOARCH). This worked fine when
building on x86-64 for ARM, but failed when building on x86-64 for
x86-64 because the binaries were installed in $$($(2)_WORKSPACE)/bin/.
Instead of doing some complicated logic to guess whether Go is going
to put our binaries in $$($(2)_WORKSPACE)/bin/ or in
$$($(2)_WORKSPACE)/bin/linux_$$(GO_GOARCH), we revert back to using
"go build", as it was done before the introduction of the golang
package infrastructure. "go build" lets us pass explicitly the
destination path of the binary to be generated.
There's just one complexity with how to decide on the name of the
binary that should be produced, and we have two cases:
- <pkg>_BUILD_TARGETS is the default, i.e ".". In this case we assume
a single binary is produced by "go build", and we name if after the
lower case package name. We allow this to be overridden thanks to
<pkg>_BIN_NAME.
- <pkg>_BUILD_TARGETS is non-default, and typically contains
something like "foo bar" or "cmd/foo cmd/bar". In this case, we
assume the binaries to be produced are "foo" and "bar", i.e we take
the non-directory part of the build target to name the binaries.
Because we're using this -o option, we no longer need to explicitly
create the binary directory, it is done by "go build".
Fixes:
http://autobuild.buildroot.net/results/1f9cd7c48e8c8f41326632a9c0de83915d72c45b/
[Peter: use $(or instead of $(if as suggested by Arnout]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2018-04-01 13:51:35 +02:00
|
|
|
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+.
|
2018-03-31 15:27:31 +02:00
|
|
|
|
|
|
|
* +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.
|
2022-01-08 23:33:32 +01:00
|
|
|
|
|
|
|
A Go package can depend on other Go modules, listed in its +go.mod+
|
|
|
|
file. Buildroot automatically takes care of downloading such
|
|
|
|
dependencies as part of the download step of packages that use the
|
|
|
|
+golang-package+ infrastructure. Such dependencies are then kept
|
|
|
|
together with the package source code in the tarball cached in
|
|
|
|
Buildroot's +DL_DIR+, and therefore the hash of the package's tarball
|
|
|
|
includes such dependencies.
|
|
|
|
|
|
|
|
This mechanism ensures that any change in the dependencies will be
|
|
|
|
detected, and allows the build to be performed completely offline.
|