bazel: document some tips for debug and build performance (#415).

bazel/README.md

@@ -63,6 +63,35 @@ the units tests in
 bazel test //test/common/http:async_client_impl_test
 ```
 
+To observe more verbose test output:
+
+```
+bazel test --test_output=streamed //test/common/http:async_client_impl_test
+```
+
+It's also possible to pass into an Envoy test additional command-line args via `--test_arg`. For
+example, for extremely verbose test debugging:
+
+```
+bazel test --test_output=streamed //test/common/http:async_client_impl_test --test_arg="-l trace"
+```
+
+Bazel will by default cache successful test results. To force it to rerun tests:
+
+
+```
+bazel test //test/common/http:async_client_impl_test --cache_test_results=no
+```
+
+Bazel will by default run all tests inside a sandbox, which disallows access to the
+local filesystem. If you need to break out of the sandbox (for example to run under a
+local script or tool with [`--run_under`](https://bazel.build/versions/master/docs/bazel-user-manual.html#flag--run_under)),
+you can run the test with `--strategy=TestRunner=standalone`, e.g.:
+
+```
+bazel test //test/common/http:async_client_impl_test --strategy=TestRunner=standalone --run_under=/some/path/foobar.sh
+```
+
 # Running a single Bazel test under GDB
 
 ```
@@ -127,6 +156,43 @@ test/run_envoy_bazel_coverage.sh
 The summary results are printed to the standard output and the full coverage
 report is available in `generated/coverage/coverage.html`.
 
+# Cleaning the build and test artifacts
+
+`bazel clean` will nuke all the build/test artifacts from the Bazel cache for
+Envoy proper. To remove the artifacts for the external dependencies run
+`bazel clean --expunge`.
+
 # Adding or maintaining Envoy build rules
 
 See the [developer guide for writing Envoy Bazel rules](DEVELOPER.md).
+
+# Bazel performance on (virtual) machines with low resources
+
+If the (virtual) machine that is performing the build is low on memory or CPU
+resources, you can override Bazel's default job parallelism determination with
+`--jobs=N` to restrict the build to at most `N` simultaneous jobs, e.g.:
+
+```
+bazel build --jobs=2 //source/...
+```
+
+# Debugging the Bazel build
+
+When trying to understand what Bazel is doing, the `-s` and `--explain` options
+are useful. To have Bazel provide verbose output on which commands it is executing:
+
+```
+bazel build -s //source/...
+```
+
+To have Bazel emit to a text file the rationale for rebuilding a target:
+
+```
+bazel build --explain=file.txt //source/...
+```
+
+To get more verbose explanations:
+
+```
+bazel build --explain=file.txt --verbose_explanations //source/...
+```