Go support is beta 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, we invite you to share your use case on <https://github.com/pantsbuild/pants/issues/13114>. (For example, if you are using a `
## Initial setup
First, activate the Go backend in `
You may want to set the option `
[golang].minimum_expected_version` to a value like `
"1.17"`. Pants will use this to find a Go distribution that is the same version or newer. You still set your projects' Go version with `
go.mod` with the `
go` directive; this option is only used for Pants to discover a compatible Go distribution.
You can also set `
[golang].go_search_paths` to influence where Pants looks for Go, e.g. `
["/usr/bin"]`. It defaults to your `
Then run [`
./pants tailor ::`](🔗) to generate BUILD files. This will add a `
go_mod` target where you have your `
go.mod` file, a `
go_package` target for every directory with a `
.go` file, and a `
go_binary` target in every directory where you have `
go_package` target allows you to set metadata for that directory, such as the `
test_timeout` field. However, Pants uses sensible defaults so, usually, you can simply use what was generated by `
go_mod` target generates a `
go_third_party_package` target for each package belonging to the modules declared in your `
go.mod`. You will rarely need to interact with these directly, thanks to dependency inference.
You can run `
./pants list ::` to see all targets in your project, including generated `
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. Run `
go mod download all` to make sure these files are correct.
### The `
embed` directive and `
To use the [`
embed` directive](🔗), you must first teach Pants about the [files](🔗) with the `
resource` / `
Add a `
resource` or `
resources` target with the embedded files in the `
source` / `
sources` field, respectively.
Add that target to the `
dependencies` field of the relevant `
## 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:
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.
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:
## Compile code
To manually check that a package compiles, use `
(Instead, you can simply run `
run`, and `
test`. Pants will compile all the relevant packages.)
## Run tests
To run tests, use `
You can pass through arguments with `
--`, e.g. `
./pants test pkg/deploy: -- -v -run TestFoo`.
### Loose files in tests (`
To open files in your tests, use [`
file` / `
files` targets](🔗) targets and add them as `
dependencies` to your `
Traditionally in Go, these files are located in the `
testdata` directory. However, with Pants, you can place the files wherever you'd like. Pants sets the working directory to the path of the `
go_package`, which allows you to open files regardless of where there are in your repository, such as with `
Pants can cancel tests that take too long, which is useful to prevent tests from hanging indefinitely.
To add a timeout, set the `
test_timeout` field to an integer value of seconds, like this:
Gofmt is activated by default when you activate the Go backend. Simply run `
./pants fmt` and `
If you'd like to disable Gofmt, set this:
To only run Gofmt, use `
--fmt-only` and `