From 61aadc49224ccd7d5d700de76ae221953cacb86b Mon Sep 17 00:00:00 2001 From: Harvey Tuch Date: Tue, 25 Apr 2017 08:21:34 -0400 Subject: [PATCH 1/4] bazel: document some tips for debug and build performance. --- bazel/README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/bazel/README.md b/bazel/README.md index 0c70aa7444443..82f2043ab0869 100644 --- a/bazel/README.md +++ b/bazel/README.md @@ -130,3 +130,34 @@ report is available in `generated/coverage/coverage.html`. # 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/... +``` From ff39288dc51d01f0bec1d909019e5624e80386bd Mon Sep 17 00:00:00 2001 From: Harvey Tuch Date: Tue, 25 Apr 2017 15:07:17 -0400 Subject: [PATCH 2/4] Document --test_output and --test_arg. --- bazel/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/bazel/README.md b/bazel/README.md index 82f2043ab0869..c4c0fdeddbae8 100644 --- a/bazel/README.md +++ b/bazel/README.md @@ -63,6 +63,26 @@ 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 +``` + # Running a single Bazel test under GDB ``` From 1f61d16332a81d809127a42c9e135c74fdfc2eac Mon Sep 17 00:00:00 2001 From: Harvey Tuch Date: Tue, 25 Apr 2017 15:20:11 -0400 Subject: [PATCH 3/4] Sandbox and clean. --- bazel/README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/bazel/README.md b/bazel/README.md index c4c0fdeddbae8..beb1cf3662cd2 100644 --- a/bazel/README.md +++ b/bazel/README.md @@ -83,6 +83,15 @@ 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 ``` +By default, Bazel runs all tests inside a sandbox, which disallows access to the +filesystem. If you need to break out of the sandbox (for example to run under a +local script or tool with `--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 ``` @@ -147,6 +156,12 @@ 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). From 888258571cb305d12b6907ef756d2630c90f9799 Mon Sep 17 00:00:00 2001 From: Harvey Tuch Date: Tue, 25 Apr 2017 15:24:17 -0400 Subject: [PATCH 4/4] --run_under link and typos. --- bazel/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bazel/README.md b/bazel/README.md index beb1cf3662cd2..8544eda4d1282 100644 --- a/bazel/README.md +++ b/bazel/README.md @@ -83,10 +83,10 @@ 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 ``` -By default, Bazel runs all tests inside a sandbox, which disallows access to the -filesystem. If you need to break out of the sandbox (for example to run under a -local script or tool with `--run_under`, you can run the test with `--strategy=TestRunner=standalone`, -e.g.: +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