Skip to main content
Version: 2.23 (prerelease)

go_binary

A Go binary.

Backend: pants.backend.experimental.go

asan​

bool | None
default: None

Enable interoperation between Go code and the C/C++ "address sanitizer."

See https://github.com/google/sanitizers/wiki/AddressSanitizer for additional information about the C/C++ address sanitizer.

assembler_flags​

Iterable[str] | None
default: None

Extra flags to pass to the Go assembler (i.e., go tool asm) when assembling Go-format assembly code.

Note: These flags will not be added to gcc/clang-format assembly that is assembled in packages using Cgo.

This field can be specified on several different target types:

  • On go_mod targets, the assembler flags are used when building any package involving the module including both first-party (i.e., go_package targets) and third-party dependencies.

  • On go_binary targets, the assembler flags are used when building any packages comprising that binary including third-party dependencies. These assembler flags will be added after any assembler flags added by any assembler_flags field set on the applicable go_mod target.

  • On go_package targets, the assembler flags are used only for building that specific package and not for any other package. These assembler flags will be added after any assembler flags added by any assembler_flags field set on the applicable go_mod target or applicable go_binary target.

Run go doc cmd/asm to see the flags supported by go tool asm.

cgo_enabled​

bool | None
default: None

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.

This field can be specified on several different target types, including go_binary and go_mod target types. If this field is specified on a go_binary target, then that instance takes precedence over other configuration when building the applicable executable. The applicable go_mod target will be checked next as a fallback. Finally, if neither target specifies this field, then the value will be taken from the value of the [golang].cgo_enabled option. (Note: That option will be deprecated in a future Pants version.)

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

compiler_flags​

Iterable[str] | None
default: None

Extra flags to pass to the Go compiler (i.e., go tool compile) when compiling Go code.

This field can be specified on several different target types:

  • On go_mod targets, the compiler flags are used when compiling any package involving the module including both first-party (i.e., go_package targets) and third-party dependencies.

  • On go_binary targets, the compiler flags are used when compiling any packages comprising that binary including third-party dependencies. These compiler flags will be added after any compiler flags added by any compiler_flags field set on the applicable go_mod target.

  • On go_package targets, the compiler flags are used only for compiling that specific package and not for any other package. These compiler flags will be added after any compiler flags added by any compiler_flags field set on the applicable go_mod target or applicable go_binary target.

Run go doc cmd/compile to see the flags supported by go tool compile.

description​

str | None
default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

environment​

str | None
default: '__local__'

Specify which environment target to consume environment-sensitive options from.

Once environments are defined in [environments-preview].names, you can specify the environment for this target by its name. Any fields that are defined in that environment will override the values from options set by pants.toml, command line values, or environment variables.

You can specify multiple valid environments by using parametrize. If __local__ is specified, Pants will fall back to the local_environment defined for the current platform, or no environment if no such environment exists.

linker_flags​

Iterable[str] | None
default: None

Extra flags to pass to the Go linker (i.e., go tool link) when linking Go binaries.

This field can be specified on several different target types:

  • On go_mod targets, the linker flags are used when linking any binary involving the module including both go_binary targets and test binaries for go_package targets within the module.

  • On go_binary targets, the linker flags are used when linking that binary. These linker flags will be added after any linker flags added by any linker_flags field set on the applicable go_mod target.

Run go doc cmd/link to see the flags supported by go tool link.

main​

str | None
default: None

Address of the go_package with the main for this binary.

If not specified, will default to the go_package for the same directory as this target's BUILD file. You should usually rely on this default.

msan​

bool | None
default: None

Enable interoperation between Go code and the C/C++ "memory sanitizer."

See https://github.com/google/sanitizers/wiki/MemorySanitizer for additional information about the C/C++ memory sanitizer.

output_path​

str | None
default: '${spec_path_normalized}/${target_name_normalized}${file_suffix}'

Where the built asset should be located.

This field supports the following template replacements:

  • ${spec_path_normalized}: The path to the target's directory ("spec path") with forward slashes replaced by dots.

  • ${target_name_normalized}: The target's name with paramaterizations escaped by replacing dots with underscores.

  • ${file_suffix}: For target's which produce single file artifacts, this is the file type suffix to use with a leading dot, and is empty otherwise when not applicable.

If undefined, this will use the path to the BUILD file, followed by the target name. For example, src/python/project:app would be src.python.project/app.ext. This behavior corresponds to the default template: ${spec_path_normalized}/${target_name_normalized}${file_suffix}

When running pants package, this path will be prefixed by --distdir (e.g. dist/).

Warning: setting this value risks naming collisions with other package targets you may have.

race​

bool | None
default: None

Enable compiling the binary with the Go data race detector.

See https://go.dev/doc/articles/race_detector for additional information about the Go data race detector.

restartable​

bool
default: False

If true, runs of this target with the run goal may be interrupted and restarted when its input files change.

tags​

Iterable[str] | None
default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.