pw_polyfill: Make the std::span polyfill optional
- Introduce the pw_span_ENABLE_STD_SPAN_POLYFILL option to the GN build
to support enabling or disabling the <span> polyfill. This defaults to
true, but will default to false eventually.
- Rename pw_span/internal/span.h to pw_span/internal/span_polyfill.h to
distinguish it from pw_span/span.h.
Bug: b/235237667
Change-Id: I9d1028da6418b3096a08f4f84b9f97eaa7a5244e
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/99543
Reviewed-by: Ted Pudlik <tpudlik@google.com>
Commit-Queue: Wyatt Hepler <hepler@google.com>
Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com>
diff --git a/pw_build/defaults.gni b/pw_build/defaults.gni
index 9f564ff..be1f77f 100644
--- a/pw_build/defaults.gni
+++ b/pw_build/defaults.gni
@@ -14,6 +14,8 @@
import("//build_overrides/pigweed.gni")
+import("$dir_pw_span/polyfill.gni")
+
declare_args() {
# Default configs and dependencies targets provided by the toolchain. These
# are applied to all of the pw_* target types. They are set from a toolchain's
@@ -43,7 +45,9 @@
]
# TODO(b/235237667): Remove this once all uses explicitly depend on polyfills.
- public_deps += [ "$dir_pw_polyfill:overrides" ]
+ if (pw_span_ENABLE_STD_SPAN_POLYFILL) {
+ public_deps = [ "$dir_pw_span:polyfill" ]
+ }
}
# One more pass, to remove configs
diff --git a/pw_polyfill/BUILD.gn b/pw_polyfill/BUILD.gn
index 2506ce7..cb8e226 100644
--- a/pw_polyfill/BUILD.gn
+++ b/pw_polyfill/BUILD.gn
@@ -43,12 +43,6 @@
visibility = [ ":*" ]
}
-# TODO(b/235237667): Remove this overrides target by migrating all users to
-# explicitly depend on the polyfill(s) they require.
-group("overrides") {
- public_deps = [ ":span" ]
-}
-
config("standard_library_public") {
include_dirs = [ "standard_library_public" ]
}
diff --git a/pw_polyfill/docs.rst b/pw_polyfill/docs.rst
index e800eed..d52b66b 100644
--- a/pw_polyfill/docs.rst
+++ b/pw_polyfill/docs.rst
@@ -3,84 +3,12 @@
===========
pw_polyfill
===========
-The ``pw_polyfill`` module backports new C++ features to C++14.
-
-------------------------------------------------
-Backport new C++ features to older C++ standards
-------------------------------------------------
-The main purpose of ``pw_polyfill`` is to bring new C++ library and language
-features to older C++ standards. No additional ``#include`` statements are
-required to use these features; simply write code assuming that the features are
-available. This implicit feature backporting is provided through the
-``overrides`` library in the ``pw_polyfill`` module. GN automatically adds this
-library as a dependency in ``pw_source_set``.
-
-``pw_polyfill`` backports C++ library features by wrapping the standard C++ and
-C headers. The wrapper headers include the original header using
-`#include_next <https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then
-add missing features. The backported features are only defined if they aren't
-provided by the standard header, so ``pw_polyfill`` is safe to use when
-compiling with any standard C++14 or newer.
-
-The wrapper headers are in ``public_overrides``. These are provided through the
-following libraries:
-
-* ``pw_polyfill:cstddef``
-* ``pw_polyfill:iterator``
-* ``pw_polyfill:span``
-
-The GN build automatically adds dependencies on the ``<span>`` header. To apply
-other overrides, add dependencies as needed. In Bazel or CMake, overrides are
-not applied automatically, so depend on the targets you need such as
-``//pw_polyfill:span`` or ``pw_polyfill.span``.
-
-Backported features
-===================
-
-.. list-table::
-
- * - **Header**
- - **Feature**
- - **Feature test macro**
- - **Module**
- - **Polyfill header**
- - **Polyfill name**
- * - ``<array>``
- - ``std::to_array``
- - ``__cpp_lib_to_array``
- - :ref:`module-pw_containers`
- - ``pw_containers/to_array.h``
- - ``pw::containers::to_array``
- * - ``<bit>``
- - ``std::endian``
- - ``__cpp_lib_endian``
- - :ref:`module-pw_bytes`
- - ``pw_bytes/bit.h``
- - ``pw::endian``
- * - ``<cstdlib>``
- - ``std::byte``
- - ``__cpp_lib_byte``
- - pw_polyfill
- - ``<cstdlib>``
- - ``std::byte``
- * - ``<iterator>``
- - ``std::data``, ``std::size``
- - ``__cpp_lib_nonmember_container_access``
- - pw_polyfill
- - ``<iterator>``
- - ``std::data``, ``std::size``
- * - ``<span>``
- - ``std::span``
- - ``__cpp_lib_span``
- - pw_polyfill
- - ``<span>``
- - ``std::span``
+The ``pw_polyfill`` module supports compiling code against different C++
+standards. It also supports backporting a few C++17 features to C++14.
----------------------------------------------------
Adapt code to compile with different versions of C++
----------------------------------------------------
-``pw_polyfill`` provides features for adapting to different C++ standards when
-``pw_polyfill:overrides``'s automatic backporting is insufficient.
C++ standard macro
==================
@@ -96,21 +24,81 @@
Language feature macros
=======================
``pw_polyfill/language_feature_macros.h`` provides macros for adapting code to
-work with or without newer language features
+work with or without C++ language features.
-====================== ================================ ======================================== ==========================
-Macro Feature Description Feature test macro
-====================== ================================ ======================================== ==========================
-PW_INLINE_VARIABLE inline variables inline if supported by the compiler __cpp_inline_variables
-PW_CONSTEXPR_CPP20 constexpr in C++20 constexpr if compiling for C++20 __cplusplus >= 202002L
-PW_CONSTEVAL consteval consteval if supported by the compiler __cpp_consteval
-PW_CONSTINIT constinit constinit in clang and GCC 10+ __cpp_constinit
-====================== ================================ ======================================== ==========================
+.. list-table::
+ :header-rows: 1
+
+ * - Macro
+ - Feature
+ - Description
+ - Feature test macro
+ * - ``PW_INLINE_VARIABLE``
+ - inline variables
+ - inline if supported by the compiler
+ - ``__cpp_inline_variables``
+ * - ``PW_CONSTEXPR_CPP20``
+ - ``constexpr``
+ - ``constexpr`` if compiling for C++20
+ - ``__cplusplus >= 202002L``
+ * - ``PW_CONSTEVAL``
+ - ``consteval``
+ - ``consteval`` if supported by the compiler
+ - ``__cpp_consteval``
+ * - ``PW_CONSTINIT``
+ - ``constinit``
+ - ``constinit`` in clang and GCC 10+
+ - ``__cpp_constinit``
In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``,
or ``pw_polyfill``, respectively, to access these features. In other build
-systems, add ``pw_polyfill/standard_library_public`` and
-``pw_polyfill/public_overrides`` as include paths.
+systems, add ``pw_polyfill/public`` as an include path.
+
+------------------------------------------------
+Backport new C++ features to older C++ standards
+------------------------------------------------
+``pw_polyfill`` backports a few C++17 library features to C++14 by wrapping the
+standard C++ and C headers. The wrapper headers include the original header
+using `#include_next
+<https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then add missing
+features. The backported features are only defined if they aren't provided by
+the standard header and can only be used when compiling with C++14.
+
+The wrapper headers are in ``<feature>_public_overrides directories``. These are
+provided through the following libraries:
+
+* ``pw_polyfill:cstddef``
+* ``pw_polyfill:iterator``
+
+Backported features
+===================
+.. list-table::
+ :header-rows: 1
+
+ * - Header
+ - Feature
+ - Feature test macro
+ - Module
+ - Polyfill header
+ - Polyfill name
+ * - ``<array>``
+ - ``std::to_array``
+ - ``__cpp_lib_to_array``
+ - :ref:`module-pw_containers`
+ - ``pw_containers/to_array.h``
+ - ``pw::containers::to_array``
+ * - ``<cstdlib>``
+ - ``std::byte``
+ - ``__cpp_lib_byte``
+ - pw_polyfill
+ - ``<cstdlib>``
+ - ``std::byte``
+ * - ``<iterator>``
+ - ``std::data``, ``std::size``
+ - ``__cpp_lib_nonmember_container_access``
+ - pw_polyfill
+ - ``<iterator>``
+ - ``std::data``, ``std::size``
-------------
Compatibility
diff --git a/pw_span/BUILD.bazel b/pw_span/BUILD.bazel
index 71b7875..be16639 100644
--- a/pw_span/BUILD.bazel
+++ b/pw_span/BUILD.bazel
@@ -35,8 +35,8 @@
pw_cc_library(
name = "pw_span",
srcs = [
- "public/pw_span/internal/span.h",
"public/pw_span/internal/span_common.inc",
+ "public/pw_span/internal/span_polyfill.h",
],
hdrs = ["public_overrides/span"],
includes = [
diff --git a/pw_span/BUILD.gn b/pw_span/BUILD.gn
index 6878ebb..0bc22cc 100644
--- a/pw_span/BUILD.gn
+++ b/pw_span/BUILD.gn
@@ -16,6 +16,7 @@
import("$dir_pw_build/target_types.gni")
import("$dir_pw_docgen/docs.gni")
+import("$dir_pw_span/polyfill.gni")
import("$dir_pw_toolchain/traits.gni")
import("$dir_pw_unit_test/test.gni")
@@ -45,12 +46,8 @@
}
}
-# This source set provides the <span> header, which is accessed only through
-# pw_polyfill. This source set provides the internal span.h header included by
-# <span>. This source set is only used by pw_polyfill, so its visibility is
-# restricted.
+# This source set provides the <span> header.
pw_source_set("polyfill") {
- remove_public_deps = [ "*" ]
public_configs = [
":public_config",
":overrides_config",
@@ -67,13 +64,14 @@
}
public = [ "public_overrides/span" ]
sources = [
- "public/pw_span/internal/span.h",
"public/pw_span/internal/span_common.inc",
+ "public/pw_span/internal/span_polyfill.h",
]
- visibility = [
- ":*",
- "$dir_pw_polyfill:*",
- ]
+ if (pw_span_ENABLE_STD_SPAN_POLYFILL) {
+ remove_public_deps = [ "*" ]
+ } else {
+ visibility = [ ":*" ]
+ }
}
pw_test_group("tests") {
diff --git a/pw_span/CMakeLists.txt b/pw_span/CMakeLists.txt
index e6f5b5f..8a3f47f 100644
--- a/pw_span/CMakeLists.txt
+++ b/pw_span/CMakeLists.txt
@@ -16,7 +16,7 @@
pw_add_module_library(pw_span
HEADERS
-
+ public/pw_span/span.h
PUBLIC_INCLUDES
public
public_overrides
diff --git a/pw_span/docs.rst b/pw_span/docs.rst
index c7ee5eb..9c4b760 100644
--- a/pw_span/docs.rst
+++ b/pw_span/docs.rst
@@ -45,28 +45,28 @@
#include <span>
- // With std::span, the buffer is passed as a single argument.
- bool ProcessBuffer(std::span<uint8_t> buffer);
+ // With pw::span, the buffer is passed as a single argument.
+ bool ProcessBuffer(pw::span<uint8_t> buffer);
bool DoStuff() {
ProcessBuffer(c_array);
ProcessBuffer(array_object);
- ProcessBuffer(std::span(data_pointer, data_size));
+ ProcessBuffer(pw::span(data_pointer, data_size));
}
.. tip::
- Use ``pw::span<std::byte>`` or ``std::span<const std::byte>`` to represent
+ Use ``pw::span<std::byte>`` or ``pw::span<const std::byte>`` to represent
spans of binary data. Use ``pw::as_bytes`` or ``pw::as_writeable_bytes`` to
convert any span to a byte span.
.. code-block:: cpp
- void ProcessData(std::span<const std::byte> data);
+ void ProcessData(pw::span<const std::byte> data);
void DoStuff() {
std::array<AnyType, 7> data = { ... };
- ProcessData(std::as_bytes(std::span(data)));
+ ProcessData(pw::as_bytes(pw::span(data)));
}
``pw_bytes/span.h`` provides ``ByteSpan`` and ``ConstByteSpan`` aliases for
diff --git a/pw_span/polyfill.gni b/pw_span/polyfill.gni
new file mode 100644
index 0000000..5f45d7c
--- /dev/null
+++ b/pw_span/polyfill.gni
@@ -0,0 +1,20 @@
+# Copyright 2022 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
+# the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+declare_args() {
+ # Whether to provide <span> and std::span in the build. This feature is
+ # DEPRECATED and should not be used. Instead, use "pw_span/span.h" and
+ # pw::span in C++17, or std::span in C++20 or newer.
+ pw_span_ENABLE_STD_SPAN_POLYFILL = true
+}
diff --git a/pw_span/public/pw_span/internal/span.h b/pw_span/public/pw_span/internal/span_polyfill.h
similarity index 100%
rename from pw_span/public/pw_span/internal/span.h
rename to pw_span/public/pw_span/internal/span_polyfill.h
diff --git a/pw_span/public_overrides/span b/pw_span/public_overrides/span
index 715f155..ef9216b 100644
--- a/pw_span/public_overrides/span
+++ b/pw_span/public_overrides/span
@@ -24,5 +24,5 @@
#include_next <span>
#else
#undef __cpp_lib_span
-#include "pw_span/internal/span.h"
+#include "pw_span/internal/span_polyfill.h"
#endif // defined(__cpp_lib_span) && __cpp_lib_span >= 202002L
