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

[Yann E. MORIN <yann.morin.1998@free.fr>]

Thomas, Angelo, All,

On 2018-03-31 15:27 +0200, Thomas Petazzoni spake thusly:
> From: Angelo Compagnucci <angelo@amarulasolutions.com>
> 
> 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>

Regards,
Yann E. MORIN.

> ---
>  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
> 
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'