adding-packages-golang.txt 4.9 KB

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