docs/manual: add documentation for the golang infrastructure
This patch adds the documentation for the golang infrastructure. Signed-off-by: Angelo Compagnucci <angelo@amarulasolutions.com> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com> Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Tested-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
This commit is contained in:
Angelo Compagnucci
Arnout Vandecappelle (Essensium/Mind)
parent
048b06ed3e
commit
12ae882bf6
108
docs/manual/adding-packages-golang.txt
Normal file
108
docs/manual/adding-packages-golang.txt
Normal file
@ -0,0 +1,108 @@
|
||||
// -*- 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 +.+.
|
||||
|
||||
* +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.
|
||||
@ -38,6 +38,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[]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user