pw_assert_log/docs.rst

.. _module-pw_assert_log:

=============
pw_assert_log
=============
.. pigweed-module::
   :name: pw_assert_log

-----------------
pw_assert_BACKEND
-----------------
This assert backend implements the ``pw_assert:check`` facade, by routing the
``PW_CHECK()``/``PW_CRASH()`` macros into ``PW_LOG``  with the
``PW_LOG_LEVEL_FATAL`` log level. This is an easy way to tokenize your assert
messages, by using the ``pw_log_tokenized`` log backend for logging, then using
``pw_assert_log`` to route the tokenized messages into the tokenized log
handler.

To use this module:

1. Set your assert backend: ``pw_assert_BACKEND = dir_pw_assert_log``
2. Ensure your logging backend knows how to handle the assert failure flag

``%`` in ``PW_ASSERT`` conditions
=================================
``PW_CHECK`` does not support use of the ``%`` character in conditions. See
:ref:`module-pw_assert-mod` for details. Since the ``pw_assert_log`` backend
uses ``pw_log`` for ``PW_ASSERT``, the ``%`` character also cannot be used in
``PW_ASSERT``.

.. literalinclude:: examples.cc
   :language: cpp
   :start-after: [pw_assert_log-mod-example]
   :end-before: [pw_assert_log-mod-example]

----------------------
pw_assert_LITE_BACKEND
----------------------
This assert backend implements the ``pw_assert:assert`` facade, by routing the
``PW_ASSERT()`` macros into ``PW_LOG`` with the ``PW_LOG_LEVEL_FATAL`` log
level. This is an easy way to forward your asserts to a native macro assert
API if it is already constexpr safe such as on Android.

.. warning::
   When building with Soong (using Android.bp), some Pigweed modules are listing
   `pw_log_null_headers` in their `header_lib` list. This means that the
   `PW_CHECK`, `PW_ASSERT`, and `PW_CRASH` macros that depend on logs are
   ignored. Make sure to use the correct log backend in your final target, such
   as the `pw_log_android` backend which supports crashing on
   `PW_LOG_LEVEL_FATAL`. See
   `b/324266698 <https://issues.pigweed.dev/324266698>`_.