diff options
Diffstat (limited to 'docs/module_structure.rst')
| -rw-r--r-- | docs/module_structure.rst | 66 |
1 files changed, 48 insertions, 18 deletions
diff --git a/docs/module_structure.rst b/docs/module_structure.rst index 586fca09d..17d3a07fd 100644 --- a/docs/module_structure.rst +++ b/docs/module_structure.rst @@ -55,12 +55,14 @@ Example module structure zip_test.cc # Python files go into 'py/<module>/...' - py/setup.py # All Python must be a Python module with setup.py - py/foo_test.py # Tests go in py/ but outside of the Python module + py/BUILD.gn # Python packages are declared in GN using pw_python_package + py/setup.py # Python files are structured as standard Python packages + py/foo_test.py # Tests go in py/ but outside of the Python package py/bar_test.py py/pw_foo/__init__.py py/pw_foo/__main__.py py/pw_foo/bar.py + py/pw_foo/py.typed # Indicates that this package has type annotations # Go files go into 'go/...' go/... @@ -203,10 +205,10 @@ configuration. Declaring configuration ^^^^^^^^^^^^^^^^^^^^^^^ -Configuration values are declared in a header file with macros. If the macro -value is not already defined, a default definition is provided. Otherwise, -nothing is done. Configuration headers may include ``static_assert`` statements -to validate configuration values. +Configuration options are declared in a header file as macros. If the macro is +not already defined, a default definition is provided. Otherwise, nothing is +done. Configuration headers may include ``static_assert`` statements to validate +configuration values. .. code-block:: c++ @@ -283,10 +285,11 @@ if desired. The configuration values may also be overridden individually by setting backends for the individual module configurations (e.g. in GN, ``pw_foo_CONFIG = "//configuration:my_foo_config"``). -Configurations are overridden by setting compilation options in the config -backend. These options could be set through macro definitions, such as -``-DPW_FOO_INPUT_BUFFER_SIZE_BYTES=256``, or in a header file included with the -``-include`` option. +Configurations options are overridden by setting macros in the config backend. +These macro definitions can be provided through compilation options, such as +``-DPW_FOO_INPUT_BUFFER_SIZE_BYTES=256``. Configuration macro definitions may +also be set in a header file. The header file is included using the ``-include`` +compilation option. This example shows two ways to configure a module in the GN build system. @@ -295,30 +298,57 @@ This example shows two ways to configure a module in the GN build system. # 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 macro. + # 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 = [ "-DPW_FOO_INPUT_BUFFER_SIZE_BYTES=256" ] + defines = [ "PW_FOO_INPUT_BUFFER_SIZE_BYTES=256" ] } - # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES with a header file. + # This configuration sets PW_FOO_INPUT_BUFFER_SIZE_BYTES in a header file. pw_source_set("include_overrides") { - public_configs = [ ":header_options" ] + public_configs = [ ":set_options_in_header_file" ] # Header file with #define PW_FOO_INPUT_BUFFER_SIZE_BYTES 256 sources = [ "my_config_overrides.h" ] } - config("header_options") { + config("set_options_in_header_file") { cflags = [ "-include", - "my_config_overrides.h", + rebase_path("my_config_overrides.h"), ] } +.. admonition:: Why this config pattern is preferred + + Alternate patterns for configuring a module include overriding the module's + config header or having that header optionally include a header at a known + path (e.g. ``pw_foo/config_overrides.h``). There are a few downsides to these + approaches: + + * The module needs its own config header that defines, provides defaults for, + and validates the configuration options. Replacing this header with a + user-defined header would require defining all options in the user's header, + which is cumbersome and brittle, and would bypass validation in the module's + header. + * Including a config override header at a particular path would prevent + multiple modules from sharing the same configuration file. Multiple headers + could redirect to the same configuration file, but this would still require + creating a separate header and setting the config backend variable for each + module. + * Optionally including a config override header requires boilerplate code that + would have to be duplicated in every configurable module. + * An optional config override header file would silently be excluded if the + file path were accidentally misspelled. + +Python module structure +----------------------- +Python code is structured as described in the :ref:`docs-python-build-structure` +section of :ref:`docs-python-build`. + .. _docs-module-structure-facades: Facades @@ -345,7 +375,7 @@ Facades are essential in some circumstances: .. caution:: Modules should only use facades when necessary. Facades are permanently locked - to a particular implementation at compile time. Multpile backends cannot be + to a particular implementation at compile time. Multiple backends cannot be used in one build, and runtime dependency injection is not possible, which makes testing difficult. Where appropriate, modules should use other mechanisms, such as virtual interfaces, callbacks, or templates, in place of @@ -427,7 +457,7 @@ To create a new Pigweed module, follow the below steps. 10. Add the new module to docs module - - Add in ``docs/BUILD.gn`` to ``pw_doc_gen("docs")`` + - Add in ``docs/BUILD.gn`` to ``group("module_docs")`` 11. Run :ref:`module-pw_module-module-check` |