Overview
Pants's support for Golang.
We are done implementing the initial core functionality for Pants's initial Go support (tracked here). However, there may be some edge cases we aren't yet handling. There are also some features that are not yet supported like Cgo files and vendoring, which we'd love your input on how to prioritize!
Please share feedback for what you need to use Pants with your Go project by either opening a GitHub issue or joining our Slack!
Go's builtin tooling is already excellent! Many projects may be fine only using Go's tooling, although Pants offers some unique benefits:
- A consistent interface for all languages/tools in your repository, such as being able to run
./pants fmt lint check test package
. - Integration with Git, such as running
./pants --changed-since=HEAD test
. - Caching, such as caching test results on a per-package basis.
- Remote execution and remote caching.
- Advanced project introspection, such as finding all code that transitively depends on a certain package.
Check out github.com/pantsbuild/example-golang to try out Pants's Go support.
We do not yet support multiple first-party Go modules. If you are using multiple modules, please feel free to share your use case on https://github.com/pantsbuild/pants/issues/13114. (For example, if you are using a replace
directive.)
Initial setup
First, activate the Go backend and set the expected Go version in pants.toml
:
[GLOBAL]
backend_packages = ["pants.backend.experimental.go"]
[golang]
expected_version = "1.17"
You can also set [golang].go_search_paths
to influence where Pants looks for Go, e.g. ["/usr/bin"]
. It defaults to your PATH
.
Then run ./pants tailor
to generate BUILD files. This will add a go_mod
target where you have your go.mod
file, along with a go_binary
target in every directory where you have package main
.
❯ ./pants tailor
Created BUILD:
- Add go_mod target root
Created cmd/deploy/BUILD:
- Add go_binary target bin
Created cmd/runner/BUILD:
- Add go_binary target bin
The go_mod
target generates a go_first_party_package
target for each directory in your project with .go
files, and a go_third_party_package
target for each package belonging to the modules declared in your go.mod
. These package targets are the building blocks for Pants, although you rarely will need to interact with them directly.
You can run ./pants list ::
to see all targets in your project, including generated go_first_party_package
and go_third_party_package
targets:
❯ ./pants list
//:root#./cmd/deploy
//:root#./cmd/runner
//:root#./pkg/deploy
//:root#./pkg/runner
...
//:root#golang.org/x/net/ipv4
//:root#golang.org/x/net/ipv6
...
cmd/deploy:bin
cmd/runner:bin
go.mod
and go.sum
need to be up-to-datePants does not yet update your go.mod
and go.sum
for you; it only reads these files when downloading modules.
You will need to run go mod download all
and/or go mod tidy
to update these files when you add a new third-party module or change its version.
Package and run binaries
To run a binary, use ./pants run path/to/main_pkg:
(note the colon). You can pass through arguments with --
, like this:
❯ ./pants run cmd/deploy: -- --help
Usage of /Users/pantsbuild/example/.pants.d/tmpzfh33ggu/cmd.deploy/bin:
--allow-insecure-auth allow credentials to be passed unencrypted (i.e., no TLS)
-A, --auth-token-env string name of environment variable with auth bearer token
...
pflag: help requested
You can also package your binaries (aka go build
) by using ./pants package
. package ::
will build all your project's binaries, whereas package path/to/main_pkg:
will build only the binary in that directory.
❯ ./pants package ::
[INFO] Wrote dist/cmd.deploy/bin
[INFO] Wrote dist/cmd.runner/bin
By default, Pants names the binary with the scheme path.to.directory/target_name
, e.g. cmd.deploy/bin
. You can set the field output_path
to use a different name:
go_binary(name="bin", output_path="deploy")
embed
support coming in Pants 2.9We're making progress on adding support for resources
/ the embed
directive. See https://github.com/pantsbuild/pants/issues/13193.
Compile code
To manually check that a package compiles, use ./pants check
:
# Check this package
❯ ./pants check pkg/deploy:
# Check this directory and all subdirectories
❯ ./pants check pkg::
# Check the whole project
❯ ./pants check ::
(Instead, you can simply run package
, run
, and test
. Pants will compile all the relevant packages.)
Run tests
To run tests, use ./pants test
:
# Test this package
❯ ./pants test pkg/deploy:
# Test this directory and all subdirectories
❯ ./pants check pkg::
# Test the whole project
❯ ./pants test ::
You can pass through arguments with --
, e.g. ./pants test pkg/deploy: -- -v -run TestFoo
.
testdata
folder not yet supportedPlease comment on https://github.com/pantsbuild/pants/issues/13200 if you need this feature for your project so that we can bump its priority.
Gofmt
Gofmt is activated by default when you activate the Go backend. Simply run ./pants fmt
and ./pants lint
:
# Format a single directory
❯ ./pants fmt cmd/deploy:
# Format this directory and all subdirectories
❯ ./pants fmt cmd::
# Lint the whole project
❯ ./pants lint ::
# Format all changed files
❯ ./pants --changed-since=HEAD fmt
If you'd like to disable Gofmt, you can set this:
[gofmt]
skip = true
Support for [gofmt].args
is upcoming, which will allow you to use Gofmt's -r
feature.
Support for go vet
is also upcoming.