Go support is alpha stage
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!
Why use Pants with Go?
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.
Example Go repository
Check out github.com/pantsbuild/example-golang to try out Pants's Go support.
Assumes you're using a single Go module
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
First, activate the Go backend and set the expected Go version in
[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
./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
❯ ./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
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
❯ ./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.sumneed to be up-to-date
Pants does not yet update your
go.sumfor you; it only reads these files when downloading modules.
You will need to run
go mod download alland/or
go mod tidyto update these files when you add a new third-party module or change its version.
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
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
cmd.deploy/bin. You can set the field
output_path to use a different name:
embedsupport coming in Pants 2.9
We're making progress on adding support for
embeddirective. See https://github.com/pantsbuild/pants/issues/13193.
To manually check that a package compiles, use
# 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
test. Pants will compile all the relevant packages.)
To run tests, use
# 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
./pants test pkg/deploy: -- -v -run TestFoo.
testdatafolder not yet supported
Please 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 is activated by default when you activate the Go backend. Simply run
./pants fmt and
# 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
go vet is also upcoming.
Updated about 2 years ago