docs: document Bazel integration (#2238)

* docs: document Bazel integration

* fix(docs): avoid pinning current benchmark version

README.md

diff --git a/README.md b/README.md
index b60e2d8..77a2336 100644
--- a/README.md
+++ b/README.md
@@ -273,3 +273,32 @@
 static or shared library output. On Windows, keep this setting consistent with
 the rest of the project and make sure the same runtime library configuration is
 used across the benchmark library and the targets that link it.
+
+### Usage with Bazel
+
+If using Bazel with Bzlmod, add Google Benchmark to your `MODULE.bazel` file:
+
+```starlark
+bazel_dep(name = "google_benchmark", version = "<VERSION>")
+```
+
+Replace `<VERSION>` with the Google Benchmark release version you want to use.
+
+Then link a `cc_binary` or `cc_test` against one of the provided targets:
+
+```starlark
+load("@rules_cc//cc:defs.bzl", "cc_binary")
+
+cc_binary(
+    name = "my_benchmark",
+    srcs = ["my_benchmark.cc"],
+    deps = ["@google_benchmark//:benchmark_main"],
+)
+```
+
+Use `@google_benchmark//:benchmark` when your target defines its own `main`
+function, including through `BENCHMARK_MAIN()`. Use
+`@google_benchmark//:benchmark_main` to use the default Google Benchmark entry
+point.
+
+For WORKSPACE setup and more examples, see [Bazel](docs/bazel.md).

docs/bazel.md

diff --git a/docs/bazel.md b/docs/bazel.md
new file mode 100644
index 0000000..b5217a9
--- /dev/null
+++ b/docs/bazel.md
@@ -0,0 +1,92 @@
+# Bazel
+
+Google Benchmark provides Bazel targets for both the benchmark library and the
+optional default `main` function:
+
+* `@google_benchmark//:benchmark` provides the benchmark library.
+* `@google_benchmark//:benchmark_main` provides the default `main` function and
+  depends on `@google_benchmark//:benchmark`.
+
+Use `@google_benchmark//:benchmark` when the benchmark target defines its own
+`main` function, including through `BENCHMARK_MAIN()`. Use
+`@google_benchmark//:benchmark_main` when the benchmark target should use the
+default Google Benchmark entry point.
+
+## Bzlmod
+
+With Bzlmod enabled, add Google Benchmark to your `MODULE.bazel` file:
+
+```starlark
+bazel_dep(name = "google_benchmark", version = "<VERSION>")
+```
+
+Replace `<VERSION>` with the Google Benchmark release version you want to use.
+
+Then depend on the Bazel target from a `cc_binary` or `cc_test`:
+
+```starlark
+load("@rules_cc//cc:defs.bzl", "cc_binary")
+
+cc_binary(
+    name = "string_benchmark",
+    srcs = ["string_benchmark.cc"],
+    deps = ["@google_benchmark//:benchmark_main"],
+)
+```
+
+The source file should register benchmarks, but it should not call
+`BENCHMARK_MAIN()` when linking against `@google_benchmark//:benchmark_main`:
+
+```c++
+#include <benchmark/benchmark.h>
+#include <string>
+
+static void BM_StringCreation(benchmark::State& state) {
+  for (auto _ : state) {
+    std::string empty_string;
+  }
+}
+BENCHMARK(BM_StringCreation);
+```
+
+Run the benchmark with Bazel:
+
+```bash
+bazel run //:string_benchmark
+```
+
+Pass Google Benchmark flags after Bazel's `--` separator:
+
+```bash
+bazel run //:string_benchmark -- --benchmark_filter=StringCreation
+```
+
+## WORKSPACE
+
+Projects that still use `WORKSPACE` can declare Google Benchmark as an external
+repository and load its dependencies from `bazel/benchmark_deps.bzl`:
+
+```starlark
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "google_benchmark",
+    strip_prefix = "benchmark-<VERSION>",
+    urls = ["https://github.com/google/benchmark/archive/refs/tags/v<VERSION>.tar.gz"],
+    # Add sha256 for reproducible builds.
+)
+
+load("@google_benchmark//:bazel/benchmark_deps.bzl", "benchmark_deps")
+
+benchmark_deps()
+```
+
+Use the same `<VERSION>` value without the leading `v`; the archive URL adds the tag prefix explicitly.
+
+After declaring the repository, use the same target labels shown above:
+`@google_benchmark//:benchmark` or `@google_benchmark//:benchmark_main`.
+
+## Perf Counters
+
+When using Bazel, enable libpfm support by adding `--define pfm=1` to the build
+or run command. See [Perf Counters](perf_counters.md) for more details.

docs/index.md

diff --git a/docs/index.md b/docs/index.md
index 9cada96..af6e88a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,7 @@
 # Benchmark
 
 * [Assembly Tests](AssemblyTests.md)
+* [Bazel](bazel.md)
 * [Dependencies](dependencies.md)
 * [Perf Counters](perf_counters.md)
 * [Platform Specific Build Instructions](platform_specific_build_instructions.md)