pw_build: Updates to pw_cc_blob_library

- Support specifying the alignment of the blob with the alignas
  argument.
- Require the namespace argument.
- Isolate blob include paths under "$target_gen_dir/$target_name" so
  they aren't shared by all blobs declared in the same directory.
- No longer use different one-line formatting for short blobs to
  simplify code generation.
- Add a unit test that checks the contents of a blob.

Change-Id: I61d58b6cb95576a89fd8123b9f41ffeb0db38860
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/100801
Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com>
Reviewed-by: Ewout van Bekkum <ewout@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>

pw_build/BUILD.bazel

@@ -22,3 +22,10 @@ config_setting(
  "define": "kythe_corpus=pigweed.googlesource.com/pigweed/pigweed",
  },
 )
+
+# TODO(b/238339027): Run cc_blob_library_test when pw_cc_blob_library is
+# supported in Bazel.
+filegroup(
+ name = "cc_blob_library_test",
+ srcs = ["cc_blob_library_test.cc"],
+)

pw_build/BUILD.gn

@@ -14,10 +14,12 @@
 
 import("//build_overrides/pigweed.gni")
 
+import("$dir_pw_build/cc_blob_library.gni")
 import("$dir_pw_build/python.gni")
 import("$dir_pw_build/relative_source_file_names.gni")
 import("$dir_pw_docgen/docs.gni")
 import("$dir_pw_toolchain/traits.gni")
+import("$dir_pw_unit_test/test.gni")
 import("target_types.gni")
 
 # IMPORTANT: The compilation flags in this file must be kept in sync with
@@ -231,3 +233,29 @@ pw_doc_group("docs") {
  "python.rst",
  ]
 }
+
+pw_test("cc_blob_library_test") {
+ sources = [ "cc_blob_library_test.cc" ]
+ deps = [ ":test_blob" ]
+}
+
+pw_cc_blob_library("test_blob") {
+ out_header = "pw_build/test_blob.h"
+ namespace = "test::ns"
+ blobs = [
+ {
+ file_path = "test_blob_0123.bin"
+ symbol_name = "kFirstBlob0123"
+ alignas = 512
+ },
+ {
+ file_path = "test_blob_0123.bin"
+ symbol_name = "kSecondBlob0123"
+ },
+ ]
+ visibility = [ ":*" ]
+}
+
+pw_test_group("tests") {
+ tests = [ ":cc_blob_library_test" ]
+}

pw_build/cc_blob_library.gni

@@ -18,6 +18,8 @@ import("$dir_pw_build/python_action.gni")
 import("$dir_pw_build/target_types.gni")
 
 # Turns binary blobs into a C++ source_set library of hard-coded byte arrays.
+# The byte arrays are constant initialized and are safe to access at any time,
+# including before main().
 #
 # blobs A list of scopes, where each scope corresponds to a binary
 # blob to be transformed from file to byte array. This is a
@@ -30,15 +32,21 @@ import("$dir_pw_build/target_types.gni")
 # linker_section [optional]: If present, places the byte array
 # in the specified linker section.
 #
+# alignas [optional]: If present, the byte array is aligned as
+# specified. The value of this argument is used verbatim
+# in an alignas() specifier for the blob byte array.
+#
 # out_header The header file to generate. Users will include this file
 # exactly as it is written here to reference the byte arrays.
 #
