From b8d1cd064d4440e216f62802ab2378eb0c3eb269 Mon Sep 17 00:00:00 2001
From: Kayce Basques <kayce@google.com>
Date: Sat, 7 Dec 2024 03:48:56 +0000
Subject: [PATCH] pw_build: Document pw_cc_binary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: Id41b1e09d4f54d007c75744f9bd95130437414b4
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/252052
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Commit-Queue: Kayce Basques <kayce@google.com>
Reviewed-by: Ted Pudlik <tpudlik@google.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
---
 pw_build/bazel.rst | 53 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/pw_build/bazel.rst b/pw_build/bazel.rst
index e1d75bdb5c..54b17c8095 100644
--- a/pw_build/bazel.rst
+++ b/pw_build/bazel.rst
@@ -12,10 +12,17 @@ microcontrollers.
 
 Wrapper rules
 -------------
-The common configuration for Bazel for all modules is in the ``pigweed.bzl``
-file. The built-in Bazel rules ``cc_binary``, ``cc_test``, ``py_binary`` and
-``py_test`` are wrapped with ``pw_cc_binary``, ``pw_cc_test`` ``pw_py_binary``
-and ``pw_py_test``, respectively.
+.. _pigweed.bzl: https://cs.opensource.google/pigweed/pigweed/+/main:pw_build/pigweed.bzl
+
+The built-in Bazel rules ``cc_binary``, ``cc_test``, ``py_binary``, and
+``py_test`` are wrapped with :ref:`module-pw_build-bazel-pw_cc_binary`,
+``pw_cc_test``, ``pw_py_binary``, and ``pw_py_test``, respectively.
+To access a wrapper, load its individual ``.bzl`` file. For example, to
+access ``pw_cc_binary``:
+
+.. code-block:: python
+
+   load("@pigweed//pw_build:pw_cc_binary.bzl", "pw_cc_binary")
 
 .. _module-pw_build-bazel-pw_linker_script:
 
@@ -251,6 +258,44 @@ Example
 
    }  // namespace my::stuff
 
+.. _module-pw_build-bazel-pw_cc_binary:
+
+pw_cc_binary
+------------
+.. _cc_binary: https://bazel.build/reference/be/c-cpp#cc_binary
+.. _//pw_build/pw_cc_binary.bzl: https://cs.opensource.google/pigweed/pigweed/+/main:pw_build/pw_cc_binary.bzl
+
+``pw_cc_binary`` is a wrapper of `cc_binary`_. It's implemented at
+`//pw_build/pw_cc_binary.bzl`_. Usage of this wrapper is optional;
+downstream Pigweed projects can instead use ``cc_binary`` if preferred.
+
+Basic usage:
+
+.. code-block:: python
+
+   load("@pigweed//pw_build:pw_cc_binary.bzl", "pw_cc_binary")
+
+   pw_cc_binary(
+       name = "…",
+       srcs = ["…"],
+       deps = [
+           "…",
+       ],
+   )
+
+Pros of using ``pw_cc_binary``:
+
+* It simplifies :ref:`link-time dependency
+  <docs-build_system-bazel_link-extra-lib>`. Projects using ``cc_binary``
+  must set up (and document) link-time dependency themselves.
+
+Cons of using ``pw_cc_binary``:
+
+.. _magical: https://en.wikipedia.org/wiki/Magic_(programming)
+
+* It makes the configuration of :ref:`module-pw_log` and
+  :ref:`module-pw_assert` a bit more `magical`_.
+
 .. _module-pw_build-bazel-pw_cc_binary_with_map:
 
 pw_cc_binary_with_map