Skip to main content
Version: 2.8 (deprecated)

Overview

Pants's support for Golang.

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!

Please share feedback for what you need to use Pants with your Go project by either opening a GitHub issue or joining our Slack!

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 replace directive.)

Initial setup​

First, activate the Go backend and set the expected Go version in pants.toml:

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-date

Pants 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:

cmd/deploy/BUILD
go_binary(name="bin", output_path="deploy")
embed support coming in Pants 2.9

We'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 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​

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:

pants.toml
[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.