diff options
Diffstat (limited to 'pw_assert/docs.rst')
| -rw-r--r-- | pw_assert/docs.rst | 36 |
1 files changed, 25 insertions, 11 deletions
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst index 6a6576ee5..a66c3f7e1 100644 --- a/pw_assert/docs.rst +++ b/pw_assert/docs.rst @@ -472,20 +472,26 @@ The ``PW_ASSERT`` API ultimately calls the C function ``pw_assert_HandleFailure()``, which must be provided by the ``pw_assert`` backend. +.. _module-pw_assert-circular-deps: + Avoiding circular dependencies with ``PW_ASSERT`` ------------------------------------------------- Because asserts are so widely used, including in low-level libraries, it is -common for the ``pw_assert`` backend to cause circular dependencies. These can -be avoided by only using the ``PW_ASSERT`` macro and depending directly on the -library that provides it, rather than the whole ``pw_assert`` module. The -``pw_assert`` backend, which defines ``pw_assert_HandleFailure()``, will need to -be linked in elsewhere in the build, so only depend directly on the -``pw_assert`` build target when necessary. - -In GN, depend on ``"$dir_pw_assert:assert"`` rather than on ``dir_pw_assert`` to -access only ``PW_ASSERT`` without risking circular dependencies. The -``pw_assert_HandleFailure()`` function is provided by the -``$dir_pw_assert:pw_assert`` or ``"$dir_pw_assert:check"`` target. +common for the ``pw_assert`` backend to cause circular dependencies. Because of +this, assert backends may avoid declaring explicit dependencies, instead relying +on include paths to access header files. + +In GN, the ``pw_assert`` backend's true dependencies are made available through +the ``$dir_pw_assert:deps`` group. When ``pw_assert_BACKEND`` is set, +``$dir_pw_assert:deps`` must be listed in the ``pw_build_LINK_DEPS`` variable. +See :ref:`module-pw_build-link-deps`. + +If necessary, ``pw_assert`` backends can access dependencies from include paths +rather than GN ``deps``. In this case, the may disable GN header checking with +``check_includes = false``. The true build dependencies must be listed in a +``deps`` group, which the ``pw_assert`` facade depends on. The ``deps`` group +may be empty if the backend can use its dependencies directly without causing +circular dependencies. .. _module-pw_assert-backend_api: @@ -574,6 +580,14 @@ header, but instead is in a ``.cc`` file. file, expression, or other rich assert information. Backends should do something reasonable in this case; typically, capturing the stack is useful. +Backend build targets +--------------------- +In GN, the backend must provide a ``deps`` build target in the same directory as +the backend target. The ``deps`` target contains the backend's dependencies that +could result in a dependency cycle. In the simplest case, it can be an empty +group. Circular dependencies are a common problem with ``pw_assert`` because it +is so widely used. See :ref:`module-pw_assert-circular-deps`. + -------------------------- Frequently asked questions -------------------------- |