123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122 |
- // -*- 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_TARGET_ARCH_SUPPORTS+
- because Buildroot will automatically add a dependency on +host-go+
- to such packages.
- If you need CGO support in your package, you must add a dependency on
- +BR2_PACKAGE_HOST_GO_TARGET_CGO_LINKING_SUPPORTS+.
- The main macro of the Go package infrastructure is
- +golang-package+. It is similar to the +generic-package+ macro. The
- ability to build host packages is also available, with the
- +host-golang-package+ macro.
- Host packages built by +host-golang-package+ macro should depend on
- BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS.
- 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.
- * The package must specify its Go module name in the +FOO_GOMOD+
- variable. If not specified, it defaults to
- +URL-domain/1st-part-of-URL/2nd-part-of-URL+, e.g +FOO_GOMOD+ will
- take the value +github.com/bar/foo+ for a package that specifies
- +FOO_SITE = $(call github,bar,foo,$(FOO_VERSION))+. The Go package
- infrastructure will automatically generate a minimal +go.mod+ file
- in the package source tree if it doesn't exist.
- * +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 +.+. We then have two cases:
- ** +FOO_BUILD_TARGETS+ is +.+. In this case, we assume only one binary
- will be produced, and that by default we name it after the package
- name. If that is not appropriate, the name of the produced binary
- can be overridden using +FOO_BIN_NAME+.
- ** +FOO_BUILD_TARGETS+ is not +.+. In this case, we iterate over the
- values to build each target, and for each produced a binary that is
- the non-directory component of the target. For example if
- +FOO_BUILD_TARGETS = cmd/docker cmd/dockerd+ the binaries produced
- are +docker+ and +dockerd+.
- * +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.
|