[Buildroot] [PATCH v4 3/8] docs/manual: add documentation for the golang infrastructure

[Thomas Petazzoni]

From: Angelo Compagnucci <angelo at amarulasolutions.com>

This patch adds the documentation for the golang infrastructure.

Signed-off-by: Angelo Compagnucci <angelo at amarulasolutions.com>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni at bootlin.com>
---
 docs/manual/adding-packages-golang.txt | 110 +++++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt        |   2 +
 2 files changed, 112 insertions(+)
 create mode 100644 docs/manual/adding-packages-golang.txt

diff --git a/docs/manual/adding-packages-golang.txt b/docs/manual/adding-packages-golang.txt
new file mode 100644
index 0000000000..418da5fa4f
--- /dev/null
+++ b/docs/manual/adding-packages-golang.txt
@@ -0,0 +1,110 @@
+// -*- 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 +go+ or +host-go+ in the
+   +FOO_DEPENDENCIES+ variable of a package, since these basic
+   dependencies are 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 +/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[]
-- 
2.14.3