pw_assert: Rename light GN target and test
- Rename pw_assert:light to pw_assert:assert.
- Move CHECK functionality to its own source set.
Change-Id: I8caa0f69465e1bb9effa15d914252f4781e35e7e
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/43100
Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Ewout van Bekkum <ewout@google.com>
diff --git a/pw_assert/BUILD b/pw_assert/BUILD
index 09a5929..d5af164 100644
--- a/pw_assert/BUILD
+++ b/pw_assert/BUILD
@@ -61,8 +61,8 @@
name = "assert_facade_test",
srcs = [
"assert_facade_test.cc",
+ "assert_test.cc",
"fake_backend.cc",
- "light_test.cc",
"public/pw_assert/internal/assert_impl.h",
"pw_assert_test/fake_backend.h",
],
diff --git a/pw_assert/BUILD.gn b/pw_assert/BUILD.gn
index 40b1635..2b78c00 100644
--- a/pw_assert/BUILD.gn
+++ b/pw_assert/BUILD.gn
@@ -1,4 +1,4 @@
-# Copyright 2020 The Pigweed Authors
+# Copyright 2021 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
@@ -23,40 +23,61 @@
pw_assert_BACKEND = ""
}
-config("default_config") {
+config("public_include_path") {
include_dirs = [ "public" ]
+ visibility = [ ":*" ]
}
-pw_facade("pw_assert") {
+# Depending on dir_pw_assert provides both assert and check.
+group("pw_assert") {
+ public_deps = [
+ ":assert",
+ ":check",
+ ]
+}
+
+# Wrap :pw_assert with facade-style targets, so it can be used as if it were
+# created with pw_facade.
+group("facade") {
+ public_deps = [
+ ":assert",
+ ":check.facade",
+ ]
+}
+
+group("pw_assert.facade") {
+ public_deps = [ ":facade" ]
+}
+
+# Provides the rich PW_CHECK macros.
+pw_facade("check") {
backend = pw_assert_BACKEND
- public_configs = [ ":default_config" ]
+ public_configs = [ ":public_include_path" ]
public = [
"public/pw_assert/check.h",
"public/pw_assert/internal/check_impl.h",
+ "public/pw_assert/options.h",
"public/pw_assert/short.h",
]
- public_deps = [
- dir_pw_preprocessor,
-
- # Also expose assert.h to all users of pw_assert.
- ":light",
- ]
+ public_deps = [ dir_pw_preprocessor ]
}
-# Provide a way include "pw_assert/assert.h" without depending on the full
-# assert facade. This enables relying on light asserts from low-level headers
-# like polyfill or span that might trigger circular includes due to the
-# backend.
+# Provide "pw_assert/assert.h" in its own source set, so it can be used without
+# depending on pw_assert_BACKEND. This makes it possible to use PW_ASSERT in
+# situations that might result in circular dependencies, such as in low-level
+# headers like polyfill or span. See the docs for more discussion around where
+# to use which assert headers.
#
-# See the docs for more discussion around where to use which assert system.
-pw_source_set("light") {
- public_configs = [ ":default_config" ]
+# The implementation function pw_assert_HandleFailure() must be provided at link
+# time. It is linked by the pw_assert:pw_assert (or pw_assert:check) targets.
+pw_source_set("assert") {
+ public_configs = [ ":public_include_path" ]
public = [
"public/pw_assert/assert.h",
# Needed for PW_ASSERT_ENABLE_DEBUG. Note that depending on :pw_assert to
# get options.h won't work here since it will trigger the circular include
- # problem that light asserts are designed to solve.
+ # problem that the :assert target is intended solve.
"public/pw_assert/options.h",
]
public_deps = [ dir_pw_preprocessor ]
@@ -64,17 +85,17 @@
# Note: While this is technically a test, doesn't verify any of the output and
# is more of a compile test. The results can be visually verified if desired.
-pw_test("light_test") {
- configs = [ ":default_config" ]
- sources = [ "light_test.cc" ]
+pw_test("assert_test") {
+ configs = [ ":public_include_path" ]
+ sources = [ "assert_test.cc" ]
deps = [ ":pw_assert" ]
}
pw_test_group("tests") {
tests = [
+ ":assert_test",
":assert_backend_compile_test",
":assert_facade_test",
- ":light_test",
]
}
@@ -82,7 +103,7 @@
# provided. However, since this doesn't depend on the backend it re-includes
# the facade headers.
pw_test("assert_facade_test") {
- configs = [ ":default_config" ] # For internal/assert_impl.h
+ configs = [ ":public_include_path" ] # For internal/assert_impl.h
sources = [
"assert_facade_test.cc",
"fake_backend.cc",
@@ -90,7 +111,7 @@
"pw_assert_test/fake_backend.h",
]
deps = [
- ":light",
+ ":assert",
dir_pw_status,
]
diff --git a/pw_assert/light_test.cc b/pw_assert/assert_test.cc
similarity index 99%
rename from pw_assert/light_test.cc
rename to pw_assert/assert_test.cc
index 8c23df0..770ddbd 100644
--- a/pw_assert/light_test.cc
+++ b/pw_assert/assert_test.cc
@@ -12,9 +12,10 @@
// License for the specific language governing permissions and limitations under
// the License.
-#include "gtest/gtest.h"
#include "pw_assert/assert.h"
+#include "gtest/gtest.h"
+
// PW_ASSERT() should always be enabled, and always evaluate the expression.
TEST(Light, AssertTrue) {
int evaluated = 1;
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst
index ef7ee53..6a6576e 100644
--- a/pw_assert/docs.rst
+++ b/pw_assert/docs.rst
@@ -472,6 +472,21 @@
``pw_assert_HandleFailure()``, which must be provided by the ``pw_assert``
backend.
+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.
+
.. _module-pw_assert-backend_api:
-----------
@@ -489,8 +504,8 @@
.. attention::
The facade macros (``PW_CRASH`` and related) are expected to behave like they
- have the ``[[ noreturn ]]`` attribute set. This implies that the backend
- handler functions, ``PW_HANDLE_*`` defined by the backend, must not return.
+ have the ``[[noreturn]]`` attribute set. This implies that the backend handler
+ functions, ``PW_HANDLE_*`` defined by the backend, must not return.
In other words, the device must reboot.
