golang

---

Options for Golang support.

Backend: pants.backend.experimental.go

Config section: [golang]

Basic options

cgo_enabled

--[no-]golang-cgo-enabled
PANTS_GOLANG_CGO_ENABLED

pants.toml

[golang]
cgo_enabled = <bool>

default: True

Enable Cgo support, which allows Go and C code to interact. This option must be enabled for any packages making use of Cgo to actually be compiled with Cgo support.

See https://go.dev/blog/cgo and https://pkg.go.dev/cmd/cgo for additional information about Cgo.

cgo_tool_search_paths

--golang-cgo-tool-search-paths="['<str>', '<str>', ...]"
PANTS_GOLANG_CGO_TOOL_SEARCH_PATHS

pants.toml

[golang]
cgo_tool_search_paths = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "<PATH>"
]

A list of paths to search for tools needed by CGo (e.g., gcc, g++).

Specify absolute paths to directories with tools needed by CGo , e.g. /usr/bin. Earlier entries will be searched first.

The following special strings are supported:

• <PATH>, the contents of the PATH environment variable

Can be overriden by fieldgolang_cgo_tool_search_paths on local_environment, docker_environment, or remote_environmenttargets.

go_search_paths

--golang-go-search-paths="['<str>', '<str>', ...]"
PANTS_GOLANG_GO_SEARCH_PATHS

pants.toml

[golang]
go_search_paths = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "<PATH>"
]

A list of paths to search for Go.

Specify absolute paths to directories with the go binary, e.g. /usr/bin. Earlier entries will be searched first.

The following special strings are supported:

• <PATH>, the contents of the PATH environment variable
• <ASDF>, all Go versions currently configured by ASDF (asdf shell, ${HOME}/.tool-versions), with a fallback to all installed versions
• <ASDF_LOCAL>, the ASDF binary with the version in BUILD_ROOT/.tool-versions

Can be overriden by fieldgolang_go_search_paths on local_environment, docker_environment, or remote_environmenttargets.

minimum_expected_version

--golang-minimum-expected-version=<str>
PANTS_GOLANG_MINIMUM_EXPECTED_VERSION

pants.toml

[golang]
minimum_expected_version = <str>

default: 1.17

The minimum Go version the distribution discovered by Pants must support.

For example, if you set '1.17', then Pants will look for a Go binary that is 1.17+, e.g. 1.17 or 1.18.

You should still set the Go version for each module in your go.mod with the go directive.

Do not include the patch version.

Advanced options

asdf_bin_relpath

--golang-asdf-bin-relpath=<str>
PANTS_GOLANG_ASDF_BIN_RELPATH

pants.toml

[golang]
asdf_bin_relpath = <str>

default: bin

The path relative to an ASDF install directory to use to find the bin directory within an installed Go distribution. The default value for this option works for the go-sdk ASDF plugin. Other ASDF plugins that install Go may have a different relative path to use.

asdf_tool_name

--golang-asdf-tool-name=<str>
PANTS_GOLANG_ASDF_TOOL_NAME

pants.toml

[golang]
asdf_tool_name = <str>

default: go-sdk

The ASDF tool name to use when searching for installed Go distributions using the ASDF tool manager (https://asdf-vm.com/). The default value for this option is for the go-sdk ASDF plugin (https://github.com/yacchi/asdf-go-sdk.git). There are other plugins. If you wish to use one of them, then set this option to the ASDF tool name under which that other plugin was installed into ASDF.

cgo_c_flags

--golang-cgo-c-flags="['<str>', '<str>', ...]"
PANTS_GOLANG_CGO_C_FLAGS

pants.toml

[golang]
cgo_c_flags = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "-g",
  "-O2"
]

Compiler options used when compiling C code when Cgo is enabled. Equivalent to setting the CGO_CFLAGS environment variable when invoking go.

Can be overriden by fieldgolang_cgo_c_flags on local_environment, docker_environment, or remote_environmenttargets.

cgo_cxx_flags

--golang-cgo-cxx-flags="['<str>', '<str>', ...]"
PANTS_GOLANG_CGO_CXX_FLAGS

pants.toml

[golang]
cgo_cxx_flags = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "-g",
  "-O2"
]

Compiler options used when compiling C++ code when Cgo is enabled. Equivalent to setting the CGO_CXXFLAGS environment variable when invoking go.

Can be overriden by fieldgolang_cgo_cxx_flags on local_environment, docker_environment, or remote_environmenttargets.

cgo_fortran_binary_name

