Repository: bazelbuild/bazel
Issue: Outdated docs for configuring C++ toolchains
Labels: P1
team-Rules-CPP

### Description of the problem / feature request:

`emscripten` could not be configured as it's described in tutorial in docs: 

* https://docs.bazel.build/versions/master/tutorial/cc-toolchain-config.html

```
example@docker:~/examples/cpp-tutorial/stage1$ bazel build --config=asmjs //main:helloworld.js
INFO: SHA256 (https://github.com/kripken/emscripten/archive/1.37.22.tar.gz) = 433dedb63ba423cf04bbc9802b49fa842bd479bad31a339db9506614e92334c7
INFO: SHA256 (https://s3.amazonaws.com/mozilla-games/emscripten/packages/llvm/tag/linux_64bit/emscripten-llvm-e1.37.22.tar.gz) = fd457ebfbe5a727058880ff55cdabf7f1b7809aea07957d2cc854e7de3001ef3
INFO: Call stack for the definition of repository 'emscripten_toolchain' which is a http_archive (rule definition at /home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/http.bzl:237:16):
 - /home/example/examples/cpp-tutorial/stage1/WORKSPACE:3:1
ERROR: An error occurred during the fetch of repository 'emscripten_toolchain':
   Traceback (most recent call last):
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/http.bzl", line 57
		workspace_and_buildfile(ctx)
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/utils.bzl", line 61, in workspace_and_buildfile
		ctx.symlink(ctx.attr.build_file, "BUILD.bazel")
Unable to load package for //:emscripten-toolchain.BUILD: BUILD file not found in any of the following directories.
 - /home/example/examples/cpp-tutorial/stage1
ERROR: /home/example/examples/cpp-tutorial/stage1/toolchain/BUILD:14:1: no such package '@emscripten_toolchain//': Traceback (most recent call last):
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/http.bzl", line 57
		workspace_and_buildfile(ctx)
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/utils.bzl", line 61, in workspace_and_buildfile
		ctx.symlink(ctx.attr.build_file, "BUILD.bazel")
Unable to load package for //:emscripten-toolchain.BUILD: BUILD file not found in any of the following directories.
 - /home/example/examples/cpp-tutorial/stage1 and referenced by '//toolchain:all'
ERROR: Analysis of target '//main:helloworld.js' failed; build aborted: no such package '@emscripten_toolchain//': Traceback (most recent call last):
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/http.bzl", line 57
		workspace_and_buildfile(ctx)
	File "/home/example/.cache/bazel/_bazel_example/f398d85a4189d668d83b95c96638982b/external/bazel_tools/tools/build_defs/repo/utils.bzl", line 61, in workspace_and_buildfile
		ctx.symlink(ctx.attr.build_file, "BUILD.bazel")
Unable to load package for //:emscripten-toolchain.BUILD: BUILD file not found in any of the following directories.
 - /home/example/examples/cpp-tutorial/stage1
INFO: Elapsed time: 109.938s
INFO: 0 processes.
FAILED: Build did NOT complete successfully (0 packages loaded, 0 targets configured)
    Fetching @emscripten_clang; fetching 109s
```

Both `*.BUILD` files were created in WORKSPACE directory root:

```
$ tree
.
├── emscripten-clang.BUILD
├── emscripten-toolchain.BUILD
├── main
│   ├── BUILD
│   └── hello-world.cc
├── README.md
├── toolchain
│   ├── BUILD
│   ├── cc_toolchain_config.bzl
│   └── emcc.sh
└── WORKSPACE
```
```
example@docker:~/examples/cpp-tutorial/stage1$ cat emscripten-toolchain.BUILD
package(default_visibility = ['//visibility:public'])

filegroup(
  name = "all",
  srcs = glob(["**/*"]),
)
```
```
example@docker:~/examples/cpp-tutorial/stage1$ cat emscripten-toolchain.BUILD
package(default_visibility = ['//visibility:public'])

filegroup(
  name = "all",
  srcs = glob(["**/*"]),
)
```
### What operating system are you running Bazel on?

`Ubuntu 12.04.5 LTS`

### What's the output of `bazel info release`?

`release 0.27.1`

### What's the output of `git remote get-url origin ; git rev-parse master ; git rev-parse HEAD` ?

```
https://github.com/bazelbuild/examples.git
5d8c8961a2516ebf875787df35e98cadd08d43dc
5d8c8961a2516ebf875787df35e98cadd08d43dc
```

### Any other information, logs, or outputs that you want to share?

I updated couple places in docs so far in this PR:

* https://github.com/bazelbuild/bazel/pull/8841

Issue comments:
I used `build_file_content` as workaround instead.

Pull request review comments:

Patch that resolved the issue:
diff --git a/site/docs/tutorial/cc-toolchain-config.md b/site/docs/tutorial/cc-toolchain-config.md
index c971271a176579..6cebaeba71e276 100644
--- a/site/docs/tutorial/cc-toolchain-config.md
+++ b/site/docs/tutorial/cc-toolchain-config.md
@@ -332,6 +332,13 @@ using an older release of Bazel, look for the "Configuring CROSSTOOL" tutorial.
     In the workspace directory root, create the `emscripten-toolchain.BUILD` and
     `emscripten-clang.BUILD` files that expose these repositories as filegroups
     and establish their visibility across the build.
+    
+    Make sure that in the workspace directory root `BUILD` file is present, if it's
+    missing create it empty:
+    
+    ```
+    touch BUILD
+    ```
 
     First create the `emscripten-toolchain.BUILD` file with the following
     contents:


Test patch: