1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4=== Infrastructure for Go packages 5 6This infrastructure applies to Go packages that use the standard 7build system and use bundled dependencies. 8 9[[golang-package-tutorial]] 10 11==== +golang-package+ tutorial 12 13First, let's see how to write a +.mk+ file for a go package, 14with an example : 15 16------------------------ 1701: ################################################################################ 1802: # 1903: # foo 2004: # 2105: ################################################################################ 2206: 2307: FOO_VERSION = 1.0 2408: FOO_SITE = $(call github,bar,foo,$(FOO_VERSION)) 2509: FOO_LICENSE = BSD-3-Clause 2610: FOO_LICENSE_FILES = LICENSE 2711: 2812: $(eval $(golang-package)) 29------------------------ 30 31On line 7, we declare the version of the package. 32 33On line 8, we declare the upstream location of the package, here 34fetched from Github, since a large number of Go packages are hosted on 35Github. 36 37On line 9 and 10, we give licensing details about the package. 38 39Finally, on line 12, we invoke the +golang-package+ macro that 40generates all the Makefile rules that actually allow the package to be 41built. 42 43[[golang-package-reference]] 44 45==== +golang-package+ reference 46 47In their +Config.in+ file, packages using the +golang-package+ 48infrastructure should depend on +BR2_PACKAGE_HOST_GO_TARGET_ARCH_SUPPORTS+ 49because Buildroot will automatically add a dependency on +host-go+ 50to such packages. 51If you need CGO support in your package, you must add a dependency on 52+BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS+. 53 54The main macro of the Go package infrastructure is 55+golang-package+. It is similar to the +generic-package+ macro. The 56ability to build host packages is also available, with the 57+host-golang-package+ macro. 58Host packages built by +host-golang-package+ macro should depend on 59BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS. 60 61Just like the generic infrastructure, the Go infrastructure works 62by defining a number of variables before calling the +golang-package+. 63 64All the package metadata information variables that exist in the 65xref:generic-package-reference[generic package infrastructure] also 66exist in the Go infrastructure: +FOO_VERSION+, +FOO_SOURCE+, 67+FOO_PATCH+, +FOO_SITE+, +FOO_SUBDIR+, +FOO_DEPENDENCIES+, 68+FOO_LICENSE+, +FOO_LICENSE_FILES+, +FOO_INSTALL_STAGING+, etc. 69 70Note that it is not necessary to add +host-go+ in the 71+FOO_DEPENDENCIES+ variable of a package, since this basic dependency 72is automatically added as needed by the Go package infrastructure. 73 74A few additional variables, specific to the Go infrastructure, can 75optionally be defined, depending on the package's needs. Many of them 76are only useful in very specific cases, typical packages will 77therefore only use a few of them, or none. 78 79* The package must specify its Go module name in the +FOO_GOMOD+ 80 variable. If not specified, it defaults to 81 +URL-domain/1st-part-of-URL/2nd-part-of-URL+, e.g +FOO_GOMOD+ will 82 take the value +github.com/bar/foo+ for a package that specifies 83 +FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))+. The Go package 84 infrastructure will automatically generate a minimal +go.mod+ file 85 in the package source tree if it doesn't exist. 86 87* +FOO_LDFLAGS+ and +FOO_TAGS+ can be used to pass respectively the 88 +LDFLAGS+ or the +TAGS+ to the +go+ build command. 89 90* +FOO_BUILD_TARGETS+ can be used to pass the list of targets that 91 should be built. If +FOO_BUILD_TARGETS+ is not specified, it 92 defaults to +.+. We then have two cases: 93 94** +FOO_BUILD_TARGETS+ is +.+. In this case, we assume only one binary 95 will be produced, and that by default we name it after the package 96 name. If that is not appropriate, the name of the produced binary 97 can be overridden using +FOO_BIN_NAME+. 98 99** +FOO_BUILD_TARGETS+ is not +.+. In this case, we iterate over the 100 values to build each target, and for each produced a binary that is 101 the non-directory component of the target. For example if 102 +FOO_BUILD_TARGETS = cmd/docker cmd/dockerd+ the binaries produced 103 are +docker+ and +dockerd+. 104 105* +FOO_INSTALL_BINS+ can be used to pass the list of binaries that 106 should be installed in +/usr/bin+ on the target. If 107 +FOO_INSTALL_BINS+ is not specified, it defaults to the lower-case 108 name of package. 109 110With the Go infrastructure, all the steps required to build and 111install the packages are already defined, and they generally work well 112for most Go-based packages. However, when required, it is still 113possible to customize what is done in any particular step: 114 115* By adding a post-operation hook (after extract, patch, configure, 116 build or install). See xref:hooks[] for details. 117 118* By overriding one of the steps. For example, even if the Go 119 infrastructure is used, if the package +.mk+ file defines its own 120 +FOO_BUILD_CMDS+ variable, it will be used instead of the default Go 121 one. However, using this method should be restricted to very 122 specific cases. Do not use it in the general case. 123