--golang-cgo-fortran-binary-name=<str>
PANTS_GOLANG_CGO_FORTRAN_BINARY_NAME

pants.toml

[golang]
cgo_fortran_binary_name = <str>

default: gfortran

Name of the tool to use to compile fortran code included via CGo in a Go package. Pants will search for the tool using the paths specified by the [golang].cgo_tool_search_paths option.

Can be overriden by fieldgolang_cgo_fortran_binary_name on local_environment, docker_environment, or remote_environmenttargets.

cgo_fortran_flags

--golang-cgo-fortran-flags="['<str>', '<str>', ...]"
PANTS_GOLANG_CGO_FORTRAN_FLAGS

pants.toml

[golang]
cgo_fortran_flags = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "-g",
  "-O2"
]

Compiler options used when compiling Fortran code when Cgo is enabled. Equivalent to setting the CGO_FFLAGS environment variable when invoking go.

Can be overriden by fieldgolang_cgo_fortran_flags on local_environment, docker_environment, or remote_environmenttargets.

cgo_gcc_binary_name

--golang-cgo-gcc-binary-name=<str>
PANTS_GOLANG_CGO_GCC_BINARY_NAME

pants.toml

[golang]
cgo_gcc_binary_name = <str>

default: gcc

Name of the tool to use to compile C code included via CGo in a Go package. Pants will search for the tool using the paths specified by the [golang].cgo_tool_search_paths option.

Can be overriden by fieldgolang_cgo_gcc_binary_name on local_environment, docker_environment, or remote_environmenttargets.

cgo_gxx_binary_name

--golang-cgo-gxx-binary-name=<str>
PANTS_GOLANG_CGO_GXX_BINARY_NAME

pants.toml

[golang]
cgo_gxx_binary_name = <str>

default: g++

Name of the tool to use to compile C++ code included via CGo in a Go package. Pants will search for the tool using the paths specified by the [golang].cgo_tool_search_paths option.

Can be overriden by fieldgolang_cgo_gxx_binary_name on local_environment, docker_environment, or remote_environmenttargets.

cgo_linker_flags

--golang-cgo-linker-flags="['<str>', '<str>', ...]"
PANTS_GOLANG_CGO_LINKER_FLAGS

pants.toml

[golang]
cgo_linker_flags = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "-g",
  "-O2"
]

Compiler options used when linking native code when Cgo is enabled. Equivalent to setting the CGO_LDFLAGS environment variable when invoking go.

Can be overriden by fieldgolang_cgo_linker_flags on local_environment, docker_environment, or remote_environmenttargets.

external_linker_binary_name

--golang-external-linker-binary-name=<str>
PANTS_GOLANG_EXTERNAL_LINKER_BINARY_NAME

pants.toml

[golang]
external_linker_binary_name = <str>

default: gcc

Name of the tool to use as the "external linker" when invoking go tool link. Pants will search for the tool using the paths specified by the [golang].cgo_tool_search_paths option.

Can be overriden by fieldgolang_external_linker_binary_name on local_environment, docker_environment, or remote_environmenttargets.

subprocess_env_vars

--golang-subprocess-env-vars="['<str>', '<str>', ...]"
PANTS_GOLANG_SUBPROCESS_ENV_VARS

pants.toml

[golang]
subprocess_env_vars = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "LANG",
  "LC_CTYPE",
  "LC_ALL",
  "PATH"
]

Environment variables to set when invoking the go tool. Entries are either strings in the form ENV_VAR=value to set an explicit value; or just ENV_VAR to copy the value from Pants's own environment.

Can be overriden by fieldgolang_subprocess_env_vars on local_environment, docker_environment, or remote_environmenttargets.

tailor_binary_targets

--[no-]golang-tailor-binary-targets
PANTS_GOLANG_TAILOR_BINARY_TARGETS

pants.toml

[golang]
tailor_binary_targets = <bool>

default: True

If true, add a go_binary target with the tailor goal in every directory with a .go file with package main.

tailor_go_mod_targets

--[no-]golang-tailor-go-mod-targets
PANTS_GOLANG_TAILOR_GO_MOD_TARGETS

pants.toml

[golang]
tailor_go_mod_targets = <bool>

default: True

If true, add a go_mod target with the tailor goal wherever there is a go.mod file.

tailor_package_targets

--[no-]golang-tailor-package-targets
PANTS_GOLANG_TAILOR_PACKAGE_TARGETS

pants.toml

[golang]
tailor_package_targets = <bool>

default: True

If true, add a go_package target with the tailor goal in every directory with a .go file.

Deprecated options

None

Related subsystems

None