ref-manual: initial documentation for go and go-mod classes

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

This addresses [YOCTO #14582]

---
 If you are familiar with the Go classes, please review and propose corrections
 or extensions to what I wrote. My understanding of Go is very limited,
 and I'm not even sure go-mod.bbclass is for building or just importing
 Go modules.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Jan Dorniak <jaskij@gmail.com>
---
 documentation/ref-manual/classes.rst   | 23 +++++++++
 documentation/ref-manual/variables.rst | 67 ++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

Michael,

The descriptions look good to me.

Thanks,
-Matt

On Wed, Jan 11, 2023 at 1:51 AM <michael.opdenacker@bootlin.com> wrote:
>
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>
> This addresses [YOCTO #14582]
>
> ---
>  If you are familiar with the Go classes, please review and propose corrections
>  or extensions to what I wrote. My understanding of Go is very limited,
>  and I'm not even sure go-mod.bbclass is for building or just importing
>  Go modules.
>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> Reported-by: Jan Dorniak <jaskij@gmail.com>
> ---
>  documentation/ref-manual/classes.rst   | 23 +++++++++
>  documentation/ref-manual/variables.rst | 67 ++++++++++++++++++++++++++
>  2 files changed, 90 insertions(+)
>
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 7dba617db5..0cb507b500 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -758,6 +758,29 @@ software from the GNOME stack. This class sets
>  mirrors as well as extending :term:`FILES` with the typical
>  GNOME installation paths.
>
> +.. _ref-classes-go:
> +
> +``go``
> +======
> +
> +The :ref:`ref-classes-go` class supports building Go programs. The behavior of
> +this class is controlled by the mandatory :term:`GO_IMPORT` variable, and
> +by the optional :term:`GO_INSTALL` and :term:`GO_INSTALL_FILTEROUT` ones.
> +
> +To build a Go program with the Yocto Project, you can use the
> +:yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
> +recipe as an example.
> +
> +.. _ref-classes-go-mod:
> +
> +``go-mod``
> +==========
> +
> +The :ref:`ref-classes-go-mod` class allows to use Go modules, and inherits the
> +:ref:`ref-classes-go` class.
> +
> +See the associated :term:`GO_WORKDIR` variable.
> +
>  .. _ref-classes-gobject-introspection:
>
>  ``gobject-introspection``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index f2decd713b..8419c80d03 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -3012,6 +3012,73 @@ system and gives an overview of their function and contents.
>
>           GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
>
> +   :term:`GO_IMPORT`
> +      When inheriting the :ref:`ref-classes-go` class, this mandatory variable
> +      sets the import path for the Go package that will be created for the code
> +      to build. If you have a ``go.mod`` file in the source directory, this
> +      typically matches the path in the ``module`` line in this file.
> +
> +      Other Go programs importing this package will use this path.
> +
> +      Here is an example setting from the
> +      :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
> +      recipe::
> +
> +          GO_IMPORT = "golang.org/x/example"
> +
> +   :term:`GO_INSTALL`
> +      When inheriting the :ref:`ref-classes-go` class, this optional variable
> +      specifies which packages in the sources should be compiled and
> +      installed in the Go build space by the
> +      `go install <https://go.dev/ref/mod#go-install>`__ command.
> +
> +      Here is an example setting from the
> +      :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>`
> +      recipe::
> +
> +         GO_INSTALL = "\
> +             ${GO_IMPORT}/cmd/crucible \
> +             ${GO_IMPORT}/cmd/habtool \
> +         "
> +
> +      By default, :term:`GO_INSTALL` is defined as::
> +
> +         GO_INSTALL ?= "${GO_IMPORT}/..."
> +
> +      The ``...`` wildcard means that it will catch all
> +      packages found in the sources.
> +
> +      See the :term:`GO_INSTALL_FILTEROUT` variable for
> +      filtering out unwanted packages from the ones
> +      found from the :term:`GO_INSTALL` value.
> +
> +   :term:`GO_INSTALL_FILTEROUT`
> +      When using the Go "vendor" mechanism to bring in dependencies for a Go
> +      package, the default :term:`GO_INSTALL` setting, which uses the ``...``
> +      wildcard, will include the vendored packages in the build, which produces
> +      incorrect results.
> +
> +      There are also some Go packages that are structured poorly, so that the
> +      ``...`` wildcard results in building example or test code that should not
> +      be included in the build, or could fail to build.
> +
> +      This optional variable allows for filtering out a subset of the sources.
> +      It defaults to excluding everything under the ``vendor`` subdirectory
> +      under package's main directory. This is the normal location for vendored
> +      packages, but it can be overridden by a recipe to filter out other
> +      subdirectories if needed.
> +
> +   :term:`GO_WORKDIR`
> +      When using Go Modules, the current working directory must be the directory
> +      containing the ``go.mod`` file, or one of its subdirectories. When the
> +      ``go`` tool is used, it will automatically look for the ``go.mod`` file
> +      in the Go working directory or in any parent directory, but not in
> +      subdirectories.
> +
> +      When using the :ref:`ref-classes-go-mod` class to use Go modules,
> +      the optional :term:`GO_WORKDIR` variable, defaulting to the value
> +      of :term:`GO_IMPORT`, allows to specify a different Go working directory.
> +
>     :term:`GROUPADD_PARAM`
>        When inheriting the :ref:`ref-classes-useradd` class,
>        this variable specifies for a package what parameters should be
> --
> 2.37.2
>