bazel: document how to override a dependency (envoyproxy#2818)

* This reverts commit 8a0d833.
* document --override_repository

Signed-off-by: Lizan Zhou <[email protected]>

bazel/EXTERNAL_DEPS.md

@@ -50,5 +50,21 @@ and install dependencies into a shared directory prefix.
 
 # Updating an external dependency version
 
-1. Update the build recipe in [`ci/build_container/build_recipes`](../ci/build_container/build_recipes).
-2. `bazel test //test/...`
+1. If the dependency is a build recipe, update the build recipe in
+[`ci/build_container/build_recipes`](../ci/build_container/build_recipes).
+2. If not, update the corresponding entry in
+[the repository locations file.](https://github.com/envoyproxy/envoy/blob/master/bazel/repository_locations.bzl)
+3. `bazel test //test/...`
+
+# Overriding an external dependency temporarily
+
+An external dependency built by genrule repository or native Bazel could be overridden by
+specifying Bazel option
+[`--override_repository`](https://docs.bazel.build/versions/master/command-line-reference.html)
+to point to a local copy. The option can used multiple times to override multiple dependencies.
+The name of the dependency can be found in
+[the repository locations file.](https://github.com/envoyproxy/envoy/blob/master/bazel/repository_locations.bzl)
+The path of the local copy has to be absolute path.
+
+For example you can point the data plane API to a local copy checked out in home directory and run tests:  
+`bazel test --override_repository="envoy_api={$HOME}/data-plane-api"`

bazel/README.md

@@ -22,10 +22,9 @@ As a developer convenience, a [WORKSPACE](https://github.com/envoyproxy/envoy/bl
 version](https://github.com/envoyproxy/envoy/blob/master/bazel/repositories.bzl) of the various Envoy
 dependencies are provided. These are provided as is, they are only suitable for development and
 testing purposes. The specific versions of the Envoy dependencies used in this build may not be
-up-to-date with the latest security patches. You may override the location and/or version of a dependency
-by modifying the corresponding entry in
-[the repository locations file](https://github.com/envoyproxy/envoy/blob/master/bazel/repository_locations.bzl).
-Overrides can be local or remote. See that file for details.
+up-to-date with the latest security patches. See 
+[this doc](https://github.com/envoyproxy/envoy/blob/master/bazel/EXTERNAL_DEPS.md#updating-an-external-dependency-version)
+for how to update or override dependencies.
 
 1. Install the latest version of [Bazel](https://bazel.build/versions/master/docs/install.html) in your environment.
 2. Install external dependencies libtool, cmake, and realpath libraries separately.

bazel/repositories.bzl

@@ -12,9 +12,7 @@ def _repository_impl(name, **kwargs):
     # `existing_rule_keys` contains the names of repositories that have already
     # been defined in the Bazel workspace. By skipping repos with existing keys,
     # users can override dependency versions by using standard Bazel repository
-    # rules in their WORKSPACE files. Giving a `local_path` in
-    # `repository_locations.bzl` is the easiest way to override a dependency with
-    # a local checkout.
+    # rules in their WORKSPACE files.
     existing_rule_keys = native.existing_rules().keys()
     if name in existing_rule_keys:
         # This repository has already been defined, probably because the user
@@ -30,29 +28,7 @@ def _repository_impl(name, **kwargs):
             "Refusing to depend on Git tag %r for external dependency %r: use 'commit' instead."
             % (location["tag"], name))
 
-    if "local_path" in location:
-        # local_repository() does not use any parameter besides local_path.
-        # If any are present, warn that they're ignored.
-        if len(location) > 1:
-            other_keys = []
-            for k in location:
-                if k != "local_path":
-                    other_keys.append(k)
-
-            print(("Warning: overriding external dependency %r with repository at local path %r. " +
-                  "The following location specifiers will be ignored: %r") % \
-                  (name, location["local_path"], other_keys))
-
-        # Local repository at given path. Add a BUILD file if requested.
-        if "build_file" in kwargs:
-            native.new_local_repository(
-                name = name,
-                path = location["local_path"])
-        else:
-            native.local_repository(
-                name = name,
-                path = location["local_path"])
-    elif "commit" in location:
+    if "commit" in location:
         # Git repository at given commit ID. Add a BUILD file if requested.
         if "build_file" in kwargs:
             new_git_repository(

bazel/repository_locations.bzl

@@ -1,7 +1,3 @@
-# Use a "local_path" key to build against a local checkout of a repository.
-# The path must be absolute. Other keys are ignored when using a local repository.
-# The current working tree at the given path will be used.
-# DO NOT PUSH a "local_path" override upstream.
 REPOSITORY_LOCATIONS = dict(
     boringssl = dict(
         # Use commits from branch "chromium-stable-with-bazel"

support/hooks/pre-push

@@ -47,16 +47,6 @@ do
       exit 1
     fi
 
-    # Check if any commits look like they (likely accidentally) included a
-    # local repository entry in repository_locations.bzl
-    LOCAL_PATH_DEPS=$(git log -p --pickaxe-regex -S "local_path" "$RANGE" -- "bazel/repository_locations.bzl")
-    if [ -n "$LOCAL_PATH_DEPS" ]
-    then
-      echo >&2 "ERROR: The following commit(s) added local dependencies to bazel/repository_locations.bzl"
-      echo >&2 "$LOCAL_PATH_DEPS"
-      exit 1
-    fi
-
     # NOTE: The `tools` directory will be the same relative to the support
     # directory, independent of whether we're in a submodule, so no need to use
     # our `relpath` helper.