.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Debian::Debhelper::Buildsystem::golang 3pm"
.TH Debian::Debhelper::Buildsystem::golang 3pm "2022-09-25" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh\-golang \-\- debhelper build system class for Go packages
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The dh-golang package provides a build system for debhelper which can be used
by adding \fBdh-sequence-golang\fR to the package build dependencies,
and passing the following options to \fBdh\fR:
.PP
.Vb 2
\& %:
\&        dh $@ \-\-builddirectory=_build \-\-buildsystem=golang
.Ve
.PP
Starting with debhelper 13.4 (a versioned build dependency is currently
required), the build system is automatically detected, and the following
is enough:
.PP
.Vb 2
\& %:
\&        dh $@ \-\-builddirectory=_build
.Ve
.PP
Starting with debhelper compatibility level 14, the build directory defaults
to \fI_build\fR, and the following is enough:
.PP
.Vb 2
\& %:
\&        dh $@
.Ve
.SH "IMPLEMENTATION"
.IX Header "IMPLEMENTATION"
Here is a brief description of how the golang build system implements each
debhelper build system stage:
.IP "\fBconfigure\fR" 4
.IX Item "configure"
Creates a Go workspace (see https://golang.org/doc/code.html#Workspaces) in the
build directory. Copies the source code into that workspace and symlinks all
available libraries from /usr/share/gocode/src into the workspace because the
\&\fBgo\fR\|(1) tool requires write access to the workspace. See also
\&\f(CW\*(C`DH_GOLANG_INSTALL_EXTRA\*(C'\fR and \f(CW\*(C`DH_GOLANG_INSTALL_ALL\*(C'\fR.
.IP "\fBbuild\fR" 4
.IX Item "build"
Determines build targets (see also \f(CW\*(C`DH_GOLANG_BUILDPKG\*(C'\fR and
\&\f(CW\*(C`DH_GOLANG_EXCLUDES\*(C'\fR), possibly calls \f(CW\*(C`go generate\*(C'\fR (see also
\&\f(CW\*(C`DH_GOLANG_GO_GENERATE\*(C'\fR), then calls \f(CW\*(C`go install\*(C'\fR.
.IP "\fBtest\fR" 4
.IX Item "test"
Calls \f(CW\*(C`go test \-v\*(C'\fR on all build targets.
.IP "\fBinstall\fR" 4
.IX Item "install"
Installs binaries and sources from the build directory into the Debian package
destdir. See also \f(CW\*(C`\-\-no\-source\*(C'\fR and \f(CW\*(C`\-\-no\-binaries\*(C'\fR.
.IP "\fBclean\fR" 4
.IX Item "clean"
Removes the build directory.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fBdh_auto_install\fR" 4
.IX Item "dh_auto_install"
.RS 4
.PD 0
.IP "\fB\-\-no\-source\fR" 4
.IX Item "--no-source"
.PD
By default, all files within the src/ subdirectory of the build directory will
be copied to /usr/share/gocode/src/ of the Debian package destdir. Specifying
the \f(CW\*(C`\-\-no\-source\*(C'\fR option disables this behavior, which is useful if you are
packaging a program (as opposed to a library).
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 2
\& override_dh_auto_install:
\&        dh_auto_install \-\- \-\-no\-source
.Ve
.IP "\fB\-\-no\-binaries\fR" 4
.IX Item "--no-binaries"
By default, all files within the bin/ subdirectory of the build directory will
be copied to /usr/bin/ of the Debian package destdir. Specifying the
\&\f(CW\*(C`\-\-no\-binaries\*(C'\fR option disables this behavior.
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 2
\& override_dh_auto_install:
\&        dh_auto_install \-\- \-\-no\-binaries
.Ve
.Sp
Note: instead of using this option (which was added for symmetry with
\&\f(CW\*(C`\-\-no\-source\*(C'\fR), consider not building unwanted binaries in the first place to
save \s-1CPU\s0 time on our build daemons; see \f(CW\*(C`DH_GOLANG_EXCLUDES\*(C'\fR.
.RE
.RS 4
.RE
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """DH_GOPKG""" 4
.el .IP "\f(CWDH_GOPKG\fR" 4
.IX Item "DH_GOPKG"
\&\f(CW\*(C`DH_GOPKG\*(C'\fR (string) contains the Go package name which this Debian package is
building.
.Sp
\&\f(CW\*(C`DH_GOPKG\*(C'\fR is automatically set to the value of the first import path of the
\&\f(CW\*(C`XS\-Go\-Import\-Path\*(C'\fR \f(CW\*(C`debian/control\*(C'\fR field, which can contain several
comma-separated import paths.
.Sp
Example (in \f(CW\*(C`debian/control\*(C'\fR):
.Sp
.Vb 4
\& XS\-Go\-Import\-Path: github.com/go\-mgo/mgo,
\&                    gopkg.in/mgo.v2,
\&                    labix.org/v2/mgo,
\&                    launchpad.net/mgo
.Ve
.Sp
\&\f(CW\*(C`DH_GOPKG\*(C'\fR is set by dh-golang, and as a consequence it is not present in the
\&\f(CW\*(C`debian/rules\*(C'\fR environment. If you need to use the Go package name in the
\&\f(CW\*(C`debian/rules\*(C'\fR file, you must define it yourself.
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 1
\& export DH_GOPKG := github.com/go\-mgo/mgo
.Ve
.Sp
Historical note: before the \f(CW\*(C`XS\-Go\-Import\-Path\*(C'\fR field was introduced, we used
to set \f(CW\*(C`DH_GOPKG\*(C'\fR in \f(CW\*(C`debian/rules\*(C'\fR. When you encounter such a package, please
convert it by moving the value from \f(CW\*(C`debian/rules\*(C'\fR to \f(CW\*(C`debian/control\*(C'\fR. It is
preferable to use the \f(CW\*(C`debian/control\*(C'\fR field because it is machine-readable and
picked up/used by various Debian infrastructure tools, whereas \f(CW\*(C`debian/rules\*(C'\fR is
very hard to parse.
.IP "\s-1DH_GOLANG_INSTALL_EXTRA\s0" 4
.IX Item "DH_GOLANG_INSTALL_EXTRA"
\&\f(CW\*(C`DH_GOLANG_INSTALL_EXTRA\*(C'\fR (list of strings, whitespace-separated, default
empty) enumerates files and directories which are additionally installed into
the build directory. By default, only files with the following extension are
installed: .go, .c, .cc, .cpp, .h, .hh, hpp, .proto, .s. Starting with dh-golang
1.31, testdata directory contents are installed by default.
Starting with dh-golang 1.39, go.mod and go.sum are installed by default
to support Go 1.11 modules.
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 1
\& export DH_GOLANG_INSTALL_EXTRA := example.toml marshal_test.toml
.Ve
.IP "\s-1DH_GOLANG_INSTALL_ALL\s0" 4
.IX Item "DH_GOLANG_INSTALL_ALL"
\&\f(CW\*(C`DH_GOLANG_INSTALL_ALL\*(C'\fR (bool, default false) controls whether all files are
installed into the build directory. By default, only files with the following
extension are installed: .go, .c, .cc, .cpp, .h, .hh, .hpp, .proto, .s. Starting
with dh-golang 1.31, testdata directory contents are installed by default.
Starting with dh-golang 1.39, go.mod and go.sum are installed by default
to support Go 1.11 modules.
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 1
\& export DH_GOLANG_INSTALL_ALL := 1
.Ve
.Sp
Note: prefer the \f(CW\*(C`DH_GOLANG_INSTALL_EXTRA\*(C'\fR environment variable because it is
self-documenting and future-proof: when using \f(CW\*(C`DH_GOLANG_INSTALL_ALL\*(C'\fR, readers
of your package cannot easily tell which extra files in particular need to be
installed, and newer upstream versions might result in unexpected extra files.
.IP "\s-1DH_GOLANG_BUILDPKG\s0" 4
.IX Item "DH_GOLANG_BUILDPKG"
\&\f(CW\*(C`DH_GOLANG_BUILDPKG\*(C'\fR (list of strings, whitespace-separated, default
\&\f(CW\*(C`${DH_GOPKG}/...\*(C'\fR) defines the build targets for compiling this Go package. In
other words, this is what will be passed to \f(CW\*(C`go install\*(C'\fR.
.Sp
The default value matches all Go packages within the source, which is usually
desired, but you might need to exclude example programs, for which you should
use the \f(CW\*(C`DH_GOLANG_EXCLUDES\*(C'\fR environment variable.
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 4
\& # Install only programs for end users, the also\-included Go packages are not
\& # yet mature enough to be shipped for other packages to consume (despite what
\& # upstream claims).
\& export DH_GOLANG_BUILDPKG := github.com/debian/ratt/cmd/...
.Ve
.IP "\s-1DH_GOLANG_EXCLUDES\s0" 4
.IX Item "DH_GOLANG_EXCLUDES"
\&\f(CW\*(C`DH_GOLANG_EXCLUDES\*(C'\fR (list of Perl regular expressions, whitespace-separated,
default empty) defines regular expression patterns to exclude from the build
targets expanded from \f(CW\*(C`DH_GOLANG_BUILDPKG\*(C'\fR.
.Sp
Please note that with \s-1DH_COMPAT\s0 level inferior or equal to 11, the default is
to only exclude pattern from the build target.  (see \f(CW\*(C`DH_GOLANG_EXCLUDES_ALL\*(C'\fR
below)
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 3
\& # We want to build only the library packages themselves, not the accompanying
\& # example binaries.
\& export DH_GOLANG_EXCLUDES := examples/
.Ve
.IP "\s-1DH_GOLANG_EXCLUDES_ALL\s0" 4
.IX Item "DH_GOLANG_EXCLUDES_ALL"
\&\f(CW\*(C`DH_GOLANG_EXCLUDES_ALL\*(C'\fR (boolean, default to true starting from \s-1DH_COMPAT\s0
level 12) makes \f(CW\*(C`DH_GOLANG_EXCLUDE\*(C'\fR excludes files not only during the
building process but also for install.  This is useful, if, for instance,
examples are installed with \f(CW\*(C`dh_installexamples\*(C'\fR. If you only want to
exclude files from the building process but keep them in the source, set this
to false.
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 4
\& # We want to ship only the library packages themselves in the go source, not
\& # the accompanying example binaries.
\& export DH_GOLANG_EXCLUDES := examples/
\& export DH_GOLANG_EXCLUDES_ALL := 1
.Ve
.IP "\s-1DH_GOLANG_GO_GENERATE\s0" 4
.IX Item "DH_GOLANG_GO_GENERATE"
\&\f(CW\*(C`DH_GOLANG_GO_GENERATE\*(C'\fR (bool, default false) controls whether \f(CW\*(C`go generate\*(C'\fR
is called on all build targets (see \f(CW\*(C`DH_GOLANG_BUILDPKG\*(C'\fR).
.Sp
It is convention in the Go community to commit all \f(CW\*(C`go generate\*(C'\fR artifacts to
version control, so re-generating these artifacts is usually not required.
.Sp
Depending on what the Go package in question uses \f(CW\*(C`go generate\*(C'\fR for, you may
want to enable \f(CW\*(C`DH_GOLANG_GO_GENERATE\*(C'\fR:
.RS 4
.IP "\(bu" 4
If the Go package uses \f(CW\*(C`go generate\*(C'\fR to generate artifacts purely from inputs
within its own source (e.g. creating a perfect hash table), there usually is no
need to re-generate that output. It does not necessarily hurt, either, but some
\&\f(CW\*(C`go generate\*(C'\fR commands might be poorly tested and break the build.
.IP "\(bu" 4
If the Go package uses \f(CW\*(C`go generate\*(C'\fR to (e.g.) bundle a JavaScript library into
a template file which is then compiled into a Go program, it is advisable to
re-generate that output so that the Debian version of the JavaScript library is
picked up, as opposed to the pre-generated version.
.RE
.RS 4
.Sp
Example (in \f(CW\*(C`debian/rules\*(C'\fR):
.Sp
.Vb 1
\& export DH_GOLANG_GO_GENERATE := 1
.Ve
.Sp
Note: this option should default to true, but it was introduced after dh-golang
was already widely used, and nobody made the transition happen yet (i.e. inspect
and possibly fix any resulting breakages).
.RE