Add documentation for Skylark Go rules.

--
MOS_MIGRATED_REVID=86946740

4 files changed, 107 insertions, 10 deletions

diff --git a/base_workspace/examples/go/BUILD b/base_workspace/examples/go/BUILD
index b3939e2244..5e6b7806d4 100644
--- a/base_workspace/examples/go/BUILD
+++ b/base_workspace/examples/go/BUILD
@@ -1,5 +1,4 @@
-# Go rules expect a symlink to the Go installation, e.g.
-#   ln -s $(go env GOROOT) tools/go/go_root
+# See README.md for instructions on how to use these rules.
 
 package(default_visibility = ["//visibility:public"])
 
diff --git a/base_workspace/examples/go/README.md b/base_workspace/examples/go/README.md
new file mode 100644
index 0000000000..73d73de70b
--- /dev/null
+++ b/base_workspace/examples/go/README.md
@@ -0,0 +1,100 @@
+
+Go rules
+--------
+
+The files here demonstrate how to use the supplied rules for Go.
+
+They do support:
+
+  * libraries
+  * binaries
+  * tests
+
+They currently do not support:
+
+  * coverage
+  * race detector
+  * multiple target configurations
+  * //+build tags
+  * C/C++ interoperation (cgo, swig etc.)
+
+
+Testing
+-------
+
+Setup a symlink to the Go installation you wish to use,
+
+    ln -s /usr/lib/golang/ tools/go/go_root
+
+or
+
+    ln -s $(go env GOROOT) tools/go/go_root
+
+To build something, run
+
+    bazel build examples/go/...
+
+To run a test, run
+
+	bazel test --test_arg=--test.v examples/go/lib1:lib1_test
+
+
+Writing BUILD rules
+-------------------
+
+In the bazel model of compiling Go, each directory can hold multiple
+packages, rather than just one in the standard "go" tool. Suppose you
+have
+
+    dir/f.go:
+
+    package p
+    func F() {}
+
+then in the BUILD file could say
+
+    go_library(
+      name = "q",
+      srcs = ["f.go"])
+
+and you import it with its Bazel name,
+
+    import "dir/p/q"
+
+this add the declared package name as namespace, i.e., it is
+equivalent to
+
+    import p "dir/p/q"
+
+so you use it as follows
+
+    import "dir/p/q"
+    main() {
+      p.F()
+    }
+
+
+
+FAQ
+---
+
+
+# Why does this not follow the external Go conventions?
+
+These rules were inspired on Google's internal Go rules, which work
+like this. They make more sense for Bazel, because directories in
+Bazel do not correspond to single rules.
+
+
+# Do I have to specify dependencies twice?
+
+Yes, once in the BUILD file, once in the source file. Bazel does not
+examine file contents, so it cannot infer the dependencies.  It is
+possible to generate the BUILD file from the Go sources through a
+separate program, though.
+
+
+Disclaimer
+----------
+
+These rules are not supported by Google's Go team.
diff --git a/base_workspace/examples/go/fib.go b/base_workspace/examples/go/fib.go
index 426569d2a1..43d8a499ba 100644
--- a/base_workspace/examples/go/fib.go
+++ b/base_workspace/examples/go/fib.go
@@ -3,7 +3,6 @@ package main
 import (
 	"fmt"
 
-	// TODO(bazel-team): remap compiler inputs so this is "go/lib1"
 	"examples/go/lib1/lib1"
 )
 
diff --git a/tools/build_rules/go_rules.bzl b/tools/build_rules/go_rules.bzl
index ae218ccd39..8e6d561d56 100644
--- a/tools/build_rules/go_rules.bzl
+++ b/tools/build_rules/go_rules.bzl
@@ -16,9 +16,6 @@
 
 Several issues:
 
-- For "a/b/c.go", the go tool creates library "a/b.a" with import path
-"a/b".  We can probably simulate this with symlink trees.
-
 - Dependencies are not enforced; a symlink tree might help here too.
 
 - Hardcoded to 6g from the GC suite. We should be able to support GCC
@@ -27,11 +24,12 @@ Several issues:
 - It would be nice to be able to create a full-fledged Go
   configuration in Skylark.
 
-- It would be nice to support zero-configuration
-go_library()/go_binary()/go_test() rules:
+- It would be nice to support zero-configuration rules, similar to
+  vanilla "go", with one package per directory.  This would requiere
+  macro support though, to use glob()
 
-  * name defaults to basename of directory
-  * srcs defaults to *.go
+  * For "a/b/c.go", the go tool creates library "a/b.a" with import path
+    "a/b".  We can probably simulate this with symlink trees.
 
 - does not support checked in compilers.
 
@@ -40,6 +38,7 @@ go_library()/go_binary()/go_test() rules:
 - deps must be populated by hand.
 
 - go_test must have both test and non-test files in srcs.
+
 """
 
 go_filetype = FileType([".go"])