rm crosstool (#3986)

**What type of PR is this?**

Documentation

**What does this PR do? Why is it needed?**

Crosstool is the old way in Bazel to define a C/C++ toolchain.
It has been deprecated and replaced with the new toolchain + platforms
auto resolve system in recent years.

The current docs in rules_go are out-of-date with a huge disclaimer up
top.
Several links still point to the old Wiki page which has already been
moved to ./docs/ dir.

This PR does 2 things:

1. Rename `crosstool` attribute in Go Context in starlark to
`cc_toolchain_files`.
This new name better communicates the actual usage of the attribute,
which is to propagate all
CC toolchain files to Go actions.

2. Remove `go/crosstool.rst` doc entirely and update out-of-date
crosstool references to point to
the new platforms and toolchains doc.

**Which issues(s) does this PR fix?**

**Other notes for review**

WORKSPACE

@@ -83,7 +83,7 @@ http_archive(
 )
 
 # For manual testing against an LLVM toolchain.
-# Use --crosstool_top=@llvm_toolchain//:toolchain
+# Use --extra_toolchains=@llvm_toolchain//:cc-toolchain-linux,@llvm_toolchain//:cc-toolchain-darwin
 http_archive(
     name = "com_grail_bazel_toolchain",
     sha256 = "fb762268ca70ced1a0f65d24f92cd881098afd34990ae5767df0ab325217620e",

docs/go/core/cross_compilation.md

@@ -21,9 +21,7 @@ which disables cgo; cgo files will not be compiled, and C/C++ dependencies will
 not be compiled or linked.
 
 Cross-compiling cgo code is possible, but not fully supported. You will need to
-[write a CROSSTOOL file] that describes your C/C++ toolchain. You'll need to
-ensure it works by building `cc_binary` and `cc_library` targets with the
-`--cpu` command line flag set. Then, to build a mixed Go / C / C++ project,
-add `pure = "off"` to your `go_binary` target and run Bazel with `--cpu`
-and `--platforms`.
-
+[define and register a C/C++ toolchain and platforms]. You'll need to ensure it
+works by building `cc_binary` and `cc_library` targets with the `--platforms`
+command line flag set. Then, to build a mixed Go / C / C++ project, add
+`pure = "off"` to your `go_binary` target and run Bazel with `--platforms`.

docs/go/core/rules.bzl

@@ -25,7 +25,7 @@
   [test_filter]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_filter
   [test_env]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_env
   [test_runner_fail_fast]: https://docs.bazel.build/versions/master/command-line-reference.html#flag--test_runner_fail_fast
-  [write a CROSSTOOL file]: https://github.com/bazelbuild/bazel/wiki/Yet-Another-CROSSTOOL-Writing-Tutorial
+  [define and register a C/C++ toolchain and platforms]: https://bazel.build/extending/toolchains#toolchain-definitions
   [bazel]: https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel?tab=doc
   [go_library]: #go_library
   [go_binary]: #go_binary
@@ -72,7 +72,7 @@ sufficient to match the capabilities of the normal go tools.
 - [test_filter]
 - [test_env]
 - [test_runner_fail_fast]
-- [write a CROSSTOOL file]
+- [define and register a C/C++ toolchain and platforms]
 - [bazel]
 
 

docs/go/core/rules.md

@@ -27,7 +27,7 @@
   [test_filter]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_filter
   [test_env]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_env
   [test_runner_fail_fast]: https://docs.bazel.build/versions/master/command-line-reference.html#flag--test_runner_fail_fast
-  [write a CROSSTOOL file]: https://github.com/bazelbuild/bazel/wiki/Yet-Another-CROSSTOOL-Writing-Tutorial
+  [define and register a C/C++ toolchain and platforms]: https://bazel.build/extending/toolchains#toolchain-definitions
   [bazel]: https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel?tab=doc
   [go_library]: #go_library
   [go_binary]: #go_binary
@@ -74,7 +74,7 @@ sufficient to match the capabilities of the normal go tools.
 - [test_filter]
 - [test_env]
 - [test_runner_fail_fast]
-- [write a CROSSTOOL file]
+- [define and register a C/C++ toolchain and platforms]
 - [bazel]
 
 

go/core.rst

@@ -27,7 +27,7 @@ Core Go rules
 .. _test_filter: https://docs.bazel.build/versions/master/user-manual.html#flag--test_filter
 .. _test_env: https://docs.bazel.build/versions/master/user-manual.html#flag--test_env
 .. _test_runner_fail_fast: https://docs.bazel.build/versions/master/command-line-reference.html#flag--test_runner_fail_fast
-.. _write a CROSSTOOL file: https://github.com/bazelbuild/bazel/wiki/Yet-Another-CROSSTOOL-Writing-Tutorial
+.. _define and register a C/C++ toolchain and platforms: https://bazel.build/extending/toolchains#toolchain-definitions
 .. _bazel: https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel?tab=doc
 .. _introduction: /docs/go/core/rules.md#introduction
 .. _rules: /docs/go/core/rules.md#rules