-# namespace An optional (but highly recommended!) C++ namespace to place
-# the generated blobs within.
+# namespace The C++ namespace in which to place the generated blobs.
+#
 template("pw_cc_blob_library") {
  assert(defined(invoker.blobs), "pw_cc_blob_library requires 'blobs'")
  assert(defined(invoker.out_header),
  "pw_cc_blob_library requires an 'out_header'")
+ assert(defined(invoker.namespace),
+ "pw_cc_blob_library requires a 'namespace'")
 
  _blobs = []
  _blob_files = []
@@ -50,9 +58,13 @@ template("pw_cc_blob_library") {
  _blob_files += [ blob.file_path ]
  }
 
- _blob_json_file = "$target_gen_dir/$target_name.json"
+ _out_dir = "$target_gen_dir/$target_name"
+ _blob_json_file = "$_out_dir/blobs.json"
  write_file(_blob_json_file, _blobs, "json")
 
+ _header = "$_out_dir/public/${invoker.out_header}"
+ _source = "$_out_dir/" + get_path_info(invoker.out_header, "name") + ".cc"
+
  pw_python_action("$target_name._gen") {
  forward_variables_from(invoker,
  [
@@ -62,25 +74,17 @@ template("pw_cc_blob_library") {
  module = "pw_build.generate_cc_blob_library"
  python_deps = [ "$dir_pw_build/py" ]
 
- _header = "${target_gen_dir}/public/" + invoker.out_header
- _source =
- "${target_gen_dir}/" + get_path_info(invoker.out_header, "name") + ".cc"
  args = [
  "--blob-file",
  rebase_path(_blob_json_file, root_build_dir),
+ "--namespace=${invoker.namespace}",
+ "--header-include=${invoker.out_header}",
  "--out-header",
- rebase_path(_header),
+ rebase_path(_header, root_build_dir),
  "--out-source",
- rebase_path(_source),
+ rebase_path(_source, root_build_dir),
  ]
 
- if (defined(invoker.namespace)) {
- args += [
- "--namespace",
- invoker.namespace,
- ]
- }
-
  inputs = [ _blob_json_file ] + _blob_files
  outputs = [
  _header,
@@ -89,14 +93,18 @@ template("pw_cc_blob_library") {
  }
 
  config("$target_name._include_path") {
- include_dirs = [ "${target_gen_dir}/public" ]
+ include_dirs = [ "$_out_dir/public" ]
  visibility = [ ":*" ]
  }
 
  pw_source_set(target_name) {
- sources = get_target_outputs(":$target_name._gen")
+ public = [ _header ]
+ sources = [ _source ]
  public_configs = [ ":$target_name._include_path" ]
- deps = [ ":$target_name._gen" ]
- public_deps = [ "$dir_pw_preprocessor" ]
+ deps = [
+ ":$target_name._gen",
+ dir_pw_preprocessor,
+ ]
+ forward_variables_from(invoker, [ "visibility" ])
  }
 }

pw_build/cc_blob_library_test.cc

@@ -0,0 +1,53 @@
+// 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.
+
+#include <cstddef>
+
+#include "gtest/gtest.h"
+#include "pw_build/test_blob.h"
+
+namespace pw::build {
+namespace {
+
+static_assert(test::ns::kFirstBlob0123.size() == 4);
+static_assert(test::ns::kFirstBlob0123.data() != nullptr);
+
+static_assert(test::ns::kSecondBlob0123.size() == 4);
+static_assert(test::ns::kSecondBlob0123.data() != nullptr);
+
+TEST(CcBlobLibraryTest, FirstBlobContentsMatch) {
+ EXPECT_EQ(test::ns::kFirstBlob0123[0], std::byte{0});
+ EXPECT_EQ(test::ns::kFirstBlob0123[1], std::byte{1});
+ EXPECT_EQ(test::ns::kFirstBlob0123[2], std::byte{2});
+ EXPECT_EQ(test::ns::kFirstBlob0123[3], std::byte{3});
+}
+
+TEST(CcBlobLibraryTest, SecondBlobContentsMatch) {
+ EXPECT_EQ(test::ns::kSecondBlob0123[0], std::byte{0});
+ EXPECT_EQ(test::ns::kSecondBlob0123[1], std::byte{1});
+ EXPECT_EQ(test::ns::kSecondBlob0123[2], std::byte{2});
+ EXPECT_EQ(test::ns::kSecondBlob0123[3], std::byte{3});
+}
+
+TEST(CcBlobLibraryTest, FirstBlobAlignedTo512) {
+ // This checks that the variable is aligned to 512, but cannot guarantee that
+ // alignas was specified correctly, since it could be aligned to 512 by
+ // coincidence.
+ const uintptr_t addr = reinterpret_cast<uintptr_t>(&test::ns::kFirstBlob0123);
+ constexpr uintptr_t kAlignmentMask = static_cast<uintptr_t>(512 - 1);
+ EXPECT_EQ(addr & kAlignmentMask, 0u);
+}
+
+} // namespace
+} // namespace pw::build

pw_build/docs.rst

@@ -128,7 +128,10 @@ pw_cc_blob_library
 The ``pw_cc_blob_library`` template is useful for embedding binary data into a
 program. The template takes in a mapping of symbol names to file paths, and
 generates a set of C++ source and header files that embed the contents of the
-passed-in files as arrays.
+passed-in files as arrays of ``std::byte``.
+
+The blob byte arrays are constant initialized and are safe to access at any
+time, including before ``main()``.
 
 **Arguments**
 
@@ -140,6 +143,8 @@ passed-in files as arrays.
  * ``file_path``: The file path for the binary blob.
  * ``linker_section``: If present, places the byte array in the specified
  linker section.
+ * ``alignas``: If present, uses the specified string or integer verbatim in
+ the ``alignas()`` specifier for the byte array.
 
 * ``out_header``: The header file to generate. Users will include this file
  exactly as it is written here to reference the byte arrays.

pw_build/generated_pigweed_modules_lists.gni

@@ -297,6 +297,7 @@ declare_args() {
  "$dir_pw_blob_store:tests",
  "$dir_pw_bluetooth:tests",
  "$dir_pw_bluetooth_hci:tests",
+ "$dir_pw_build:tests",
  "$dir_pw_bytes:tests",
  "$dir_pw_checksum:tests",
  "$dir_pw_chrono:tests",