aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar Angelo Compagnucci <angelo@amarulasolutions.com>2018-03-31 15:27:31 +0200
committerGravatar Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>2018-03-31 19:57:31 +0200
commit12ae882bf66ed19bed0e9e127f4d6833aed453e2 (patch)
treec64ac41660a48f72325dc0651279627b8acfd1ca
parent048b06ed3e59d5d2268bea1de95560b80e4d3f8c (diff)
downloadbuildroot-12ae882bf66ed19bed0e9e127f4d6833aed453e2.tar.gz
buildroot-12ae882bf66ed19bed0e9e127f4d6833aed453e2.tar.bz2
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>
-rw-r--r--docs/manual/adding-packages-golang.txt108
-rw-r--r--docs/manual/adding-packages.txt2
2 files changed, 110 insertions, 0 deletions
diff --git a/docs/manual/adding-packages-golang.txt b/docs/manual/adding-packages-golang.txt
new file mode 100644
index 0000000000..b6d1f5e6b4
--- /dev/null
+++ b/docs/manual/adding-packages-golang.txt
@@ -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.
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index e8d40daee4..c642146287 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -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[]