message: bazel: docs for cache setup
  This is a kind of hacky solution to setup efficient cache across different compilation mode and/or different working trees that I have been using for weeks.
  Risk Level: Low (docs only)
  Testing: N/A
diff: @@ -422,3 +422,67 @@ with any tools (e.g. clang-tidy) compatible with the format.
  The compilation database could also be used to setup editors with cross reference, code completion.
  For example, you can use [You Complete Me](https://valloric.github.io/YouCompleteMe/) or
  [cquery](https://github.com/cquery-project/cquery) with supported editors.
  +
  +# Advanced caching setup
  +
  +Setting up an HTTP cache for Bazel output helps optimize Bazel performance and resource usage when
  +using multiple compilation modes or multiple trees.
  +
  +## Setup common `envoy_deps`
  +
  +This step sets up the common `envoy_deps` allowing HTTP or disk cache (described below) to work
  +across working trees in different paths. Also it allows new working trees to skip dependency
  +compilation. The drawback is that the cached dependencies won't be updated automatically, so make
  +sure all your working trees have same (or compatible) dependencies, and run this step periodically
  +to update them.
  +
  +Make sure you don't have `--override_repository` in your `.bazelrc` when you run this step.
  +
  +```
  +bazel fetch //test/...
  +cp -LR $(bazel info output_base)/external/envoy_deps ${HOME}/envoy_deps_cache
  +```
  +
  +Adding the following parameter to Bazel everytime or persist them in `.bazelrc`, note you will need to expand
  +the environment variables for `.bazelrc`.
  +
  +```
  +--override_repository=envoy_deps=${HOME}/envoy_deps_cache
  +```
  +
  +## Setup local cache
  +
  +You may use any [Remote Caching](https://docs.bazel.build/versions/master/remote-caching.html) backend
  +as an alternative to this.
  +
  +This requires Go 1.11+, follow the [instructions](https://golang.org/doc/install#install) to install
  +if you don't have one.
  +
  +```
  +go run github.com/buchgr/bazel-remote --dir ${HOME}/bazel_cache --host 127.0.0.1 --port 28080 --max_size 64
  +```
  +
  +See [Bazel remote cache](github.com/buchgr/bazel-remote) for more information on the parameters.
  +The command above will setup a maximum 64 GiB cache at `~/bazel_cache` on port 28080. You might
  +want to setup a larger cache if you run ASAN builds.
  +
  +NOTE: Using docker to run remote cache server described in remote cache docs will likely have
  +slower cache performance on macOS due to slow disk performance for Docker on Mac.
  +
  +Adding the following parameter to Bazel everytime or persist them in `.bazelrc`.
  +
  +```
  +--remote_http_cache=http://127.0.0.1:28080/
  +```
  +
  +## Restrict environment variables
  +
  +You might need the following parameters for Bazel or persist in `.bazelrc` as well to make cache
  +more efficient. This will let Bazel use an environment with a static value for _PATH_ and does
  +not inherit _LD_LIBRARY_PATH_ or _TMPDIR_. See
  +[Bazel Command-Line References](https://docs.bazel.build/versions/master/command-line-reference.html#flag--experimental_strict_action_env)
  +for more information.
  +
  +```
  +--experimental_strict_action_env
  +```
  