diff options
Diffstat (limited to 'tools/build_rules/go/DESIGN.md')
| -rw-r--r-- | tools/build_rules/go/DESIGN.md | 61 |
1 files changed, 0 insertions, 61 deletions
diff --git a/tools/build_rules/go/DESIGN.md b/tools/build_rules/go/DESIGN.md deleted file mode 100644 index 15015c4ae3..0000000000 --- a/tools/build_rules/go/DESIGN.md +++ /dev/null @@ -1,61 +0,0 @@ -Go support in Bazel -=================== - -Objective ---------- - -Provide Go support in Bazel that feels familiar to existing Go users and -existing Go tools. - - -Use cases ---------- - -Users might find benefit from using Bazel for Go in the following scenarios: - -* Multi-language/multi-platform builds, where not all platforms are supported by `go` natively. For example: test iOS app running against a Go backend from a single tool, or Bazel itself, where the BUILD file formatter (`buildifier`) is written Go, and Bazel (Java/C++) interact. -* Large Go projects, where correctness and scalability of `go` become a problem. -* Go projects where the executable is not the final product. -* Projects with complex native code builds, eg. a Go server that uses first party native code through CGO. -* Projects with complex code generation steps, such as protocol buffers. - -Constraints ------------ - -The Go rules should not impose restrictions on how non-Go projects should organize their source trees. - -Proposal --------- - -* Bazel will support `go_library`, `go_binary` and `go_test` rules. These take go files as srcs, and `go_library` rules as `deps`. Along with the rules, we will have a tool that generates the main.go file based on the sources of a go_test rule. -* The go rules use a global setting `GO_PREFIX`. `GO_PREFIX` is set through Bazel's `WORKSPACE` mechanism, and may be empty. It is recommended that Go projects use the canonical import name (eg. `github.com/name/project`) as `GO_PREFIX` in Bazel. -* The go rules will support dependencies on go_library targets with other names, eg. `//a/b:c`. These are to be imported as `GO_PREFIX/a/b/c`. This convention is typically used for depending on generated Go code. -* The go rules will support a magic target name `go_default_library`. A dependency on `//a/b:go_default_library` will be staged by Bazel so it can be imported in a go file as `GO_PREFIX/a/b`, rather than `GO_PREFIX/a/b/go_default_library`. -* For making Bazel work with Go, we will have a tool called `glaze`, which analyzes the Go source files in a directory, and emits a BUILD file to match. Glaze must be run by hand (or, as an editor hook) when modifying Go code. -* When Glaze encounters an import line `GO_PREFIX/a/b` for which `a/b/` is a directory, it will write a dependency on `//a/b:go_default_library`. -* If a target has a dependency that contains a `vendor` directory component, the compiler will be invoked with a corresponding `-importmap` option, eg. a dependency on `x/y/vendor/domain/p/q:target` will yield `-importmap=domain/p/q/target=GO_PREFIX/x/y/vendor/domain/p/q/target`. - * Multiple dependencies that map to the same importmap key is an analysis-time error. -* When Glaze encounters an import line that can be satisfied from a `vendor/` directory, as specified in the [Go vendoring decision](https://docs.google.com/document/d/1Bz5-UB7g2uPBdOx-rw5t9MxJwkfpx90cqG9AFL0JAYo/), it will emit the full target name of the vendored library. - -Caveats -------- - -Is not fully compatible with the `go` tool: -* `go` still cannot handle generated source code (ie. protocol buffers) -* the workspace will need to be in a directory called `src` for `go` to work with it (possibly through a symlink) -* Does not address compatibility with `go generate`: - * Bazel puts sources and artifacts in different directories, so `go` tooling does not work out of the box if only parts of a go library are generated. - * We could export the generated sources as some sort of tree with `//go:generate` lines in the source, but the command line will not run if the generator was built by Bazel too. - * We could import generated sources by extracting `//go:generate` lines. Since the lines do not declare the sources of the invoked tooling, this will be hard to automatically get right, though. -* The `GO_PREFIX` that `WORKSPACE` sets is similar to the workspace name (see build encyclopedia), but it should only affect Go. Since Go prefixes are URLs, they contain dots, so using the `WORKSPACE` name would break Python imports. -* Does not specify how native interoperability (eg. cgo) should work. - -Implementation plan -------------------- - -* Implement `go_prefix` support in `WORKSPACE` -* Reintroduce the Skylark Go rules, but supporting `go_default_library` and `go_prefix`. -* Ship them in Bazel; this yields bare bones rules. -* Open-source the `BUILD` file formatter, and use it as basis to create `glaze`. -* Open-source compiler glue program and use it in the Skylark rules. This will yields conformance with //+ build tags, and other build system directives embedded in source code. -* Consider cleaning and opening up internal rules. |