pw_presubmit: RST formatting
Change-Id: I37cabb32c7f91c1a1b961240a775f1f82aea76a9
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/168541
Reviewed-by: Taylor Cramer <cramertj@google.com>
Commit-Queue: Anthony DiGirolamo <tonymd@google.com>
diff --git a/docs/build_system.rst b/docs/build_system.rst
index 97da566..d355de4 100644
--- a/docs/build_system.rst
+++ b/docs/build_system.rst
@@ -204,13 +204,13 @@
.. code-block::
- # The location of the BUILDCONFIG file.
- buildconfig = "//BUILDCONFIG.gn"
+ # The location of the BUILDCONFIG file.
+ buildconfig = "//BUILDCONFIG.gn"
- # Build arguments set across all Pigweed targets.
- default_args = {
- dir_pw_third_party_nanopb = "//third_party/nanopb-0.4.2"
- }
+ # Build arguments set across all Pigweed targets.
+ default_args = {
+ dir_pw_third_party_nanopb = "//third_party/nanopb-0.4.2"
+ }
Configuration: BUILDCONFIG.gn
-----------------------------
@@ -275,20 +275,20 @@
.. code-block::
- group("my_application_images") {
- deps = [] # Empty in the default toolchain.
+ group("my_application_images") {
+ deps = [] # Empty in the default toolchain.
- if (current_toolchain != default_toolchain) {
- # This is only evaluated by Pigweed target toolchains, which configure
- # all of the required options to build Pigweed code.
- deps += [ "//images:evt" ]
- }
- }
+ if (current_toolchain != default_toolchain) {
+ # This is only evaluated by Pigweed target toolchains, which configure
+ # all of the required options to build Pigweed code.
+ deps += [ "//images:evt" ]
+ }
+ }
- # The images group is instantiated for each of the project's Pigweed targets.
- group("my_pigweed_target") {
- deps = [ ":my_application_images(//toolchains:my_pigweed_target)" ]
- }
+ # The images group is instantiated for each of the project's Pigweed targets.
+ group("my_pigweed_target") {
+ deps = [ ":my_application_images(//toolchains:my_pigweed_target)" ]
+ }
.. warning::
Pigweed's default toolchain is never used, so it is set to an empty toolchain
@@ -435,11 +435,11 @@
.. code-block::
- # This must be imported before .gni files from any other Pigweed modules. To
- # prevent gn format from reordering this import, it must be separated by a
- # blank line from other imports.
+ # This must be imported before .gni files from any other Pigweed modules. To
+ # prevent gn format from reordering this import, it must be separated by a
+ # blank line from other imports.
- import("//build_overrides/pigweed.gni")
+ import("//build_overrides/pigweed.gni")
GN target type wrappers
-----------------------
@@ -496,24 +496,24 @@
.. code-block::
- # //foo/BUILD.gn
- pw_executable("foo") {
- sources = [ "main.cc" ]
- deps = [ ":libfoo" ]
- }
+ # //foo/BUILD.gn
+ pw_executable("foo") {
+ sources = [ "main.cc" ]
+ deps = [ ":libfoo" ]
+ }
2. In the root ``BUILD.gn`` file, add the executable's GN target to the ``apps``
group.
.. code-block::
- # //BUILD.gn
- group("apps") {
- deps = [
- # ...
- "//foo", # Shorthand for //foo:foo
- ]
- }
+ # //BUILD.gn
+ group("apps") {
+ deps = [
+ # ...
+ "//foo", # Shorthand for //foo:foo
+ ]
+ }
3. Run the ninja build to compile your executable. The apps group is built by
default, so there's no need to provide a target. The executable will be
@@ -521,7 +521,7 @@
.. code-block::
- ninja -C out
+ ninja -C out
Alternatively, build your executable by itself by specifying its path to
Ninja. When building a GN target manually, the Pigweed target for which it
@@ -531,7 +531,7 @@
.. code-block::
- ninja -C out host_gcc_debug/obj/foo/bin/foo
+ ninja -C out host_gcc_debug/obj/foo/bin/foo
.. note::
@@ -543,7 +543,7 @@
.. code-block::
- out/<pw_target>/obj/<gn_path>/{bin,test}/<executable>
+ out/<pw_target>/obj/<gn_path>/{bin,test}/<executable>
where ``pw_target`` is the Pigweed target for which the binary was built,
``gn_path`` is the GN path to the BUILD.gn file defining the executable,
@@ -556,7 +556,7 @@
.. code-block::
- out/stm32f429i_disc1_debug/obj/foo/bin/foo
+ out/stm32f429i_disc1_debug/obj/foo/bin/foo
CMake
-----
@@ -850,18 +850,18 @@
.. code-block::
- # BUILD
- pw_cc_library(
- name = "time_is_relative",
- srcs = ["relative_time_on_earth.cc"],
- deps = ["@pigweed//pw_chrono"],
- )
+ # BUILD
+ pw_cc_library(
+ name = "time_is_relative",
+ srcs = ["relative_time_on_earth.cc"],
+ deps = ["@pigweed//pw_chrono"],
+ )
Now this should work out of the box for any host operating system. e.g. Running;
.. code-block::
- bazel build //:time_is_relative
+ bazel build //:time_is_relative
will produce a working library. But as your probably here because Pigweed offers
a set of embedded libraries you might be interested in running your code on some
@@ -882,21 +882,21 @@
.. code-block::
- @pigweed//pw_chrono:pw_chrono_facade <-----------.
- ^ |
- | @pigweed//pw_chrono_freertos:system_clock
- | (Actual backend)
- | ^
- | |
- | @pigweed//pw_chrono:system_clock_backend_multiplexer
- | Select backend based on OS:
- | [FreeRTOS (X), Embos ( ), STL ( ), Threadx ( )]
- | ^
- | |
- @pigweed//pw_chrono -------> @pigweed_config//:pw_chrono_system_clock_backend
- ^ (Injectable)
- |
- //:time_is_relative
+ @pigweed//pw_chrono:pw_chrono_facade <-----------.
+ ^ |
+ | @pigweed//pw_chrono_freertos:system_clock
+ | (Actual backend)
+ | ^
+ | |
+ | @pigweed//pw_chrono:system_clock_backend_multiplexer
+ | Select backend based on OS:
+ | [FreeRTOS (X), Embos ( ), STL ( ), Threadx ( )]
+ | ^
+ | |
+ @pigweed//pw_chrono -------> @pigweed_config//:pw_chrono_system_clock_backend
+ ^ (Injectable)
+ |
+ //:time_is_relative
So when evaluating this setup Bazel checks the dependencies for '//pw_chrono'
and finds that it depends on "@pigweed_config//:pw_chrono_system_clock_backend" which looks
@@ -952,16 +952,16 @@
.. code-block::
- @pigweed//pw_chrono:pw_chrono_facade <-----.
- ^ |
- | @your_workspace//pw_chrono_my_hardware_rtc:system_clock
- | (Actual backend)
- | ^
- | |
- @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend
- ^ (Injectable)
- |
- //:time_is_relative
+ @pigweed//pw_chrono:pw_chrono_facade <-----.
+ ^ |
+ | @your_workspace//pw_chrono_my_hardware_rtc:system_clock
+ | (Actual backend)
+ | ^
+ | |
+ @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend
+ ^ (Injectable)
+ |
+ //:time_is_relative
Now while this is a nice temporary change, but you might find yourself in need
of a more permanent configuration. Particularly if you want to override multiple
@@ -1050,18 +1050,19 @@
.. code-block::
- @pigweed//pw_chrono:pw_chrono_facade <---.
- ^ |
- | @your_workspace//pw_chrono_my_hardware_rtc:system_clock
- | (Actual backend)
- | ^
- | |
- | @your_workspace//pw_chrono:system_clock_backend_multiplexer
- | Select backend based on OS:
- | [Primary (X), Backup ( ), Host only default ( )]
- | ^
- | |
- @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend
- ^ (Injectable)
- |
- //:time_is_relative
+ @pigweed//pw_chrono:pw_chrono_facade <---.
+ ^ |
+ | @your_workspace//pw_chrono_my_hardware_rtc:system_clock
+ | (Actual backend)
+ | ^
+ | |
+ | @your_workspace//pw_chrono:system_clock_backend_multiplexer
+ | Select backend based on OS:
+ | [Primary (X), Backup ( ), Host only default ( )]
+ | ^
+ | |
+ @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend
+ ^ (Injectable)
+ |
+ //:time_is_relative
+
diff --git a/docs/editors.rst b/docs/editors.rst
index 027bcdb..94ba020 100644
--- a/docs/editors.rst
+++ b/docs/editors.rst
@@ -207,9 +207,9 @@
$ pw ide cpp --list
C/C++ targets available for language server analysis:
- pw_strict_host_gcc_debug
- pw_strict_host_clang_debug
- stm32f429i_disc1_debug
+ pw_strict_host_gcc_debug
+ pw_strict_host_clang_debug
+ stm32f429i_disc1_debug
Select the target you want to use for code analysis:
diff --git a/docs/module_structure.rst b/docs/module_structure.rst
index 26079db..e9dee9d 100644
--- a/docs/module_structure.rst
+++ b/docs/module_structure.rst
@@ -145,9 +145,9 @@
.. code-block::
- pw_foo/...
- public/pw_foo/internal/secret.h
- public/pw_foo/internal/business.h
+ pw_foo/...
+ public/pw_foo/internal/secret.h
+ public/pw_foo/internal/business.h
.. note::
@@ -174,15 +174,15 @@
.. code-block::
- pw_unit_test/...
+ pw_unit_test/...
- public_overrides/gtest
- public_overrides/gtest/gtest.h
+ public_overrides/gtest
+ public_overrides/gtest/gtest.h
- public/pw_unit_test
- public/pw_unit_test/simple_printing_event_handler.h
- public/pw_unit_test/event_handler.h
- public/pw_unit_test/internal/framework.h
+ public/pw_unit_test
+ public/pw_unit_test/simple_printing_event_handler.h
+ public/pw_unit_test/event_handler.h
+ public/pw_unit_test/internal/framework.h
Note that the overrides are in a separate directory ``public_overrides``.
@@ -195,12 +195,12 @@
.. code-block::
- pw_unit_test/...
- main.cc
- framework.cc
- test.gni
- BUILD.gn
- README.md
+ pw_unit_test/...
+ main.cc
+ framework.cc
+ test.gni
+ BUILD.gn
+ README.md
.. _module-structure-compile-time-configuration:
@@ -241,16 +241,16 @@
.. code-block::
- pw_foo/...
+ pw_foo/...
- # Publicly accessible configuration header
- public/pw_foo/config.h
+ # Publicly accessible configuration header
+ public/pw_foo/config.h
- # Internal configuration header that is included by other module headers
- public/pw_foo/internal/config.h
+ # Internal configuration header that is included by other module headers
+ public/pw_foo/internal/config.h
- # Internal configuration header
- pw_foo_private/config.h
+ # Internal configuration header
+ pw_foo_private/config.h
The configuration header is provided by a build system library. This library
acts as a :ref:`facade<docs-module-structure-facades>`. The facade uses a
@@ -260,37 +260,37 @@
.. code-block::
- declare_args() {
- # The build target that overrides the default configuration options for this
- # module. This should point to a source set that provides defines through a
- # public config (which may -include a file or add defines directly).
- pw_foo_CONFIG = pw_build_DEFAULT_MODULE_CONFIG
- }
+ declare_args() {
+ # The build target that overrides the default configuration options for this
+ # module. This should point to a source set that provides defines through a
+ # public config (which may -include a file or add defines directly).
+ pw_foo_CONFIG = pw_build_DEFAULT_MODULE_CONFIG
+ }
- # An example source set for each potential config header location follows.
+ # An example source set for each potential config header location follows.
- # Publicly accessible configuration header (most common)
- pw_source_set("config") {
- public = [ "public/pw_foo/config.h" ]
- public_configs = [ ":public_include_path" ]
- public_deps = [ pw_foo_CONFIG ]
- }
+ # Publicly accessible configuration header (most common)
+ pw_source_set("config") {
+ public = [ "public/pw_foo/config.h" ]
+ public_configs = [ ":public_include_path" ]
+ public_deps = [ pw_foo_CONFIG ]
+ }
- # Internal configuration header that is included by other module headers
- pw_source_set("config") {
- sources = [ "public/pw_foo/internal/config.h" ]
- public_configs = [ ":public_include_path" ]
- public_deps = [ pw_foo_CONFIG ]
- visibility = [":*"] # Only allow this module to depend on ":config"
- friend = [":*"] # Allow this module to access the config.h header.
- }
+ # Internal configuration header that is included by other module headers
+ pw_source_set("config") {
+ sources = [ "public/pw_foo/internal/config.h" ]
+ public_configs = [ ":public_include_path" ]
+ public_deps = [ pw_foo_CONFIG ]
+ visibility = [":*"] # Only allow this module to depend on ":config"
+ friend = [":*"] # Allow this module to access the config.h header.
+ }
- # Internal configuration header
- pw_source_set("config") {
- public = [ "pw_foo_private/config.h" ]
- public_deps = [ pw_foo_CONFIG ]
- visibility = [":*"] # Only allow this module to depend on ":config"
- }
+ # Internal configuration header
+ pw_source_set("config") {
+ public = [ "pw_foo_private/config.h" ]
+ public_deps = [ pw_foo_CONFIG ]
+ visibility = [":*"] # Only allow this module to depend on ":config"
+ }
Overriding configuration
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -311,32 +311,32 @@
.. code-block::
- # In the toolchain, set either pw_build_DEFAULT_MODULE_CONFIG or pw_foo_CONFIG
- pw_build_DEFAULT_MODULE_CONFIG = get_path_info(":define_overrides", "abspath")
+ # In the toolchain, set either pw_build_DEFAULT_MODULE_CONFIG or pw_foo_CONFIG
+ pw_build_DEFAULT_MODULE_CONFIG = get_path_info(":define_overrides", "abspath")
- # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES using the -D flag.
- pw_source_set("define_overrides") {
- public_configs = [ ":define_options" ]
- }
+ # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES using the -D flag.
+ pw_source_set("define_overrides") {
+ public_configs = [ ":define_options" ]
+ }
- config("define_options") {
- defines = [ "PW_FOO_INPUT_BUFFER_SIZE_BYTES=256" ]
- }
+ config("define_options") {
+ defines = [ "PW_FOO_INPUT_BUFFER_SIZE_BYTES=256" ]
+ }
- # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES in a header file.
- pw_source_set("include_overrides") {
- public_configs = [ ":set_options_in_header_file" ]
+ # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES in a header file.
+ pw_source_set("include_overrides") {
+ public_configs = [ ":set_options_in_header_file" ]
- # Header file with #define PW_FOO_INPUT_BUFFER_SIZE_BYTES 256
- sources = [ "my_config_overrides.h" ]
- }
+ # Header file with #define PW_FOO_INPUT_BUFFER_SIZE_BYTES 256
+ sources = [ "my_config_overrides.h" ]
+ }
- config("set_options_in_header_file") {
- cflags = [
- "-include",
- rebase_path("my_config_overrides.h", root_build_dir),
- ]
- }
+ config("set_options_in_header_file") {
+ cflags = [
+ "-include",
+ rebase_path("my_config_overrides.h", root_build_dir),
+ ]
+ }
.. admonition:: Why this config pattern is preferred
@@ -409,19 +409,19 @@
.. code-block::
- # pw_foo contains 2 facades, foo and bar
- pw_foo/...
- # Public headers
- # public/pw_foo/foo.h #includes pw_foo_backend/foo.h
- # public/pw_foo/bar.h #includes pw_foo_backend/bar.h
- public/pw_foo/foo.h
- public/pw_foo/bar.h
+ # pw_foo contains 2 facades, foo and bar
+ pw_foo/...
+ # Public headers
+ # public/pw_foo/foo.h #includes pw_foo_backend/foo.h
+ # public/pw_foo/bar.h #includes pw_foo_backend/bar.h
+ public/pw_foo/foo.h
+ public/pw_foo/bar.h
- pw_foo_backend/...
+ pw_foo_backend/...
- # Public override headers for facade1 and facade2 go in separate folders
- foo_public_overrides/pw_foo_backend/foo.h
- bar_public_overrides/pw_foo_backend/bar.h
+ # Public override headers for facade1 and facade2 go in separate folders
+ foo_public_overrides/pw_foo_backend/foo.h
+ bar_public_overrides/pw_foo_backend/bar.h
Documentation
-------------
diff --git a/docs/python_build.rst b/docs/python_build.rst
index ba30abf..2be9cb0 100644
--- a/docs/python_build.rst
+++ b/docs/python_build.rst
@@ -166,10 +166,10 @@
.. code-block::
- pw_build_PIP_REQUIREMENTS = [
- # Project specific requirements
- "//tools/requirements.txt",
- ]
+ pw_build_PIP_REQUIREMENTS = [
+ # Project specific requirements
+ "//tools/requirements.txt",
+ ]
See the :ref:`docs-python-build-python-gn-structure` section below for a full
code listing.
diff --git a/docs/targets.rst b/docs/targets.rst
index 3988aa4..00bb6a7 100644
--- a/docs/targets.rst
+++ b/docs/targets.rst
@@ -69,31 +69,31 @@
.. code-block::
- import("//build_overrides/pigweed.gni")
+ import("//build_overrides/pigweed.gni")
- import("$dir_pw_toolchain/arm_gcc/toolchains.gni")
- import("$dir_pw_toolchain/generate_toolchain.gni")
+ import("$dir_pw_toolchain/arm_gcc/toolchains.gni")
+ import("$dir_pw_toolchain/generate_toolchain.gni")
- my_target_scope = {
- # Use Pigweed's Cortex M4 toolchain as a base.
- _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug
+ my_target_scope = {
+ # Use Pigweed's Cortex M4 toolchain as a base.
+ _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug
- # Forward everything except the defaults scope from that toolchain.
- forward_variables_from(_toolchain_base, "*", [ "defaults" ])
+ # Forward everything except the defaults scope from that toolchain.
+ forward_variables_from(_toolchain_base, "*", [ "defaults" ])
- defaults = {
- # Forward everything from the base toolchain's defaults.
- forward_variables_from(_toolchain_base.defaults, "*")
+ defaults = {
+ # Forward everything from the base toolchain's defaults.
+ forward_variables_from(_toolchain_base.defaults, "*")
- # Extend with custom build arguments for the target.
- pw_log_BACKEND = dir_pw_log_tokenized
- }
- }
+ # Extend with custom build arguments for the target.
+ pw_log_BACKEND = dir_pw_log_tokenized
+ }
+ }
- # Create the actual GN toolchain from the scope.
- generate_toolchain("my_target") {
- forward_variables_from(my_target_scope, "*")
- }
+ # Create the actual GN toolchain from the scope.
+ generate_toolchain("my_target") {
+ forward_variables_from(my_target_scope, "*")
+ }
Upstream targets
================
diff --git a/pw_assert_tokenized/docs.rst b/pw_assert_tokenized/docs.rst
index bb3d8f8..59ba703 100644
--- a/pw_assert_tokenized/docs.rst
+++ b/pw_assert_tokenized/docs.rst
@@ -70,29 +70,29 @@
.. code-block::
- pw_executable("main") {
- deps = [
- # ...
- ]
- sources = [ "main.cc" ]
- }
+ pw_executable("main") {
+ deps = [
+ # ...
+ ]
+ sources = [ "main.cc" ]
+ }
- pw_tokenizer_database("log_tokens") {
- database = "tools/tokenized_logs.csv"
- deps = [
- ":source_file_names",
- ":main",
- ]
- optional_paths = [ "$root_build_dir/**/*.elf" ]
- input_databases = [ "$target_gen_dir/source_file_names.json" ]
- }
+ pw_tokenizer_database("log_tokens") {
+ database = "tools/tokenized_logs.csv"
+ deps = [
+ ":source_file_names",
+ ":main",
+ ]
+ optional_paths = [ "$root_build_dir/**/*.elf" ]
+ input_databases = [ "$target_gen_dir/source_file_names.json" ]
+ }
- # Extracts all source/header file names from "main" and its transitive
- # dependencies for tokenization.
- pw_relative_source_file_names("source_file_names") {
- deps = [ ":main" ]
- outputs = [ "$target_gen_dir/source_file_names.json" ]
- }
+ # Extracts all source/header file names from "main" and its transitive
+ # dependencies for tokenization.
+ pw_relative_source_file_names("source_file_names") {
+ deps = [ ":main" ]
+ outputs = [ "$target_gen_dir/source_file_names.json" ]
+ }
.. warning::
diff --git a/pw_async_basic/docs.rst b/pw_async_basic/docs.rst
index 0363a26..7692407 100644
--- a/pw_async_basic/docs.rst
+++ b/pw_async_basic/docs.rst
@@ -20,20 +20,20 @@
.. code-block::
- pw_async_TASK_BACKEND="$dir_pw_async_basic:task"
- pw_async_FAKE_DISPATCHER_BACKEND="$dir_pw_async_basic:fake_dispatcher"
+ pw_async_TASK_BACKEND="$dir_pw_async_basic:task"
+ pw_async_FAKE_DISPATCHER_BACKEND="$dir_pw_async_basic:fake_dispatcher"
Next, create a target that depends on ``//pw_async_basic:dispatcher``:
.. code-block::
- pw_executable("hello_world") {
- sources = [ "hello_world.cc" ]
- deps = [
- "//pw_async_basic:dispatcher",
- ]
- }
+ pw_executable("hello_world") {
+ sources = [ "hello_world.cc" ]
+ deps = [
+ "//pw_async_basic:dispatcher",
+ ]
+ }
Next, construct and use a ``BasicDispatcher``.
diff --git a/pw_bloat/docs.rst b/pw_bloat/docs.rst
index 844fa09..a9da474 100644
--- a/pw_bloat/docs.rst
+++ b/pw_bloat/docs.rst
@@ -123,35 +123,35 @@
.. code-block::
- import("$dir_pw_bloat/bloat.gni")
+ import("$dir_pw_bloat/bloat.gni")
- executable("empty_base") {
- sources = [ "empty_main.cc" ]
- }
+ executable("empty_base") {
+ sources = [ "empty_main.cc" ]
+ }
- executable("hello_world_printf") {
- sources = [ "hello_printf.cc" ]
- }
+ executable("hello_world_printf") {
+ sources = [ "hello_printf.cc" ]
+ }
- executable("hello_world_iostream") {
- sources = [ "hello_iostream.cc" ]
- }
+ executable("hello_world_iostream") {
+ sources = [ "hello_iostream.cc" ]
+ }
- pw_size_diff("my_size_report") {
- base = ":empty_base"
- data_sources = "symbols,segments"
- binaries = [
- {
- target = ":hello_world_printf"
- label = "Hello world using printf"
- },
- {
- target = ":hello_world_iostream"
- label = "Hello world using iostream"
- data_sources = "symbols"
- },
- ]
- }
+ pw_size_diff("my_size_report") {
+ base = ":empty_base"
+ data_sources = "symbols,segments"
+ binaries = [
+ {
+ target = ":hello_world_printf"
+ label = "Hello world using printf"
+ },
+ {
+ target = ":hello_world_iostream"
+ label = "Hello world using iostream"
+ data_sources = "symbols"
+ },
+ ]
+ }
A sample ``pw_size_diff`` ReST size report table can be found within module
docs. For example, see the :ref:`pw_checksum-size-report` section of the
@@ -171,58 +171,58 @@
.. code-block::
- import("$dir_pw_bloat/bloat.gni")
+ import("$dir_pw_bloat/bloat.gni")
- executable("hello_world_iostream") {
- sources = [ "hello_iostream.cc" ]
- }
+ executable("hello_world_iostream") {
+ sources = [ "hello_iostream.cc" ]
+ }
- pw_size_report("hello_world_iostream_size_report") {
- target = ":hello_iostream"
- data_sources = "segments,symbols"
- source_filter = "pw::hello"
- }
+ pw_size_report("hello_world_iostream_size_report") {
+ target = ":hello_iostream"
+ data_sources = "segments,symbols"
+ source_filter = "pw::hello"
+ }
Sample Single Binary ASCII Table Generated
.. code-block::
- ┌─────────────┬──────────────────────────────────────────────────┬──────┐
- │segment_names│ symbols │ sizes│
- ├═════════════┼══════════════════════════════════════════════════┼══════┤
- │FLASH │ │12,072│
- │ │pw::kvs::KeyValueStore::InitializeMetadata() │ 684│
- │ │pw::kvs::KeyValueStore::Init() │ 456│
- │ │pw::kvs::internal::EntryCache::Find() │ 444│
- │ │pw::kvs::FakeFlashMemory::Write() │ 240│
- │ │pw::kvs::internal::Entry::VerifyChecksumInFlash() │ 228│
- │ │pw::kvs::KeyValueStore::GarbageCollectSector() │ 220│
- │ │pw::kvs::KeyValueStore::RemoveDeletedKeyEntries() │ 220│
- │ │pw::kvs::KeyValueStore::AppendEntry() │ 204│
- │ │pw::kvs::KeyValueStore::Get() │ 194│
- │ │pw::kvs::internal::Entry::Read() │ 188│
- │ │pw::kvs::ChecksumAlgorithm::Finish() │ 26│
- │ │pw::kvs::internal::Entry::ReadKey() │ 26│
- │ │pw::kvs::internal::Sectors::BaseAddress() │ 24│
- │ │pw::kvs::ChecksumAlgorithm::Update() │ 20│
- │ │pw::kvs::FlashTestPartition() │ 8│
- │ │pw::kvs::FakeFlashMemory::Disable() │ 6│
- │ │pw::kvs::FakeFlashMemory::Enable() │ 6│
- │ │pw::kvs::FlashMemory::SelfTest() │ 6│
- │ │pw::kvs::FlashPartition::Init() │ 6│
- │ │pw::kvs::FlashPartition::sector_size_bytes() │ 6│
- │ │pw::kvs::FakeFlashMemory::IsEnabled() │ 4│
- ├─────────────┼──────────────────────────────────────────────────┼──────┤
- │RAM │ │ 1,424│
- │ │test_kvs │ 992│
- │ │pw::kvs::(anonymous namespace)::test_flash │ 384│
- │ │pw::kvs::(anonymous namespace)::test_partition │ 24│
- │ │pw::kvs::FakeFlashMemory::no_errors_ │ 12│
- │ │borrowable_kvs │ 8│
- │ │kvs_entry_count │ 4│
- ├═════════════┼══════════════════════════════════════════════════┼══════┤
- │Total │ │13,496│
- └─────────────┴──────────────────────────────────────────────────┴──────┘
+ ┌─────────────┬──────────────────────────────────────────────────┬──────┐
+ │segment_names│ symbols │ sizes│
+ ├═════════════┼══════════════════════════════════════════════════┼══════┤
+ │FLASH │ │12,072│
+ │ │pw::kvs::KeyValueStore::InitializeMetadata() │ 684│
+ │ │pw::kvs::KeyValueStore::Init() │ 456│
+ │ │pw::kvs::internal::EntryCache::Find() │ 444│
+ │ │pw::kvs::FakeFlashMemory::Write() │ 240│
+ │ │pw::kvs::internal::Entry::VerifyChecksumInFlash() │ 228│
+ │ │pw::kvs::KeyValueStore::GarbageCollectSector() │ 220│
+ │ │pw::kvs::KeyValueStore::RemoveDeletedKeyEntries() │ 220│
+ │ │pw::kvs::KeyValueStore::AppendEntry() │ 204│
+ │ │pw::kvs::KeyValueStore::Get() │ 194│
+ │ │pw::kvs::internal::Entry::Read() │ 188│
+ │ │pw::kvs::ChecksumAlgorithm::Finish() │ 26│
+ │ │pw::kvs::internal::Entry::ReadKey() │ 26│
+ │ │pw::kvs::internal::Sectors::BaseAddress() │ 24│
+ │ │pw::kvs::ChecksumAlgorithm::Update() │ 20│
+ │ │pw::kvs::FlashTestPartition() │ 8│
+ │ │pw::kvs::FakeFlashMemory::Disable() │ 6│
+ │ │pw::kvs::FakeFlashMemory::Enable() │ 6│
+ │ │pw::kvs::FlashMemory::SelfTest() │ 6│
+ │ │pw::kvs::FlashPartition::Init() │ 6│
+ │ │pw::kvs::FlashPartition::sector_size_bytes() │ 6│
+ │ │pw::kvs::FakeFlashMemory::IsEnabled() │ 4│
+ ├─────────────┼──────────────────────────────────────────────────┼──────┤
+ │RAM │ │ 1,424│
+ │ │test_kvs │ 992│
+ │ │pw::kvs::(anonymous namespace)::test_flash │ 384│
+ │ │pw::kvs::(anonymous namespace)::test_partition │ 24│
+ │ │pw::kvs::FakeFlashMemory::no_errors_ │ 12│
+ │ │borrowable_kvs │ 8│
+ │ │kvs_entry_count │ 4│
+ ├═════════════┼══════════════════════════════════════════════════┼══════┤
+ │Total │ │13,496│
+ └─────────────┴──────────────────────────────────────────────────┴──────┘
Size reports are typically included in ReST documentation, as described in
@@ -250,15 +250,15 @@
.. code-block::
- import("$dir_pw_bloat/bloat.gni")
+ import("$dir_pw_bloat/bloat.gni")
- pw_size_report_aggregation("image_sizes") {
- deps = [
- ":app_image_size_report",
- ":bootloader_image_size_report",
- ]
- output = "$root_gen_dir/artifacts/image_sizes.json"
- }
+ pw_size_report_aggregation("image_sizes") {
+ deps = [
+ ":app_image_size_report",
+ ":bootloader_image_size_report",
+ ]
+ output = "$root_gen_dir/artifacts/image_sizes.json"
+ }
Documentation integration
=========================
@@ -313,16 +313,16 @@
.. code-block::
- 84.2% 1023Ki FLASH
- 94.2% 963Ki Free space
- 5.8% 59.6Ki Used space
- 15.8% 192Ki RAM
- 100.0% 192Ki Used space
- 0.0% 512 VECTOR_TABLE
- 96.9% 496 Free space
- 3.1% 16 Used space
- 0.0% 0 Not resident in memory
- NAN% 0 Used space
+ 84.2% 1023Ki FLASH
+ 94.2% 963Ki Free space
+ 5.8% 59.6Ki Used space
+ 15.8% 192Ki RAM
+ 100.0% 192Ki Used space
+ 0.0% 512 VECTOR_TABLE
+ 96.9% 496 Free space
+ 3.1% 16 Used space
+ 0.0% 0 Not resident in memory
+ NAN% 0 Used space
``utilization`` data source
@@ -345,125 +345,125 @@
.. code-block::
- MEMORY
- {
- FLASH(rx) : \
- ORIGIN = PW_BOOT_FLASH_BEGIN, \
- LENGTH = PW_BOOT_FLASH_SIZE
- RAM(rwx) : \
- ORIGIN = PW_BOOT_RAM_BEGIN, \
- LENGTH = PW_BOOT_RAM_SIZE
- }
+ MEMORY
+ {
+ FLASH(rx) : \
+ ORIGIN = PW_BOOT_FLASH_BEGIN, \
+ LENGTH = PW_BOOT_FLASH_SIZE
+ RAM(rwx) : \
+ ORIGIN = PW_BOOT_RAM_BEGIN, \
+ LENGTH = PW_BOOT_RAM_SIZE
+ }
- SECTIONS
- {
- /* Main executable code. */
- .code : ALIGN(4)
- {
- /* Application code. */
- *(.text)
- *(.text*)
- KEEP(*(.init))
- KEEP(*(.fini))
+ SECTIONS
+ {
+ /* Main executable code. */
+ .code : ALIGN(4)
+ {
+ /* Application code. */
+ *(.text)
+ *(.text*)
+ KEEP(*(.init))
+ KEEP(*(.fini))
- . = ALIGN(4);
- /* Constants.*/
- *(.rodata)
- *(.rodata*)
- } >FLASH
+ . = ALIGN(4);
+ /* Constants.*/
+ *(.rodata)
+ *(.rodata*)
+ } >FLASH
- /* Explicitly initialized global and static data. (.data)*/
- .static_init_ram : ALIGN(4)
- {
- *(.data)
- *(.data*)
- . = ALIGN(4);
- } >RAM AT> FLASH
+ /* Explicitly initialized global and static data. (.data)*/
+ .static_init_ram : ALIGN(4)
+ {
+ *(.data)
+ *(.data*)
+ . = ALIGN(4);
+ } >RAM AT> FLASH
- /* Zero initialized global/static data. (.bss) */
- .zero_init_ram (NOLOAD) : ALIGN(4)
- {
- *(.bss)
- *(.bss*)
- *(COMMON)
- . = ALIGN(4);
- } >RAM
- }
+ /* Zero initialized global/static data. (.bss) */
+ .zero_init_ram (NOLOAD) : ALIGN(4)
+ {
+ *(.bss)
+ *(.bss*)
+ *(COMMON)
+ . = ALIGN(4);
+ } >RAM
+ }
Could be modified as follows enable ``Free Space`` reporting:
.. code-block::
- MEMORY
- {
- FLASH(rx) : ORIGIN = PW_BOOT_FLASH_BEGIN, LENGTH = PW_BOOT_FLASH_SIZE
- RAM(rwx) : ORIGIN = PW_BOOT_RAM_BEGIN, LENGTH = PW_BOOT_RAM_SIZE
+ MEMORY
+ {
+ FLASH(rx) : ORIGIN = PW_BOOT_FLASH_BEGIN, LENGTH = PW_BOOT_FLASH_SIZE
+ RAM(rwx) : ORIGIN = PW_BOOT_RAM_BEGIN, LENGTH = PW_BOOT_RAM_SIZE
- /* Each memory region above has an associated .*.unused_space section that
- * overlays the unused space at the end of the memory segment. These
- * segments are used by pw_bloat.bloaty_config to create the utilization
- * data source for bloaty size reports.
- *
- * These sections MUST be located immediately after the last section that is
- * placed in the respective memory region or lld will issue a warning like:
- *
- * warning: ignoring memory region assignment for non-allocatable section
- * '.VECTOR_TABLE.unused_space'
- *
- * If this warning occurs, it's also likely that LLD will have created quite
- * large padded regions in the ELF file due to bad cursor operations. This
- * can cause ELF files to balloon from hundreds of kilobytes to hundreds of
- * megabytes.
- *
- * Attempting to add sections to the memory region AFTER the unused_space
- * section will cause the region to overflow.
- */
- }
+ /* Each memory region above has an associated .*.unused_space section that
+ * overlays the unused space at the end of the memory segment. These
+ * segments are used by pw_bloat.bloaty_config to create the utilization
+ * data source for bloaty size reports.
+ *
+ * These sections MUST be located immediately after the last section that is
+ * placed in the respective memory region or lld will issue a warning like:
+ *
+ * warning: ignoring memory region assignment for non-allocatable section
+ * '.VECTOR_TABLE.unused_space'
+ *
+ * If this warning occurs, it's also likely that LLD will have created quite
+ * large padded regions in the ELF file due to bad cursor operations. This
+ * can cause ELF files to balloon from hundreds of kilobytes to hundreds of
+ * megabytes.
+ *
+ * Attempting to add sections to the memory region AFTER the unused_space
+ * section will cause the region to overflow.
+ */
+ }
- SECTIONS
- {
- /* Main executable code. */
- .code : ALIGN(4)
- {
- /* Application code. */
- *(.text)
- *(.text*)
- KEEP(*(.init))
- KEEP(*(.fini))
+ SECTIONS
+ {
+ /* Main executable code. */
+ .code : ALIGN(4)
+ {
+ /* Application code. */
+ *(.text)
+ *(.text*)
+ KEEP(*(.init))
+ KEEP(*(.fini))
- . = ALIGN(4);
- /* Constants.*/
- *(.rodata)
- *(.rodata*)
- } >FLASH
+ . = ALIGN(4);
+ /* Constants.*/
+ *(.rodata)
+ *(.rodata*)
+ } >FLASH
- /* Explicitly initialized global and static data. (.data)*/
- .static_init_ram : ALIGN(4)
- {
- *(.data)
- *(.data*)
- . = ALIGN(4);
- } >RAM AT> FLASH
+ /* Explicitly initialized global and static data. (.data)*/
+ .static_init_ram : ALIGN(4)
+ {
+ *(.data)
+ *(.data*)
+ . = ALIGN(4);
+ } >RAM AT> FLASH
- /* Defines a section representing the unused space in the FLASH segment.
- * This MUST be the last section assigned to the FLASH region.
- */
- PW_BLOAT_UNUSED_SPACE(FLASH)
+ /* Defines a section representing the unused space in the FLASH segment.
+ * This MUST be the last section assigned to the FLASH region.
+ */
+ PW_BLOAT_UNUSED_SPACE(FLASH)
- /* Zero initialized global/static data. (.bss). */
- .zero_init_ram (NOLOAD) : ALIGN(4)
- {
- *(.bss)
- *(.bss*)
- *(COMMON)
- . = ALIGN(4);
- } >RAM
+ /* Zero initialized global/static data. (.bss). */
+ .zero_init_ram (NOLOAD) : ALIGN(4)
+ {
+ *(.bss)
+ *(.bss*)
+ *(COMMON)
+ . = ALIGN(4);
+ } >RAM
- /* Defines a section representing the unused space in the RAM segment. This
- * MUST be the last section assigned to the RAM region.
- */
- PW_BLOAT_UNUSED_SPACE(RAM)
- }
+ /* Defines a section representing the unused space in the RAM segment. This
+ * MUST be the last section assigned to the RAM region.
+ */
+ PW_BLOAT_UNUSED_SPACE(RAM)
+ }
The preprocessor macro ``PW_BLOAT_UNUSED_SPACE`` is defined in
``pw_bloat/bloat_macros.ld``. To use these macros include this file in your
@@ -518,7 +518,7 @@
.. code-block::
- PW_BLOAT_MEMORY_REGION(FLASH)
+ PW_BLOAT_MEMORY_REGION(FLASH)
As another example, if you have two aliased memory regions (``DCTM`` and
``ITCM``) into the same effective memory named you'd like to call ``RAM``, then
@@ -526,5 +526,6 @@
.. code-block::
- PW_BLOAT_MEMORY_REGION_MAP(RAM, ITCM)
- PW_BLOAT_MEMORY_REGION_MAP(RAM, DTCM)
+ PW_BLOAT_MEMORY_REGION_MAP(RAM, ITCM)
+ PW_BLOAT_MEMORY_REGION_MAP(RAM, DTCM)
+
diff --git a/pw_build/cmake.rst b/pw_build/cmake.rst
index dbcb636..11f3b75 100644
--- a/pw_build/cmake.rst
+++ b/pw_build/cmake.rst
@@ -107,12 +107,12 @@
.. code-block::
- CMake Error at pw_build/pigweed.cmake:257 (message):
- my_module.my_facade's INTERFACE dep "my_nonexistent_backend" is not
- a target.
- Call Stack (most recent call first):
- pw_build/pigweed.cmake:238:EVAL:1 (_pw_target_link_targets_deferred_check)
- CMakeLists.txt:DEFERRED
+ CMake Error at pw_build/pigweed.cmake:257 (message):
+ my_module.my_facade's INTERFACE dep "my_nonexistent_backend" is not
+ a target.
+ Call Stack (most recent call first):
+ pw_build/pigweed.cmake:238:EVAL:1 (_pw_target_link_targets_deferred_check)
+ CMakeLists.txt:DEFERRED
Toolchain setup
diff --git a/pw_build/gn.rst b/pw_build/gn.rst
index 02caa30..997bcbd 100644
--- a/pw_build/gn.rst
+++ b/pw_build/gn.rst
@@ -291,22 +291,22 @@
.. code-block::
- pw_cc_blob_library("foo_bar_blobs") {
- blobs: [
- {
- symbol_name: "kFooBlob"
- file_path: "${target_out_dir}/stuff/bin/foo.bin"
- },
- {
- symbol_name: "kBarBlob"
- file_path: "//stuff/bin/bar.bin"
- linker_section: ".bar_section"
- },
- ]
- out_header: "my/stuff/foo_bar_blobs.h"
- namespace: "my::stuff"
- deps = [ ":generate_foo_bin" ]
- }
+ pw_cc_blob_library("foo_bar_blobs") {
+ blobs: [
+ {
+ symbol_name: "kFooBlob"
+ file_path: "${target_out_dir}/stuff/bin/foo.bin"
+ },
+ {
+ symbol_name: "kBarBlob"
+ file_path: "//stuff/bin/bar.bin"
+ linker_section: ".bar_section"
+ },
+ ]
+ out_header: "my/stuff/foo_bar_blobs.h"
+ namespace: "my::stuff"
+ deps = [ ":generate_foo_bin" ]
+ }
.. note:: If the binary blobs are generated as part of the build, be sure to
list them as deps to the pw_cc_blob_library target.
@@ -315,38 +315,38 @@
.. code-block::
- #pragma once
+ #pragma once
- #include <array>
- #include <cstddef>
+ #include <array>
+ #include <cstddef>
- namespace my::stuff {
+ namespace my::stuff {
- extern const std::array<std::byte, 100> kFooBlob;
+ extern const std::array<std::byte, 100> kFooBlob;
- extern const std::array<std::byte, 50> kBarBlob;
+ extern const std::array<std::byte, 50> kBarBlob;
- } // namespace my::stuff
+ } // namespace my::stuff
**Generated Source**
.. code-block::
- #include "my/stuff/foo_bar_blobs.h"
+ #include "my/stuff/foo_bar_blobs.h"
- #include <array>
- #include <cstddef>
+ #include <array>
+ #include <cstddef>
- #include "pw_preprocessor/compiler.h"
+ #include "pw_preprocessor/compiler.h"
- namespace my::stuff {
+ namespace my::stuff {
- const std::array<std::byte, 100> kFooBlob = { ... };
+ const std::array<std::byte, 100> kFooBlob = { ... };
- PW_PLACE_IN_SECTION(".bar_section")
- const std::array<std::byte, 50> kBarBlob = { ... };
+ PW_PLACE_IN_SECTION(".bar_section")
+ const std::array<std::byte, 50> kBarBlob = { ... };
- } // namespace my::stuff
+ } // namespace my::stuff
.. _module-pw_build-facade:
@@ -369,12 +369,12 @@
.. code-block::
- # Declares ":foo" and ":foo.facade" GN targets
- pw_facade("foo") {
- backend = pw_log_BACKEND
- public_configs = [ ":public_include_path" ]
- public = [ "public/pw_foo/foo.h" ]
- }
+ # Declares ":foo" and ":foo.facade" GN targets
+ pw_facade("foo") {
+ backend = pw_log_BACKEND
+ public_configs = [ ":public_include_path" ]
+ public = [ "public/pw_foo/foo.h" ]
+ }
Low-level facades like ``pw_assert`` cannot express all of their dependencies
due to the potential for dependency cycles. Facades with this issue may require
@@ -651,13 +651,13 @@
.. code-block::
- "<TARGET_FILE(//foo/bar:static_lib)>"
+ "<TARGET_FILE(//foo/bar:static_lib)>"
might expand to
.. code-block::
- "/home/User/project_root/out/obj/foo/bar/static_lib.a"
+ "/home/User/project_root/out/obj/foo/bar/static_lib.a"
``TARGET_FILE`` parses the ``.ninja`` file for the GN target, so it should
always find the correct output file, regardless of the toolchain's or target's
@@ -682,14 +682,14 @@
.. code-block::
- "--database=<TARGET_FILE_IF_EXISTS(//alpha/bravo)>"
+ "--database=<TARGET_FILE_IF_EXISTS(//alpha/bravo)>"
If the ``//alpha/bravo`` target file exists, this might expand to the
following:
.. code-block::
- "--database=/home/User/project/out/obj/alpha/bravo/bravo.elf"
+ "--database=/home/User/project/out/obj/alpha/bravo/bravo.elf"
If the ``//alpha/bravo`` target file does not exist, the entire
``--database=`` argument is omitted from the script arguments.
@@ -705,31 +705,31 @@
.. code-block::
- "<TARGET_OBJECTS(//foo/bar:a_source_set)>"
+ "<TARGET_OBJECTS(//foo/bar:a_source_set)>"
might expand to multiple separate arguments:
.. code-block::
- "/home/User/project_root/out/obj/foo/bar/a_source_set.file_a.cc.o"
- "/home/User/project_root/out/obj/foo/bar/a_source_set.file_b.cc.o"
- "/home/User/project_root/out/obj/foo/bar/a_source_set.file_c.cc.o"
+ "/home/User/project_root/out/obj/foo/bar/a_source_set.file_a.cc.o"
+ "/home/User/project_root/out/obj/foo/bar/a_source_set.file_b.cc.o"
+ "/home/User/project_root/out/obj/foo/bar/a_source_set.file_c.cc.o"
Example
^^^^^^^
.. code-block::
- import("$dir_pw_build/python_action.gni")
+ import("$dir_pw_build/python_action.gni")
- pw_python_action("postprocess_main_image") {
- script = "py/postprocess_binary.py"
- args = [
- "--database",
- rebase_path("my/database.csv", root_build_dir),
- "--binary=<TARGET_FILE(//firmware/images:main)>",
- ]
- stamp = true
- }
+ pw_python_action("postprocess_main_image") {
+ script = "py/postprocess_binary.py"
+ args = [
+ "--database",
+ rebase_path("my/database.csv", root_build_dir),
+ "--binary=<TARGET_FILE(//firmware/images:main)>",
+ ]
+ stamp = true
+ }
.. _module-pw_build-evaluate-path-expressions:
@@ -766,40 +766,40 @@
.. code-block::
- import("$dir_pw_build/evaluate_path_expressions.gni")
+ import("$dir_pw_build/evaluate_path_expressions.gni")
- template("executable_with_artifacts") {
- executable("${target_name}.exe") {
- sources = invoker.sources
- if defined(invoker.deps) {
- deps = invoker.deps
- }
- }
+ template("executable_with_artifacts") {
+ executable("${target_name}.exe") {
+ sources = invoker.sources
+ if defined(invoker.deps) {
+ deps = invoker.deps
+ }
+ }
- _artifacts_input = "$target_gen_dir/${target_name}_artifacts.json.in"
- _artifacts_output = "$target_gen_dir/${target_name}_artifacts.json"
- _artifacts = {
- binary = "<TARGET_FILE(:${target_name}.exe)>"
- objects = "<TARGET_OBJECTS(:${target_name}.exe)>"
- }
- write_file(_artifacts_input, _artifacts, "json")
+ _artifacts_input = "$target_gen_dir/${target_name}_artifacts.json.in"
+ _artifacts_output = "$target_gen_dir/${target_name}_artifacts.json"
+ _artifacts = {
+ binary = "<TARGET_FILE(:${target_name}.exe)>"
+ objects = "<TARGET_OBJECTS(:${target_name}.exe)>"
+ }
+ write_file(_artifacts_input, _artifacts, "json")
- pw_evaluate_path_expressions("${target_name}.evaluate") {
- files = [
- {
- source = _artifacts_input
- dest = _artifacts_output
- },
- ]
- }
+ pw_evaluate_path_expressions("${target_name}.evaluate") {
+ files = [
+ {
+ source = _artifacts_input
+ dest = _artifacts_output
+ },
+ ]
+ }
- group(target_name) {
- deps = [
- ":${target_name}.exe",
- ":${target_name}.evaluate",
- ]
- }
- }
+ group(target_name) {
+ deps = [
+ ":${target_name}.exe",
+ ":${target_name}.evaluate",
+ ]
+ }
+ }
.. _module-pw_build-pw_exec:
@@ -890,18 +890,18 @@
^^^^^^^
.. code-block::
- import("$dir_pw_build/input_group.gni")
+ import("$dir_pw_build/input_group.gni")
- pw_input_group("foo_metadata") {
- metadata = {
- files = [
- "x.foo",
- "y.foo",
- "z.foo",
- ]
- }
- inputs = metadata.files
- }
+ pw_input_group("foo_metadata") {
+ metadata = {
+ files = [
+ "x.foo",
+ "y.foo",
+ "z.foo",
+ ]
+ }
+ inputs = metadata.files
+ }
Targets depending on ``foo_metadata`` will rebuild when any of the ``.foo``
files are modified.
@@ -941,53 +941,53 @@
.. code-block::
- source/
- ├── file1.txt
- ├── file2.txt
- ├── file3.txt
- └── some_dir/
- ├── file4.txt
- └── some_other_dir/
- └── file5.txt
+ source/
+ ├── file1.txt
+ ├── file2.txt
+ ├── file3.txt
+ └── some_dir/
+ ├── file4.txt
+ └── some_other_dir/
+ └── file5.txt
And we create the following build target:
.. code-block::
- import("$dir_pw_build/zip.gni")
+ import("$dir_pw_build/zip.gni")
- pw_zip("target_name") {
- inputs = [
- "//source/file1.txt > /", # Copied to the zip root dir.
- "//source/file2.txt > /renamed.txt", # File renamed.
- "//source/file3.txt > /bar/", # File moved to the /bar/ dir.
- ]
+ pw_zip("target_name") {
+ inputs = [
+ "//source/file1.txt > /", # Copied to the zip root dir.
+ "//source/file2.txt > /renamed.txt", # File renamed.
+ "//source/file3.txt > /bar/", # File moved to the /bar/ dir.
+ ]
- dirs = [
- "//source/some_dir/ > /bar/some_dir/", # All /some_dir/ contents copied
- # as /bar/some_dir/.
- ]
+ dirs = [
+ "//source/some_dir/ > /bar/some_dir/", # All /some_dir/ contents copied
+ # as /bar/some_dir/.
+ ]
- # Note on output: if the specific output directory isn't defined
- # (such as output = "zoo.zip") then the .zip will output to the
- # same directory as the BUILD.gn file that called the target.
- output = "//$target_out_dir/foo.zip" # Where the foo.zip will end up
- }
+ # Note on output: if the specific output directory isn't defined
+ # (such as output = "zoo.zip") then the .zip will output to the
+ # same directory as the BUILD.gn file that called the target.
+ output = "//$target_out_dir/foo.zip" # Where the foo.zip will end up
+ }
This will result in a ``.zip`` file called ``foo.zip`` stored in
``//$target_out_dir`` with the following structure:
.. code-block::
- foo.zip
- ├── bar/
- │ ├── file3.txt
- │ └── some_dir/
- │ ├── file4.txt
- │ └── some_other_dir/
- │ └── file5.txt
- ├── file1.txt
- └── renamed.txt
+ foo.zip
+ ├── bar/
+ │ ├── file3.txt
+ │ └── some_dir/
+ │ ├── file4.txt
+ │ └── some_other_dir/
+ │ └── file5.txt
+ ├── file1.txt
+ └── renamed.txt
.. _module-pw_build-relative-source-file-names:
@@ -1016,64 +1016,64 @@
.. code-block::
- project root
- ├── foo/
- │ ├── foo.h
- │ └── foo.cc
- ├── bar/
- │ ├── bar.h
- │ └── bar.cc
- ├── unused/
- │ ├── unused.h
- │ └── unused.cc
- └── main.cc
+ project root
+ ├── foo/
+ │ ├── foo.h
+ │ └── foo.cc
+ ├── bar/
+ │ ├── bar.h
+ │ └── bar.cc
+ ├── unused/
+ │ ├── unused.h
+ │ └── unused.cc
+ └── main.cc
And a BUILD.gn at the root:
.. code-block::
- pw_source_set("bar") {
- public_configs = [ ":bar_headers" ]
- public = [ "bar/bar.h" ]
- sources = [ "bar/bar.cc" ]
- }
+ pw_source_set("bar") {
+ public_configs = [ ":bar_headers" ]
+ public = [ "bar/bar.h" ]
+ sources = [ "bar/bar.cc" ]
+ }
- pw_source_set("foo") {
- public_configs = [ ":foo_headers" ]
- public = [ "foo/foo.h" ]
- sources = [ "foo/foo.cc" ]
- deps = [ ":bar" ]
- }
+ pw_source_set("foo") {
+ public_configs = [ ":foo_headers" ]
+ public = [ "foo/foo.h" ]
+ sources = [ "foo/foo.cc" ]
+ deps = [ ":bar" ]
+ }
- pw_source_set("unused") {
- public_configs = [ ":unused_headers" ]
- public = [ "unused/unused.h" ]
- sources = [ "unused/unused.cc" ]
- deps = [ ":bar" ]
- }
+ pw_source_set("unused") {
+ public_configs = [ ":unused_headers" ]
+ public = [ "unused/unused.h" ]
+ sources = [ "unused/unused.cc" ]
+ deps = [ ":bar" ]
+ }
- pw_executable("main") {
- sources = [ "main.cc" ]
- deps = [ ":foo" ]
- }
+ pw_executable("main") {
+ sources = [ "main.cc" ]
+ deps = [ ":foo" ]
+ }
- pw_relative_source_file_names("main_source_files") {
- deps = [ ":main" ]
- outputs = [ "$target_gen_dir/main_source_files.json" ]
- }
+ pw_relative_source_file_names("main_source_files") {
+ deps = [ ":main" ]
+ outputs = [ "$target_gen_dir/main_source_files.json" ]
+ }
The json file written to `out/gen/main_source_files.json` will contain:
.. code-block::
- [
- "bar/bar.cc",
- "bar/bar.h",
- "foo/foo.cc",
- "foo/foo.h",
- "main.cc"
- ]
+ [
+ "bar/bar.cc",
+ "bar/bar.h",
+ "foo/foo.cc",
+ "foo/foo.h",
+ "main.cc"
+ ]
Since ``unused`` isn't a transitive dependency of ``main``, its source files
are not included. Similarly, even though ``bar`` is not a direct dependency of
@@ -1294,16 +1294,16 @@
.. code-block::
- [51.3s] Building [8924/10690] ...
- [10.4s] c++ pw_strict_host_clang_debug/obj/pw_string/string_test.lib.string_test.cc.o
- [ 9.5s] ACTION //pw_console/py:py.lint.mypy(//pw_build/python_toolchain:python)
- [ 9.4s] ACTION //pw_console/py:py.lint.pylint(//pw_build/python_toolchain:python)
- [ 6.1s] clang-tidy ../pw_log_rpc/log_service.cc
- [ 6.1s] clang-tidy ../pw_log_rpc/log_service_test.cc
- [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain.cc
- [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain_test.cc
- [ 5.4s] c++ pw_strict_host_clang_debug/obj/BUILD_DIR/pw_strict_host_clang_debug/gen/pw...
- ... and 109 more
+ [51.3s] Building [8924/10690] ...
+ [10.4s] c++ pw_strict_host_clang_debug/obj/pw_string/string_test.lib.string_test.cc.o
+ [ 9.5s] ACTION //pw_console/py:py.lint.mypy(//pw_build/python_toolchain:python)
+ [ 9.4s] ACTION //pw_console/py:py.lint.pylint(//pw_build/python_toolchain:python)
+ [ 6.1s] clang-tidy ../pw_log_rpc/log_service.cc
+ [ 6.1s] clang-tidy ../pw_log_rpc/log_service_test.cc
+ [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain.cc
+ [ 6.1s] clang-tidy ../pw_log_rpc/rpc_log_drain_test.cc
+ [ 5.4s] c++ pw_strict_host_clang_debug/obj/BUILD_DIR/pw_strict_host_clang_debug/gen/pw...
+ ... and 109 more
This allows you to, at a glance, know what Ninja's currently building, which
targets are bottlenecking the rest of the build, and which targets are taking
diff --git a/pw_chrono_zephyr/docs.rst b/pw_chrono_zephyr/docs.rst
index 06760fd..9d3cafd 100644
--- a/pw_chrono_zephyr/docs.rst
+++ b/pw_chrono_zephyr/docs.rst
@@ -13,4 +13,4 @@
pw_chrono.system_clock
----------------------
To enable the ``system_clock`` facade, it is also required to add
-``CONFIG_PIGWEED_CHRONO_SYSTEM_CLOCK=y``.
\ No newline at end of file
+``CONFIG_PIGWEED_CHRONO_SYSTEM_CLOCK=y``.
diff --git a/pw_cli/docs.rst b/pw_cli/docs.rst
index 1f33612..c4aa8ac 100644
--- a/pw_cli/docs.rst
+++ b/pw_cli/docs.rst
@@ -61,44 +61,44 @@
.. code-block::
- {
- "pw": {
- "pw_cli": {
- "plugins": {
- "<plugin name>": {
- "module": "<module containing plugin>",
- "function": "<entry point for plugin>"
- },
- ...
- }
- }
- }
- }
+ {
+ "pw": {
+ "pw_cli": {
+ "plugins": {
+ "<plugin name>": {
+ "module": "<module containing plugin>",
+ "function": "<entry point for plugin>"
+ },
+ ...
+ }
+ }
+ }
+ }
The following example registers three commands:
.. code-block::
- {
- "pw": {
- "pw_cli": {
- "plugins": {
- "presubmit": {
- "module": "my_cool_project.tools",
- "function": "run_presubmit"
- },
- "test": {
- "module": "my_cool_project.testing",
- "function": "run_test"
- },
- "flash": {
- "module": "my_cool_project.flash",
- "function": "main"
- }
- }
- }
- }
- }
+ {
+ "pw": {
+ "pw_cli": {
+ "plugins": {
+ "presubmit": {
+ "module": "my_cool_project.tools",
+ "function": "run_presubmit"
+ },
+ "test": {
+ "module": "my_cool_project.testing",
+ "function": "run_test"
+ },
+ "flash": {
+ "module": "my_cool_project.flash",
+ "function": "main"
+ }
+ }
+ }
+ }
+ }
Defining a plugin function
--------------------------
@@ -328,10 +328,10 @@
.. code-block::
- # Comments start with "#". Blank lines are ignored.
- name_of_the_plugin module.name module_member
+ # Comments start with "#". Blank lines are ignored.
+ name_of_the_plugin module.name module_member
- another_plugin some_module some_function
+ another_plugin some_module some_function
These files are placed in the file system and apply similarly to Git's
``.gitignore`` files. From Python, these files are registered using
diff --git a/pw_docgen/docs.rst b/pw_docgen/docs.rst
index 004a18a..1361503 100644
--- a/pw_docgen/docs.rst
+++ b/pw_docgen/docs.rst
@@ -79,12 +79,12 @@
.. code-block::
- pw_doc_group("my_doc_group") {
- sources = [ "docs.rst" ]
- inputs = [ "face-with-tears-of-joy-emoji.svg" ]
- group_deps = [ ":sub_doc_group" ]
- report_deps = [ ":my_size_report" ]
- }
+ pw_doc_group("my_doc_group") {
+ sources = [ "docs.rst" ]
+ inputs = [ "face-with-tears-of-joy-emoji.svg" ]
+ group_deps = [ ":sub_doc_group" ]
+ report_deps = [ ":my_size_report" ]
+ }
pw_doc_gen
__________
@@ -111,14 +111,14 @@
.. code-block::
- pw_doc_gen("my_docs") {
- conf = "//my_docs/conf.py"
- index = "//my_docs/index.rst"
- output_directory = target_gen_dir
- deps = [
- "//my_module:my_doc_group",
- ]
- }
+ pw_doc_gen("my_docs") {
+ conf = "//my_docs/conf.py"
+ index = "//my_docs/index.rst"
+ output_directory = target_gen_dir
+ deps = [
+ "//my_module:my_doc_group",
+ ]
+ }
Generating Documentation
------------------------
@@ -131,16 +131,16 @@
.. code-block::
- pw_doc_gen("docs") {
- conf = "conf.py"
- index = "index.rst"
- output_directory = target_gen_dir
- deps = [
- "$dir_pw_bloat:docs",
- "$dir_pw_docgen:docs",
- "$dir_pw_preprocessor:docs",
- ]
- }
+ pw_doc_gen("docs") {
+ conf = "conf.py"
+ index = "index.rst"
+ output_directory = target_gen_dir
+ deps = [
+ "$dir_pw_bloat:docs",
+ "$dir_pw_docgen:docs",
+ "$dir_pw_preprocessor:docs",
+ ]
+ }
A documentation tree is created under the output directory. Each of the sources
and inputs in the target's dependency graph is copied under this tree in the
@@ -150,17 +150,17 @@
.. code-block::
- out/gen/docs/pw_docgen_tree/
- ├── conf.py
- ├── index.rst
- ├── pw_bloat
- │ ├── bloat.rst
- │ └── examples
- │ └── simple_bloat.rst
- ├── pw_docgen
- │ └── docgen.rst
- └── pw_preprocessor
- └── docs.rst
+ out/gen/docs/pw_docgen_tree/
+ ├── conf.py
+ ├── index.rst
+ ├── pw_bloat
+ │ ├── bloat.rst
+ │ └── examples
+ │ └── simple_bloat.rst
+ ├── pw_docgen
+ │ └── docgen.rst
+ └── pw_preprocessor
+ └── docs.rst
This is the documentation tree which gets passed to Sphinx to build HTML output.
Imports within documentation files must be relative to this structure. In
diff --git a/pw_doctor/docs.rst b/pw_doctor/docs.rst
index 1179984..bc0ad58 100644
--- a/pw_doctor/docs.rst
+++ b/pw_doctor/docs.rst
@@ -49,3 +49,4 @@
}
}
}
+
diff --git a/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst b/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst
index 3c7d9d4..b320c3d 100644
--- a/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst
+++ b/pw_fuzzer/guides/reproducing_oss_fuzz_bugs.rst
@@ -33,7 +33,7 @@
.. code-block::
- $ ./out/host/obj/pw_fuzzer/toy_fuzzer ~/Downloads/testcase
+ $ ./out/host/obj/pw_fuzzer/toy_fuzzer ~/Downloads/testcase
If you need to recreate the OSS-Fuzz environment locally, you can use its
documentation on `reproducing`_ issues.
@@ -42,22 +42,22 @@
.. code-block::
- $ python infra/helper.py pull_images
- $ python infra/helper.py build_image pigweed
- $ python infra/helper.py build_fuzzers --sanitizer <address/undefined> pigweed
+ $ python infra/helper.py pull_images
+ $ python infra/helper.py build_image pigweed
+ $ python infra/helper.py build_fuzzers --sanitizer <address/undefined> pigweed
With that environment, you can run the reproduce bugs using:
.. code-block::
- python infra/helper.py reproduce pigweed <pw_module>_<fuzzer_name> ~/Downloads/testcase
+ python infra/helper.py reproduce pigweed <pw_module>_<fuzzer_name> ~/Downloads/testcase
You can even verify fixes in your local source checkout:
.. code-block::
- $ python infra/helper.py build_fuzzers --sanitizer <address/undefined> pigweed $PW_ROOT
- $ python infra/helper.py reproduce pigweed <pw_module>_<fuzzer_name> ~/Downloads/testcase
+ $ python infra/helper.py build_fuzzers --sanitizer <address/undefined> pigweed $PW_ROOT
+ $ python infra/helper.py reproduce pigweed <pw_module>_<fuzzer_name> ~/Downloads/testcase
.. _Monorail instance: https://bugs.chromium.org/p/oss-fuzz
.. _OSS-Fuzz: https://github.com/google/oss-fuzz
diff --git a/pw_i2c_linux/docs.rst b/pw_i2c_linux/docs.rst
index 2808a9f..9659d9b 100644
--- a/pw_i2c_linux/docs.rst
+++ b/pw_i2c_linux/docs.rst
@@ -81,4 +81,4 @@
=======
Only 7-bit addresses are supported right now, but it should be possible to add
support for 10-bit addresses with minimal changes - as long as the Linux driver
-supports 10-bit addresses.
\ No newline at end of file
+supports 10-bit addresses.
diff --git a/pw_log_tokenized/docs.rst b/pw_log_tokenized/docs.rst
index cd5a105..4f7cdbc 100644
--- a/pw_log_tokenized/docs.rst
+++ b/pw_log_tokenized/docs.rst
@@ -55,7 +55,7 @@
.. code-block::
- "■key1♦contents1■key2♦contents2■key3♦contents3"
+ "■key1♦contents1■key2♦contents2■key3♦contents3"
This format makes the message easily machine parseable and human readable. It is
extremely unlikely to conflict with log message contents due to the characters
@@ -67,7 +67,7 @@
.. code-block::
- "■msg♦Hyperdrive %d set to %f■module♦engine■file♦propulsion/hyper.cc"
+ "■msg♦Hyperdrive %d set to %f■module♦engine■file♦propulsion/hyper.cc"
Using key-value pairs allows placing the fields in any order.
``pw_log_tokenized`` places the message first. This is prefered when tokenizing
diff --git a/pw_log_zephyr/docs.rst b/pw_log_zephyr/docs.rst
index 975a53f..62638e0 100644
--- a/pw_log_zephyr/docs.rst
+++ b/pw_log_zephyr/docs.rst
@@ -35,9 +35,9 @@
.. code-block::
- add_library(log_tokenized_config INTERFACE)
- target_compile_options(log_tokenized_config INTERFACE -include header_file_that_sets_that_macro.h)
- pw_set_module_config(pw_log_tokenized_CONFIG log_tokenized_config)
+ add_library(log_tokenized_config INTERFACE)
+ target_compile_options(log_tokenized_config INTERFACE -include header_file_that_sets_that_macro.h)
+ pw_set_module_config(pw_log_tokenized_CONFIG log_tokenized_config)
Setting the log level
---------------------
diff --git a/pw_metric/docs.rst b/pw_metric/docs.rst
index ca23d45..21360dd 100644
--- a/pw_metric/docs.rst
+++ b/pw_metric/docs.rst
@@ -46,23 +46,23 @@
.. code-block::
- #include "pw_metric/metric.h"
+ #include "pw_metric/metric.h"
- class MySubsystem {
- public:
- void DoSomething() {
- attempts_.Increment();
- if (ActionSucceeds()) {
- successes_.Increment();
- }
- }
- Group& metrics() { return metrics_; }
+ class MySubsystem {
+ public:
+ void DoSomething() {
+ attempts_.Increment();
+ if (ActionSucceeds()) {
+ successes_.Increment();
+ }
+ }
+ Group& metrics() { return metrics_; }
- private:
- PW_METRIC_GROUP(metrics_, "my_subsystem");
- PW_METRIC(metrics_, attempts_, "attempts", 0u);
- PW_METRIC(metrics_, successes_, "successes", 0u);
- };
+ private:
+ PW_METRIC_GROUP(metrics_, "my_subsystem");
+ PW_METRIC(metrics_, attempts_, "attempts", 0u);
+ PW_METRIC(metrics_, successes_, "successes", 0u);
+ };
The metrics subsystem has no canonical output format at this time, but a JSON
dump might look something like this:
@@ -90,37 +90,37 @@
.. code-block::
- // This code was passed down from generations of developers before; no one
- // knows what it does or how it works. But it needs to be fixed!
- void OldCodeThatDoesntWorkButWeDontKnowWhy() {
- if (some_variable) {
- DoSomething();
- } else {
- DoSomethingElse();
- }
- }
+ // This code was passed down from generations of developers before; no one
+ // knows what it does or how it works. But it needs to be fixed!
+ void OldCodeThatDoesntWorkButWeDontKnowWhy() {
+ if (some_variable) {
+ DoSomething();
+ } else {
+ DoSomethingElse();
+ }
+ }
**After instrumenting:**
.. code-block::
- #include "pw_metric/global.h"
- #include "pw_metric/metric.h"
+ #include "pw_metric/global.h"
+ #include "pw_metric/metric.h"
- PW_METRIC_GLOBAL(legacy_do_something, "legacy_do_something");
- PW_METRIC_GLOBAL(legacy_do_something_else, "legacy_do_something_else");
+ PW_METRIC_GLOBAL(legacy_do_something, "legacy_do_something");
+ PW_METRIC_GLOBAL(legacy_do_something_else, "legacy_do_something_else");
- // This code was passed down from generations of developers before; no one
- // knows what it does or how it works. But it needs to be fixed!
- void OldCodeThatDoesntWorkButWeDontKnowWhy() {
- if (some_variable) {
- legacy_do_something.Increment();
- DoSomething();
- } else {
- legacy_do_something_else.Increment();
- DoSomethingElse();
- }
- }
+ // This code was passed down from generations of developers before; no one
+ // knows what it does or how it works. But it needs to be fixed!
+ void OldCodeThatDoesntWorkButWeDontKnowWhy() {
+ if (some_variable) {
+ legacy_do_something.Increment();
+ DoSomething();
+ } else {
+ legacy_do_something_else.Increment();
+ DoSomethingElse();
+ }
+ }
In this case, the developer merely had to add the metrics header, define some
metrics, and then start incrementing them. These metrics will be available
diff --git a/pw_package/docs.rst b/pw_package/docs.rst
index a7cb2c9..8d2e579 100644
--- a/pw_package/docs.rst
+++ b/pw_package/docs.rst
@@ -142,3 +142,4 @@
}
}
}
+
diff --git a/pw_perf_test/docs.rst b/pw_perf_test/docs.rst
index 4bca8c7..5d3fb6e 100644
--- a/pw_perf_test/docs.rst
+++ b/pw_perf_test/docs.rst
@@ -219,11 +219,11 @@
.. code-block::
- import("$dir_pw_perf_test/perf_test.gni")
+ import("$dir_pw_perf_test/perf_test.gni")
- pw_perf_test("foo_perf_test") {
- sources = [ "foo_perf_test.cc" ]
- }
+ pw_perf_test("foo_perf_test") {
+ sources = [ "foo_perf_test.cc" ]
+ }
.. note::
If you use ``pw_watch``, the template is configured to build automatically
@@ -251,12 +251,12 @@
.. code-block::
- import("$dir_pw_perf_test/perf_test.gni")
+ import("$dir_pw_perf_test/perf_test.gni")
- pw_perf_test("large_test") {
- sources = [ "large_test.cc" ]
- enable_if = device_has_1m_flash
- }
+ pw_perf_test("large_test") {
+ sources = [ "large_test.cc" ]
+ enable_if = device_has_1m_flash
+ }
Grouping
--------
@@ -267,22 +267,22 @@
.. code-block::
- import("$dir_pw_perf_test/perf_test.gni")
+ import("$dir_pw_perf_test/perf_test.gni")
- pw_perf_test("foo_test") {
- sources = [ "foo.cc" ]
- }
+ pw_perf_test("foo_test") {
+ sources = [ "foo.cc" ]
+ }
- pw_perf_test("bar_test") {
- sources = [ "bar.cc" ]
- }
+ pw_perf_test("bar_test") {
+ sources = [ "bar.cc" ]
+ }
- group("my_perf_tests_collection") {
- deps = [
- ":foo_test",
- ":bar_test",
- ]
- }
+ group("my_perf_tests_collection") {
+ deps = [
+ ":foo_test",
+ ":bar_test",
+ ]
+ }
Running
-------
@@ -310,15 +310,15 @@
.. code-block::
- load(
- "//pw_build:pigweed.bzl",
- "pw_cc_test",
- )
+ load(
+ "//pw_build:pigweed.bzl",
+ "pw_cc_test",
+ )
- pw_cc_perf_test(
- name = "foo_test",
- srcs = ["foo_perf_test.cc"],
- )
+ pw_cc_perf_test(
+ name = "foo_test",
+ srcs = ["foo_perf_test.cc"],
+ )
Running
-------
diff --git a/pw_presubmit/py/BUILD.gn b/pw_presubmit/py/BUILD.gn
index 2b452c3..c00935d 100644
--- a/pw_presubmit/py/BUILD.gn
+++ b/pw_presubmit/py/BUILD.gn
@@ -43,6 +43,7 @@
"pw_presubmit/presubmit.py",
"pw_presubmit/presubmit_context.py",
"pw_presubmit/python_checks.py",
+ "pw_presubmit/rst_format.py",
"pw_presubmit/shell_checks.py",
"pw_presubmit/source_in_build.py",
"pw_presubmit/todo_check.py",
diff --git a/pw_presubmit/py/pw_presubmit/format_code.py b/pw_presubmit/py/pw_presubmit/format_code.py
index d773b4e..959bf50 100755
--- a/pw_presubmit/py/pw_presubmit/format_code.py
+++ b/pw_presubmit/py/pw_presubmit/format_code.py
@@ -65,6 +65,7 @@
presubmit_context,
)
from pw_presubmit.tools import exclude_paths, file_summary, log_run, plural
+from pw_presubmit.rst_format import reformat_rst
_LOG: logging.Logger = logging.getLogger(__name__)
_COLOR = pw_cli.color.colors()
@@ -461,6 +462,24 @@
return {}
+def rst_format_check(ctx: _Context) -> Dict[Path, str]:
+ errors = {}
+ for path in ctx.paths:
+ result = reformat_rst(path, diff=True, in_place=False)
+ if result:
+ errors[path] = ''.join(result)
+ return errors
+
+
+def rst_format_fix(ctx: _Context) -> Dict[Path, str]:
+ errors = {}
+ for path in ctx.paths:
+ result = reformat_rst(path, diff=True, in_place=True)
+ if result:
+ errors[path] = ''.join(result)
+ return errors
+
+
def print_format_check(
errors: Dict[Path, str],
show_fix_commands: bool,
@@ -595,8 +614,8 @@
RST_FORMAT: CodeFormat = CodeFormat(
'reStructuredText',
FileFilter(endswith=['.rst']),
- check_trailing_space,
- fix_trailing_space,
+ rst_format_check,
+ rst_format_fix,
)
MARKDOWN_FORMAT: CodeFormat = CodeFormat(
diff --git a/pw_presubmit/py/pw_presubmit/rst_format.py b/pw_presubmit/py/pw_presubmit/rst_format.py
new file mode 100644
index 0000000..4f2f955
--- /dev/null
+++ b/pw_presubmit/py/pw_presubmit/rst_format.py
@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+
+# Copyright 2023 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.
+"""Restructured Text Formatting."""
+
+import argparse
+from dataclasses import dataclass, field
+import difflib
+from functools import cached_property
+from pathlib import Path
+import textwrap
+from typing import List, Optional
+
+DEFAULT_TAB_WIDTH = 8
+CODE_BLOCK_INDENTATION = 3
+
+
+def _parse_args():
+ parser = argparse.ArgumentParser(description=__doc__)
+
+ parser.add_argument(
+ '--tab-width',
+ default=DEFAULT_TAB_WIDTH,
+ help='Number of spaces to use when converting tab characters.',
+ )
+ parser.add_argument(
+ '--diff',
+ action='store_true',
+ help='Print a diff of formatting changes.',
+ )
+ parser.add_argument(
+ '-i',
+ '--in-place',
+ action='store_true',
+ help='Replace existing file with the reformatted copy.',
+ )
+ parser.add_argument(
+ 'rst_files',
+ nargs='+',
+ default=[],
+ type=Path,
+ help='Paths to rst files.',
+ )
+
+ return parser.parse_args()
+
+
+def _indent_amount(line: str) -> int:
+ return len(line) - len(line.lstrip())
+
+
+def _reindent(input_text: str, amount: int) -> str:
+ text = ''
+ for line in textwrap.dedent(input_text).splitlines():
+ if len(line.strip()) == 0:
+ text += '\n'
+ continue
+ text += ' ' * amount
+ text += line
+ text += '\n'
+ return text
+
+
+@dataclass
+class CodeBlock:
+ """Store a single code block."""
+
+ directive_lineno: int
+ directive_line: str
+ first_line_indent: Optional[int] = None
+ end_lineno: Optional[int] = None
+ option_lines: List[str] = field(default_factory=list)
+ code_lines: List[str] = field(default_factory=list)
+
+ def __post_init__(self) -> None:
+ self._blank_line_after_options_found = False
+
+ def finished(self) -> bool:
+ return self.end_lineno is not None
+
+ def append_line(self, index: int, line: str) -> None:
+ """Process a line for this code block."""
+ # Check if outside the code block (indentation is less):
+ if (
+ self.first_line_indent is not None
+ and len(line.strip()) > 0
+ and _indent_amount(line) < self.first_line_indent
+ ):
+ # Code block ended
+ self.end_lineno = index
+ return
+
+ # If first line indent hasn't been found
+ if self.first_line_indent is None:
+ # Check if the first word is a directive option.
+ # E.g. :caption:
+ line_words = line.split()
+ if (
+ line_words
+ and line_words[0].startswith(':')
+ and line_words[0].endswith(':')
+ ):
+ self.option_lines.append(line.rstrip())
+ return
+ # Check for a blank line
+ if len(line.strip()) == 0:
+ if (
+ self.option_lines
+ and not self._blank_line_after_options_found
+ ):
+ self._blank_line_after_options_found = True
+ return
+ # Check for a line that is a continuation of a previous option.
+ if self.option_lines and not self._blank_line_after_options_found:
+ self.option_lines.append(line.rstrip())
+ return
+
+ self.first_line_indent = _indent_amount(line)
+
+ # Save this line as code.
+ self.code_lines.append(line.rstrip())
+
+ @cached_property
+ def directive_indent_amount(self) -> int:
+ return _indent_amount(self.directive_line)
+
+ def options_block_text(self) -> str:
+ return _reindent(
+ input_text='\n'.join(self.option_lines),
+ amount=self.directive_indent_amount + CODE_BLOCK_INDENTATION,
+ )
+
+ def code_block_text(self) -> str:
+ return _reindent(
+ input_text='\n'.join(self.code_lines),
+ amount=self.directive_indent_amount + CODE_BLOCK_INDENTATION,
+ )
+
+ def to_text(self) -> str:
+ text = ''
+ text += self.directive_line
+ if self.option_lines:
+ text += self.options_block_text()
+ text += '\n'
+ text += self.code_block_text()
+ text += '\n'
+ return text
+
+ def __repr__(self) -> str:
+ return self.to_text()
+
+
+def _strip_trailing_whitespace(line: str) -> str:
+ return line.rstrip() + '\n'
+
+
+def reindent_code_blocks(in_text: str) -> str:
+ """Reindent code blocks to 3 spaces."""
+ out_text = ''
+ current_block: Optional[CodeBlock] = None
+ for index, line in enumerate(in_text.splitlines(keepends=True)):
+ # If a code block is active, process this line.
+ if current_block:
+ current_block.append_line(index, line)
+ if current_block.finished():
+ out_text += current_block.to_text()
+ # This line wasn't part of the code block, process as normal.
+ out_text += _strip_trailing_whitespace(line)
+ # Erase this code_block variable
+ current_block = None
+ # Check for new code block start
+ elif line.lstrip().startswith('.. code') and line.rstrip().endswith(
+ '::'
+ ):
+ current_block = CodeBlock(
+ directive_lineno=index, directive_line=line
+ )
+ continue
+ else:
+ out_text += _strip_trailing_whitespace(line)
+ # If the document ends with a code block it may still need to be written.
+ if current_block is not None:
+ out_text += current_block.to_text()
+ return out_text
+
+
+def reformat_rst(
+ file_name: Path,
+ diff: bool = False,
+ in_place: bool = False,
+ tab_width: int = DEFAULT_TAB_WIDTH,
+) -> List[str]:
+ """Reformat an rst file.
+
+ Returns a list of diff lines."""
+ in_text = file_name.read_text()
+
+ # Replace tabs with spaces
+ out_text = in_text.replace('\t', ' ' * tab_width)
+
+ # Indent .. code-block:: directives.
+ out_text = reindent_code_blocks(in_text)
+
+ result_diff = list(
+ difflib.unified_diff(
+ in_text.splitlines(True),
+ out_text.splitlines(True),
+ f'{file_name} (original)',
+ f'{file_name} (reformatted)',
+ )
+ )
+ if diff and result_diff:
+ print(''.join(result_diff))
+
+ if in_place:
+ file_name.write_text(out_text)
+
+ return result_diff
+
+
+def rst_format_main(
+ rst_files: List[Path],
+ diff: bool = False,
+ in_place: bool = False,
+ tab_width: int = DEFAULT_TAB_WIDTH,
+) -> None:
+ for rst_file in rst_files:
+ reformat_rst(rst_file, diff, in_place, tab_width)
+
+
+if __name__ == '__main__':
+ rst_format_main(**vars(_parse_args()))
diff --git a/pw_rpc/nanopb/docs.rst b/pw_rpc/nanopb/docs.rst
index 500bde3..4ae7ded 100644
--- a/pw_rpc/nanopb/docs.rst
+++ b/pw_rpc/nanopb/docs.rst
@@ -18,23 +18,23 @@
.. code-block::
- # chat/BUILD.gn
+ # chat/BUILD.gn
- import("$dir_pw_build/target_types.gni")
- import("$dir_pw_protobuf_compiler/proto.gni")
+ import("$dir_pw_build/target_types.gni")
+ import("$dir_pw_protobuf_compiler/proto.gni")
- pw_proto_library("chat_protos") {
- sources = [ "chat_protos/chat_service.proto" ]
- }
+ pw_proto_library("chat_protos") {
+ sources = [ "chat_protos/chat_service.proto" ]
+ }
- # Library that implements the Chat service.
- pw_source_set("chat_service") {
- sources = [
- "chat_service.cc",
- "chat_service.h",
- ]
- public_deps = [ ":chat_protos.nanopb_rpc" ]
- }
+ # Library that implements the Chat service.
+ pw_source_set("chat_service") {
+ sources = [
+ "chat_service.cc",
+ "chat_service.h",
+ ]
+ public_deps = [ ":chat_protos.nanopb_rpc" ]
+ }
A C++ header file is generated for each input .proto file, with the ``.proto``
extension replaced by ``.rpc.pb.h``. For example, given the input file
diff --git a/pw_rpc/pwpb/docs.rst b/pw_rpc/pwpb/docs.rst
index bdc65b0..7c45067 100644
--- a/pw_rpc/pwpb/docs.rst
+++ b/pw_rpc/pwpb/docs.rst
@@ -14,23 +14,23 @@
.. code-block::
- # chat/BUILD.gn
+ # chat/BUILD.gn
- import("$dir_pw_build/target_types.gni")
- import("$dir_pw_protobuf_compiler/proto.gni")
+ import("$dir_pw_build/target_types.gni")
+ import("$dir_pw_protobuf_compiler/proto.gni")
- pw_proto_library("chat_protos") {
- sources = [ "chat_protos/chat_service.proto" ]
- }
+ pw_proto_library("chat_protos") {
+ sources = [ "chat_protos/chat_service.proto" ]
+ }
- # Library that implements the Chat service.
- pw_source_set("chat_service") {
- sources = [
- "chat_service.cc",
- "chat_service.h",
- ]
- public_deps = [ ":chat_protos.pwpb_rpc" ]
- }
+ # Library that implements the Chat service.
+ pw_source_set("chat_service") {
+ sources = [
+ "chat_service.cc",
+ "chat_service.h",
+ ]
+ public_deps = [ ":chat_protos.pwpb_rpc" ]
+ }
A C++ header file is generated for each input .proto file, with the ``.proto``
extension replaced by ``.rpc.pwpb.h``. For example, given the input file
diff --git a/pw_snapshot/proto_format.rst b/pw_snapshot/proto_format.rst
index 14e450d..ef1a865 100644
--- a/pw_snapshot/proto_format.rst
+++ b/pw_snapshot/proto_format.rst
@@ -10,19 +10,19 @@
.. code-block::
- // This message uses field numbers 1, 2, and 3.
- message BasicLog {
- string message = 1;
- LogLevel level = 2;
- int64 timestamp = 3;
- }
+ // This message uses field numbers 1, 2, and 3.
+ message BasicLog {
+ string message = 1;
+ LogLevel level = 2;
+ int64 timestamp = 3;
+ }
- // This message uses field numbers 16 and 17, which are mutually exclusive
- // to the numbers used in BasicLog.
- message ExtendedLog {
- string file_name = 16;
- uint32 line_nubmer = 17;
- }
+ // This message uses field numbers 16 and 17, which are mutually exclusive
+ // to the numbers used in BasicLog.
+ message ExtendedLog {
+ string file_name = 16;
+ uint32 line_nubmer = 17;
+ }
In the above example, a BasicLog and ExtendedLog can be encoded to the same
buffer and then be decoded without causing any problems. What breaks
@@ -32,24 +32,24 @@
.. code-block::
- message BasicLog {
- string message = 1;
- LogLevel level = 2;
- int64 timestamp = 3;
+ message BasicLog {
+ string message = 1;
+ LogLevel level = 2;
+ int64 timestamp = 3;
- // ExtendedLog uses these field numbers. These field numbers should never
- // be used by BasicLog.
- reserved 16 to max;
- }
+ // ExtendedLog uses these field numbers. These field numbers should never
+ // be used by BasicLog.
+ reserved 16 to max;
+ }
- message ExtendedLog {
- // BasicLog uses these field numbers. These field numbers should never
- // be used by ExtendedLog.
- reserved 1 to 15;
+ message ExtendedLog {
+ // BasicLog uses these field numbers. These field numbers should never
+ // be used by ExtendedLog.
+ reserved 1 to 15;
- string file_name = 16;
- uint32 line_nubmer = 17;
- }
+ string file_name = 16;
+ uint32 line_nubmer = 17;
+ }
This is exactly how the Snapshot proto is set up. While a SnapshotMetadata proto
message provides a good portion of the valuable snapshot contents, the larger
@@ -69,21 +69,21 @@
Example:
.. code-block::
- // snapshot.proto
- message Snapshot {
- ...
- // Information about allocated Thread.
- repeated pw.thread.Thread threads = 18;
- }
+ // snapshot.proto
+ message Snapshot {
+ ...
+ // Information about allocated Thread.
+ repeated pw.thread.Thread threads = 18;
+ }
- // thread.proto
+ // thread.proto
- // This message overlays the pw.snapshot.Snapshot proto. It's valid to encode
- // this message to the same sink that a Snapshot proto is being written to.
- message SnapshotThread {
- // Thread information.
- repeated pw.thread.Thread threads = 18;
- }
+ // This message overlays the pw.snapshot.Snapshot proto. It's valid to encode
+ // this message to the same sink that a Snapshot proto is being written to.
+ message SnapshotThread {
+ // Thread information.
+ repeated pw.thread.Thread threads = 18;
+ }
It is **critical** that the SnapshotThread message is in sync with the larger
Snapshot proto. If the type or field numbers are different, the proto decode
diff --git a/pw_system/docs.rst b/pw_system/docs.rst
index e2d289d..1d446ee 100644
--- a/pw_system/docs.rst
+++ b/pw_system/docs.rst
@@ -79,78 +79,78 @@
.. code-block::
- # Declare a toolchain with suggested, compiler, compiler flags, and default
- # backends.
- pw_system_target("stm32f429i_disc1_stm32cube_size_optimized") {
- # These options drive the logic for automatic configuration by this
- # template.
- cpu = PW_SYSTEM_CPU.CORTEX_M4F
- scheduler = PW_SYSTEM_SCHEDULER.FREERTOS
+ # Declare a toolchain with suggested, compiler, compiler flags, and default
+ # backends.
+ pw_system_target("stm32f429i_disc1_stm32cube_size_optimized") {
+ # These options drive the logic for automatic configuration by this
+ # template.
+ cpu = PW_SYSTEM_CPU.CORTEX_M4F
+ scheduler = PW_SYSTEM_SCHEDULER.FREERTOS
- # Optionally, override pw_system's defaults to build with clang.
- system_toolchain = pw_toolchain_arm_clang
+ # Optionally, override pw_system's defaults to build with clang.
+ system_toolchain = pw_toolchain_arm_clang
- # The pre_init source set provides things like the interrupt vector table,
- # pre-main init, and provision of FreeRTOS hooks.
- link_deps = [ "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:pre_init" ]
+ # The pre_init source set provides things like the interrupt vector table,
+ # pre-main init, and provision of FreeRTOS hooks.
+ link_deps = [ "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:pre_init" ]
- # These are hardware-specific options that set up this particular board.
- # These are declared in ``declare_args()`` blocks throughout Pigweed. Any
- # build arguments set by the user will be overridden by these settings.
- build_args = {
- pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:stm32f4xx_freertos_config"
- pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm4f"
- pw_sys_io_BACKEND = dir_pw_sys_io_stm32cube
- dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4
- pw_third_party_stm32cube_PRODUCT = "STM32F429xx"
- pw_third_party_stm32cube_CONFIG =
- "//targets/stm32f429i_disc1_stm32cube:stm32f4xx_hal_config"
- pw_third_party_stm32cube_CORE_INIT = ""
- pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
- "PW_BOOT_FLASH_BEGIN=0x08000200",
- "PW_BOOT_FLASH_SIZE=2048K",
- "PW_BOOT_HEAP_SIZE=7K",
- "PW_BOOT_MIN_STACK_SIZE=1K",
- "PW_BOOT_RAM_BEGIN=0x20000000",
- "PW_BOOT_RAM_SIZE=192K",
- "PW_BOOT_VECTOR_TABLE_BEGIN=0x08000000",
- "PW_BOOT_VECTOR_TABLE_SIZE=512",
- ]
- }
- }
+ # These are hardware-specific options that set up this particular board.
+ # These are declared in ``declare_args()`` blocks throughout Pigweed. Any
+ # build arguments set by the user will be overridden by these settings.
+ build_args = {
+ pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/stm32f429i_disc1_stm32cube:stm32f4xx_freertos_config"
+ pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm4f"
+ pw_sys_io_BACKEND = dir_pw_sys_io_stm32cube
+ dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4
+ pw_third_party_stm32cube_PRODUCT = "STM32F429xx"
+ pw_third_party_stm32cube_CONFIG =
+ "//targets/stm32f429i_disc1_stm32cube:stm32f4xx_hal_config"
+ pw_third_party_stm32cube_CORE_INIT = ""
+ pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
+ "PW_BOOT_FLASH_BEGIN=0x08000200",
+ "PW_BOOT_FLASH_SIZE=2048K",
+ "PW_BOOT_HEAP_SIZE=7K",
+ "PW_BOOT_MIN_STACK_SIZE=1K",
+ "PW_BOOT_RAM_BEGIN=0x20000000",
+ "PW_BOOT_RAM_SIZE=192K",
+ "PW_BOOT_VECTOR_TABLE_BEGIN=0x08000000",
+ "PW_BOOT_VECTOR_TABLE_SIZE=512",
+ ]
+ }
+ }
- # Example for the Emcraft SmartFusion2 system-on-module
- pw_system_target("emcraft_sf2_som_size_optimized") {
- cpu = PW_SYSTEM_CPU.CORTEX_M3
- scheduler = PW_SYSTEM_SCHEDULER.FREERTOS
+ # Example for the Emcraft SmartFusion2 system-on-module
+ pw_system_target("emcraft_sf2_som_size_optimized") {
+ cpu = PW_SYSTEM_CPU.CORTEX_M3
+ scheduler = PW_SYSTEM_SCHEDULER.FREERTOS
- link_deps = [ "$dir_pigweed/targets/emcraft_sf2_som:pre_init" ]
- build_args = {
- pw_log_BACKEND = dir_pw_log_basic #dir_pw_log_tokenized
- pw_log_tokenized_HANDLER_BACKEND = "//pw_system:log"
- pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/emcraft_sf2_som:sf2_freertos_config"
- pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm3"
- pw_sys_io_BACKEND = dir_pw_sys_io_emcraft_sf2
- dir_pw_third_party_smartfusion_mss = dir_pw_third_party_smartfusion_mss_exported
- pw_third_party_stm32cube_CONFIG =
- "//targets/emcraft_sf2_som:sf2_mss_hal_config"
- pw_third_party_stm32cube_CORE_INIT = ""
- pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
- "PW_BOOT_FLASH_BEGIN=0x00000200",
- "PW_BOOT_FLASH_SIZE=200K",
+ link_deps = [ "$dir_pigweed/targets/emcraft_sf2_som:pre_init" ]
+ build_args = {
+ pw_log_BACKEND = dir_pw_log_basic #dir_pw_log_tokenized
+ pw_log_tokenized_HANDLER_BACKEND = "//pw_system:log"
+ pw_third_party_freertos_CONFIG = "$dir_pigweed/targets/emcraft_sf2_som:sf2_freertos_config"
+ pw_third_party_freertos_PORT = "$dir_pw_third_party/freertos:arm_cm3"
+ pw_sys_io_BACKEND = dir_pw_sys_io_emcraft_sf2
+ dir_pw_third_party_smartfusion_mss = dir_pw_third_party_smartfusion_mss_exported
+ pw_third_party_stm32cube_CONFIG =
+ "//targets/emcraft_sf2_som:sf2_mss_hal_config"
+ pw_third_party_stm32cube_CORE_INIT = ""
+ pw_boot_cortex_m_LINK_CONFIG_DEFINES = [
+ "PW_BOOT_FLASH_BEGIN=0x00000200",
+ "PW_BOOT_FLASH_SIZE=200K",
- # TODO(b/235348465): Currently "pw_tokenizer/detokenize_test" requires at
- # least 6K bytes in heap when using pw_malloc_freelist. The heap size
- # required for tests should be investigated.
- "PW_BOOT_HEAP_SIZE=7K",
- "PW_BOOT_MIN_STACK_SIZE=1K",
- "PW_BOOT_RAM_BEGIN=0x20000000",
- "PW_BOOT_RAM_SIZE=64K",
- "PW_BOOT_VECTOR_TABLE_BEGIN=0x00000000",
- "PW_BOOT_VECTOR_TABLE_SIZE=512",
- ]
- }
- }
+ # TODO(b/235348465): Currently "pw_tokenizer/detokenize_test" requires at
+ # least 6K bytes in heap when using pw_malloc_freelist. The heap size
+ # required for tests should be investigated.
+ "PW_BOOT_HEAP_SIZE=7K",
+ "PW_BOOT_MIN_STACK_SIZE=1K",
+ "PW_BOOT_RAM_BEGIN=0x20000000",
+ "PW_BOOT_RAM_SIZE=64K",
+ "PW_BOOT_VECTOR_TABLE_BEGIN=0x00000000",
+ "PW_BOOT_VECTOR_TABLE_SIZE=512",
+ ]
+ }
+ }
-------
Metrics
diff --git a/pw_toolchain/docs.rst b/pw_toolchain/docs.rst
index 6d8250c..ac49ed7 100644
--- a/pw_toolchain/docs.rst
+++ b/pw_toolchain/docs.rst
@@ -85,12 +85,12 @@
.. code-block::
- static_analysis = {
- clang_tidy_path = "//third_party/ctcache/clang-tidy"
- _clang_tidy_cfg_path = rebase_path("//.clang-tidy", root_build_dir)
- cc_post = "echo '-: $_clang_tidy_cfg_path' >> {{output}}.d"
- cxx_post = "echo '-: $_clang_tidy_cfg_path' >> {{output}}.d"
- }
+ static_analysis = {
+ clang_tidy_path = "//third_party/ctcache/clang-tidy"
+ _clang_tidy_cfg_path = rebase_path("//.clang-tidy", root_build_dir)
+ cc_post = "echo '-: $_clang_tidy_cfg_path' >> {{output}}.d"
+ cxx_post = "echo '-: $_clang_tidy_cfg_path' >> {{output}}.d"
+ }
Excluding files from checks
===========================
diff --git a/pw_transfer/docs.rst b/pw_transfer/docs.rst
index 0be531c..2d60436 100644
--- a/pw_transfer/docs.rst
+++ b/pw_transfer/docs.rst
@@ -686,4 +686,5 @@
.. code-block::
- Cq-Include-Trybots: luci.pigweed.try:pigweed-integration-transfer
+ Cq-Include-Trybots: luci.pigweed.try:pigweed-integration-transfer
+
diff --git a/seed/0101-pigweed.json.rst b/seed/0101-pigweed.json.rst
index 271f0b1..0e207a6 100644
--- a/seed/0101-pigweed.json.rst
+++ b/seed/0101-pigweed.json.rst
@@ -27,26 +27,26 @@
.. code-block::
- {
- "root_variable": "<PROJNAME>_ROOT",
- "cipd_package_files": ["tools/default.json"],
- "virtualenv": {
- "gn_args": ["dir_pw_third_party_stm32cube=\"\""],
- "gn_root": ".",
- "gn_targets": [":python.install"]
- },
- "optional_submodules": ["vendor/shhh-secret"],
- "gni_file": "build_overrides/pigweed_environment.gni"
- }
+ {
+ "root_variable": "<PROJNAME>_ROOT",
+ "cipd_package_files": ["tools/default.json"],
+ "virtualenv": {
+ "gn_args": ["dir_pw_third_party_stm32cube=\"\""],
+ "gn_root": ".",
+ "gn_targets": [":python.install"]
+ },
+ "optional_submodules": ["vendor/shhh-secret"],
+ "gni_file": "build_overrides/pigweed_environment.gni"
+ }
The plugins to the ``pw`` command-line utility are configured in ``PW_PLUGINS``,
which looks like this:
.. code-block::
- # <name> <Python module> <function>
- console pw_console.__main__ main
- format pw_presubmit.format_code _pigweed_upstream_main
+ # <name> <Python module> <function>
+ console pw_console.__main__ main
+ format pw_presubmit.format_code _pigweed_upstream_main
In addition, changes have been proposed to configure some of the behavior of
``pw format`` and the formatting steps of ``pw presubmit`` from config files,
@@ -130,54 +130,54 @@
.. code-block::
- {
- "pw": {
- "pw_cli": {
- "plugins": {
- "console": {
- "module": "pw_console.__main__",
- "function": "main"
- },
- "format": {
- "module": "pw_presubmit.format_code",
- "function": "_pigweed_upstream_main"
- }
- }
- },
- "pw_env_setup": {
- "root_variable": "<PROJNAME>_ROOT",
- "rosetta": "allow",
- "gni_file": "build_overrides/pigweed_environment.gni",
- "cipd": {
- "package_files": [
- "tools/default.json"
- ]
- },
- "virtualenv": {
- "gn_args": [
- "dir_pw_third_party_stm32cube=\"\""
- ],
- "gn_targets": [
- "python.install"
- ],
- "gn_root": "."
- },
- "submodules": {
- "optional": [
- "vendor/shhh-secret"
- ]
- }
- },
- "pw_presubmit": {
- "format": {
- "python": {
- "formatter": "black",
- "black_path": "pyink"
- }
- }
- }
- }
- }
+ {
+ "pw": {
+ "pw_cli": {
+ "plugins": {
+ "console": {
+ "module": "pw_console.__main__",
+ "function": "main"
+ },
+ "format": {
+ "module": "pw_presubmit.format_code",
+ "function": "_pigweed_upstream_main"
+ }
+ }
+ },
+ "pw_env_setup": {
+ "root_variable": "<PROJNAME>_ROOT",
+ "rosetta": "allow",
+ "gni_file": "build_overrides/pigweed_environment.gni",
+ "cipd": {
+ "package_files": [
+ "tools/default.json"
+ ]
+ },
+ "virtualenv": {
+ "gn_args": [
+ "dir_pw_third_party_stm32cube=\"\""
+ ],
+ "gn_targets": [
+ "python.install"
+ ],
+ "gn_root": "."
+ },
+ "submodules": {
+ "optional": [
+ "vendor/shhh-secret"
+ ]
+ }
+ },
+ "pw_presubmit": {
+ "format": {
+ "python": {
+ "formatter": "black",
+ "black_path": "pyink"
+ }
+ }
+ }
+ }
+ }
Some teams will resist a new file at the root of their checkout, but this seed
won't be adding any files, it'll be combining at least one top-level file, maybe
diff --git a/targets/apollo4/target_docs.rst b/targets/apollo4/target_docs.rst
index b751c5d..7462be0 100644
--- a/targets/apollo4/target_docs.rst
+++ b/targets/apollo4/target_docs.rst
@@ -23,8 +23,8 @@
.. code-block::
- # Path to the extracted AmbiqSuite SDK package.
- dir_pw_third_party_ambiq_SDK = "/path/to/AmbiqSuite_R4.3.0"
+ # Path to the extracted AmbiqSuite SDK package.
+ dir_pw_third_party_ambiq_SDK = "/path/to/AmbiqSuite_R4.3.0"
Usage
=====
diff --git a/targets/emcraft_sf2_som/target_docs.rst b/targets/emcraft_sf2_som/target_docs.rst
index 3a5b4bf..272312e 100644
--- a/targets/emcraft_sf2_som/target_docs.rst
+++ b/targets/emcraft_sf2_som/target_docs.rst
@@ -27,9 +27,9 @@
.. code-block::
- dir_pw_third_party_freertos = getenv("PW_PACKAGE_ROOT") + "/freertos"
- dir_pw_third_party_smartfusion_mss = getenv("PW_PACKAGE_ROOT") + "/smartfusion_mss"
- dir_pw_third_party_nanopb = getenv("PW_PACKAGE_ROOT") + "/nanopb"
+ dir_pw_third_party_freertos = getenv("PW_PACKAGE_ROOT") + "/freertos"
+ dir_pw_third_party_smartfusion_mss = getenv("PW_PACKAGE_ROOT") + "/smartfusion_mss"
+ dir_pw_third_party_nanopb = getenv("PW_PACKAGE_ROOT") + "/nanopb"
Building and running the demo
=============================
diff --git a/targets/mimxrt595_evk/target_docs.rst b/targets/mimxrt595_evk/target_docs.rst
index 657ee6f..47a9505 100644
--- a/targets/mimxrt595_evk/target_docs.rst
+++ b/targets/mimxrt595_evk/target_docs.rst
@@ -103,29 +103,29 @@
it.
.. code-block::
- :emphasize-lines: 1,6,10,12,20
+ :emphasize-lines: 1,6,10,12,20
- (gdb) target remote :2331
- Remote debugging using :2331
- warning: No executable has been specified and target does not support
- determining executable automatically. Try using the "file" command.
- 0x08000000 in ?? ()
- (gdb) file out/mimxrt595_evk_debug/obj/pw_status/test/status_test.elf
- A program is being debugged already.
- Are you sure you want to change the file? (y or n) y
- Reading symbols from out/mimxrt595_evk_debug/obj/pw_status/test/status_test.elf...
- (gdb) monitor reset
- Resetting target
- (gdb) load
- Loading section .flash_config, size 0x200 lma 0x8000400
- Loading section .vector_table, size 0x168 lma 0x8001000
- Loading section .code, size 0xb34c lma 0x8001180
- Loading section .ARM, size 0x8 lma 0x800c4d0
- Loading section .static_init_ram, size 0x3c8 lma 0x800c4d8
- Start address 0x080048d0, load size 47748
- Transfer rate: 15542 KB/sec, 6821 bytes/write.
- (gdb) monitor reset
- Resetting target
+ (gdb) target remote :2331
+ Remote debugging using :2331
+ warning: No executable has been specified and target does not support
+ determining executable automatically. Try using the "file" command.
+ 0x08000000 in ?? ()
+ (gdb) file out/mimxrt595_evk_debug/obj/pw_status/test/status_test.elf
+ A program is being debugged already.
+ Are you sure you want to change the file? (y or n) y
+ Reading symbols from out/mimxrt595_evk_debug/obj/pw_status/test/status_test.elf...
+ (gdb) monitor reset
+ Resetting target
+ (gdb) load
+ Loading section .flash_config, size 0x200 lma 0x8000400
+ Loading section .vector_table, size 0x168 lma 0x8001000
+ Loading section .code, size 0xb34c lma 0x8001180
+ Loading section .ARM, size 0x8 lma 0x800c4d0
+ Loading section .static_init_ram, size 0x3c8 lma 0x800c4d8
+ Start address 0x080048d0, load size 47748
+ Transfer rate: 15542 KB/sec, 6821 bytes/write.
+ (gdb) monitor reset
+ Resetting target
You can now set any breakpoints you wish, and ``continue`` to run the
executable.
diff --git a/targets/mimxrt595_evk_freertos/target_docs.rst b/targets/mimxrt595_evk_freertos/target_docs.rst
index 6ce8d67..e8a405e 100644
--- a/targets/mimxrt595_evk_freertos/target_docs.rst
+++ b/targets/mimxrt595_evk_freertos/target_docs.rst
@@ -52,7 +52,7 @@
.. code-block::
- dir_pw_third_party_freertos = getenv("PW_PACKAGE_ROOT") + "/freertos"
+ dir_pw_third_party_freertos = getenv("PW_PACKAGE_ROOT") + "/freertos"
--------
Building
@@ -123,29 +123,29 @@
it.
.. code-block::
- :emphasize-lines: 1,6,10,12,20
+ :emphasize-lines: 1,6,10,12,20
- (gdb) target remote :2331
- Remote debugging using :2331
- warning: No executable has been specified and target does not support
- determining executable automatically. Try using the "file" command.
- 0x08000000 in ?? ()
- (gdb) file out/mimxrt595_evk_freertos_debug/obj/pw_status/test/status_test.elf
- A program is being debugged already.
- Are you sure you want to change the file? (y or n) y
- Reading symbols from out/mimxrt595_evk_freertos_debug/obj/pw_status/test/status_test.elf...
- (gdb) monitor reset
- Resetting target
- (gdb) load
- Loading section .flash_config, size 0x200 lma 0x8000400
- Loading section .vector_table, size 0x168 lma 0x8001000
- Loading section .code, size 0xb34c lma 0x8001180
- Loading section .ARM, size 0x8 lma 0x800c4d0
- Loading section .static_init_ram, size 0x3c8 lma 0x800c4d8
- Start address 0x080048d0, load size 47748
- Transfer rate: 15542 KB/sec, 6821 bytes/write.
- (gdb) monitor reset
- Resetting target
+ (gdb) target remote :2331
+ Remote debugging using :2331
+ warning: No executable has been specified and target does not support
+ determining executable automatically. Try using the "file" command.
+ 0x08000000 in ?? ()
+ (gdb) file out/mimxrt595_evk_freertos_debug/obj/pw_status/test/status_test.elf
+ A program is being debugged already.
+ Are you sure you want to change the file? (y or n) y
+ Reading symbols from out/mimxrt595_evk_freertos_debug/obj/pw_status/test/status_test.elf...
+ (gdb) monitor reset
+ Resetting target
+ (gdb) load
+ Loading section .flash_config, size 0x200 lma 0x8000400
+ Loading section .vector_table, size 0x168 lma 0x8001000
+ Loading section .code, size 0xb34c lma 0x8001180
+ Loading section .ARM, size 0x8 lma 0x800c4d0
+ Loading section .static_init_ram, size 0x3c8 lma 0x800c4d8
+ Start address 0x080048d0, load size 47748
+ Transfer rate: 15542 KB/sec, 6821 bytes/write.
+ (gdb) monitor reset
+ Resetting target
You can now set any breakpoints you wish, and ``continue`` to run the
executable.
diff --git a/third_party/boringssl/docs.rst b/third_party/boringssl/docs.rst
index f2442f5..7e16e2c 100644
--- a/third_party/boringssl/docs.rst
+++ b/third_party/boringssl/docs.rst
@@ -49,7 +49,7 @@
.. code-block::
- dir_pw_third_party_boringssl = "//third_party/boringssl/src"
+ dir_pw_third_party_boringssl = "//third_party/boringssl/src"
#. Having a non-empty ``dir_pw_third_party_boringssl`` variable causes GN to
attempt to include the ``BUILD.generated.gni`` file from the sources even
diff --git a/third_party/emboss/docs.rst b/third_party/emboss/docs.rst
index 8ea321a..478a79a 100644
--- a/third_party/emboss/docs.rst
+++ b/third_party/emboss/docs.rst
@@ -49,11 +49,11 @@
.. code-block::
- import("$dir_pw_third_party/emboss/build_defs.gni")
+ import("$dir_pw_third_party/emboss/build_defs.gni")
- emboss_cc_library("protocol") {
- source = "my-protocol.emb"
- }
+ emboss_cc_library("protocol") {
+ source = "my-protocol.emb"
+ }
This generates a source set of the same name as the target, in this case "protocol".
To use the bindings, list this target as a dependency in GN and include the generated
@@ -61,4 +61,5 @@
.. code-block::
- #include <some/path/to/protocol.emb.h>
+ #include <some/path/to/protocol.emb.h>
+
diff --git a/third_party/nanopb/docs.rst b/third_party/nanopb/docs.rst
index 1af7211..360d50f 100644
--- a/third_party/nanopb/docs.rst
+++ b/third_party/nanopb/docs.rst
@@ -22,7 +22,7 @@
.. code-block::
- pw_third_party_nanopb_CONFIG = "$dir_pw_third_party/nanopb:disable_error_messages"
+ pw_third_party_nanopb_CONFIG = "$dir_pw_third_party/nanopb:disable_error_messages"
This will add ``-DPB_NO_ERRMSG=1`` to the build, which disables error messages
