From 12ae882bf66ed19bed0e9e127f4d6833aed453e2 Mon Sep 17 00:00:00 2001 From: Angelo Compagnucci Date: Sat, 31 Mar 2018 15:27:31 +0200 Subject: [PATCH] docs/manual: add documentation for the golang infrastructure This patch adds the documentation for the golang infrastructure. Signed-off-by: Angelo Compagnucci Signed-off-by: Thomas Petazzoni Reviewed-by: "Yann E. MORIN" Tested-by: "Yann E. MORIN" Signed-off-by: Arnout Vandecappelle (Essensium/Mind) --- docs/manual/adding-packages-golang.txt | 108 +++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 110 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..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 + +/+. 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[] -- 2.30.2