docs: document additional flags needed for macOS (#1005)

gRPC requires an additional flag to compile with Bazel. I chose to
both document this *and* set it on our .bazelrc. Note that users will
need to set this flag on their own .bazelrc.

Author: coryan

.bazelrc

@@ -12,6 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# To workaround a bug in Bazel [1], gRPC requires this flag on macOS builds,
+# and there is (AFAIK) no way to "inherit" their definitions.
+#   [1]: https://github.com/bazelbuild/bazel/issues/4341
+build --copt=-DGRPC_BAZEL_BUILD
+
 # Clang Sanitizers, use with (for example):
 #
 # --client_env=CXX=clang++ --client_env=CC=clang --config asan

INSTALL.md

@@ -108,6 +108,19 @@ cc_binary(
 )
 ```
 
+### Building with Bazel on macOS
+
+To workaround a bug in Bazel ([bazelbuild/bazel#4341][bazel-bug-4341-link]) gRPC needs a
+command-line flag when compiled using Bazel on macOS:
+
+[bazel-bug-4341]: https://github.com/bazelbuild/bazel/issues/4341
+
+```bash
+bazel build --copt=-DGRPC_BAZEL_BUILD ...
+```
+
+Consider adding this option to your project's `.bazelrc` file.
+
 ## Required Libraries
 
 `google-cloud-cpp` directly depends on the following libraries:

ci/test-readme/generate-install.sh

@@ -128,6 +128,19 @@ cc_binary(
 )
 ```
 
+### Building with Bazel on macOS
+
+To workaround a bug in Bazel ([bazelbuild/bazel#4341][bazel-bug-4341-link]) gRPC needs a
+command-line flag when compiled using Bazel on macOS:
+
+[bazel-bug-4341]: https://github.com/bazelbuild/bazel/issues/4341
+
+```bash
+bazel build --copt=-DGRPC_BAZEL_BUILD ...
+```
+
+Consider adding this option to your project's `.bazelrc` file.
+
 ## Required Libraries
 
 `google-cloud-cpp` directly depends on the following libraries: