Third-Party Packages

Buck2 treats third-party Go packages the same way as first-party packages. There are multiple ways to add third-party packages to your project, but we recommend the following approach:

• Use go.mod for dependency resolution
• Use gobuckify to generate BUCK files for your dependencies

How gobuckify works

gobuckify runs go list all to get a list of all dependencies for your project. Since the go list command resolves dependencies for a specific "target platform," gobuckify runs it multiple times to get dependencies for various combinations of goos/goarch.

The target platforms and code-generation options are configured in a gobuckify.json file that must be in the same directory as your go.mod file.

Your project doesn't have to be fully compatible with go.mod:

• If it is compatible, you can use go mod tidy to keep dependencies up-to-date.
• If it is not compatible, you'll need to maintain a go.mod file with a placeholder file (e.g., index.go) containing blank imports for all your dependencies. You may need additional scripts to scan your project and update this file.

How to use gobuckify

1. Create a gobuckify.json file in the same directory as your go.mod file.
2. Run go mod vendor to copy all dependencies into the vendor/ directory.
3. Run gobuckify to generate BUCK files for your dependencies:

$ (cd ./path/to/go-mod-dir && go mod vendor)
$ buck2 run prelude//go/tools/gobuckify:gobuckify -- ./path/to/go-mod-dir

See a complete example in examples/toolchains/go_toolchain.

The gobuckify.json file

The gobuckify.json file has the following structure:

{
  "buck": {
    "preambule": "# Generated by gobuckify\n", // Added to the top of each BUCK file
    "load_go_binary_rule": "", // Load statement for alternative go_binary rule
    "load_go_library_rule": "", // Load statement for alternative go_library rule
    "go_binary_rule": "go_binary", // Alternative name for go_binary rule (default: "go_binary")
    "go_library_rule": "go_library", // Alternative name for go_library rule (default: "go_library")
    "deps_target_label_prefix": "", // Prefix for dependencies; if provided, deps are formatted as "{prefix}{import}:{import_suffix}"
    "generate_embed_srcs": false, // Generate srcs for go:embed directives (Not supported by prelude/go yet)
    "deps_attr": "deps" // Custom attribute for dependencies (default: "deps")
  },
  "platforms": [
    {
      "go_os": "linux", // Go OS value
      "go_arch": "amd64", // Go architecture value
      "buck_os": "config//os:linux", // Buck OS value
      "buck_arch": "config//cpu:x86_64" // Buck architecture value
    }
  ],
  "default_tags": ["purego"] // List of tags always passed to `go list`
}