From ee4b134dd604159cbb21a39ad6b93237f3974122 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 9 Jan 2023 15:46:59 -0800 Subject: [PATCH] doc: add snippets documentation Document this new build system feature. Since its purpose is customizing application builds, the logical place for the main body of documentation is in a new snippets/ directory in doc/build/. Create that directory and add its initial documentation. Like boards and samples, however, we expect people to write documentation for each snippet within the directory that defines the snippet itself. Therefore, add a new top-level snippets/ directory and stub out the documentation needed to document individual snippets as well. Add documentation and cross-references in other required places as well. Signed-off-by: Marti Bolivar --- doc/build/index.rst | 1 + doc/build/snippets/design.rst | 37 +++++ doc/build/snippets/index.rst | 25 ++++ doc/build/snippets/using.rst | 39 +++++ doc/build/snippets/writing.rst | 188 +++++++++++++++++++++++++ doc/conf.py | 3 + doc/develop/modules.rst | 6 + doc/develop/west/build-flash-debug.rst | 5 + snippets/index.rst | 10 ++ 9 files changed, 314 insertions(+) create mode 100644 doc/build/snippets/design.rst create mode 100644 doc/build/snippets/index.rst create mode 100644 doc/build/snippets/using.rst create mode 100644 doc/build/snippets/writing.rst create mode 100644 snippets/index.rst diff --git a/doc/build/index.rst b/doc/build/index.rst index dc0c6bceff..75be277c72 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -11,5 +11,6 @@ Build and Configuration Systems cmake/index.rst dts/index kconfig/index.rst + snippets/index.rst zephyr_cmake_package.rst sysbuild/index.rst diff --git a/doc/build/snippets/design.rst b/doc/build/snippets/design.rst new file mode 100644 index 0000000000..03d80f597e --- /dev/null +++ b/doc/build/snippets/design.rst @@ -0,0 +1,37 @@ +Snippets Design +############### + +This page documents design goals for the snippets feature. +Further information can be found in `Issue #51834`_. + +.. _Issue #51834: https://github.com/zephyrproject-rtos/zephyr/issues/51834 + +- **extensible**: for example, it is possible to add board support for an + existing built-in snippet without modifying the zephyr repository + +- **composable**: it is possible to use multiple snippets at once, for example + using: + + .. code-block:: console + + west build -S -S ... + +- **able to combine multiple types of configuration**: snippets make it possible + to store multiple different types of build system settings in one place, and + apply them all together + +- **specializable**: for example, it is possible to customize a snippet's + behavior for a particular board, or board revision + +- **future-proof and backwards-compatible**: arbitrary future changes to the + snippets feature will be possible without breaking backwards compatibility + for older snippets + +- **applicable to purely "software" changes**: unlike the shields feature, + snippets do not assume the presence of a "daughterboard", "shield", "hat", or + any other type of external assembly which is connected to the main board + +- **DRY** (don't repeat yourself): snippets allow you to skip unnecessary + repetition; for example, you can apply the same board-specific configuration + to boards ``foo`` and ``bar`` by specifying ``/(foo|bar)/`` as a regular + expression for the settings, which will then apply to both boards diff --git a/doc/build/snippets/index.rst b/doc/build/snippets/index.rst new file mode 100644 index 0000000000..53db2b8f19 --- /dev/null +++ b/doc/build/snippets/index.rst @@ -0,0 +1,25 @@ +.. _snippets: + +Snippets +######## + +Snippets are a way to save build system settings in one place, and then use +those settings when you build any Zephyr application. This lets you save common +configuration separately when it applies to multiple different applications. + +Some example use cases for snippets are: + +- changing your board's console backend from a "real" UART to a USB CDC-ACM UART +- enabling frequently-used debugging options +- applying interrelated configuration settings to your "main" CPU and a + co-processor core on an AMP SoC + +The following pages document this feature. + +.. toctree:: + :maxdepth: 1 + + using.rst + /snippets/index.rst + writing.rst + design.rst diff --git a/doc/build/snippets/using.rst b/doc/build/snippets/using.rst new file mode 100644 index 0000000000..608e292430 --- /dev/null +++ b/doc/build/snippets/using.rst @@ -0,0 +1,39 @@ +.. _using-snippets: + +Using Snippets +############## + +.. tip:: + + See :ref:`built-in-snippets` for a list of snippets that are provided by + Zephyr. + +Snippets have names. You use snippets by giving their names to the build +system. + +With west build +*************** + +To use a snippet named ``foo`` when building an application ``app``: + +.. code-block:: console + + west build -S foo app + +To use multiple snippets: + +.. code-block:: console + + west build -S snippet1 -S snippet2 [...] app + +With cmake +********** + +If you are running CMake directly instead of using ``west build``, use the +``SNIPPET`` variable. This is a whitespace- or semicolon-separated list of +snippet names you want to use. For example: + +.. code-block:: console + + cmake -Sapp -Bbuild -DSNIPPET="snippet1;snippet2" [...] + cmake --build build diff --git a/doc/build/snippets/writing.rst b/doc/build/snippets/writing.rst new file mode 100644 index 0000000000..66101e8e2b --- /dev/null +++ b/doc/build/snippets/writing.rst @@ -0,0 +1,188 @@ +Writing Snippets +################ + +.. contents:: + :local: + +Basics +****** + +Snippets are defined using YAML files named :file:`snippet.yml`. + +A :file:`snippet.yml` file contains the name of the snippet, along with +additional build system settings, like this: + +.. code-block:: yaml + + name: snippet-name + # ... build system settings go here ... + +Build system settings go in other keys in the file as described later on in +this page. + +You can combine settings whenever they appear under the same keys. For example, +you can combine a snippet-specific devicetree overlay and a ``.conf`` file like +this: + +.. code-block:: yaml + + name: foo + append: + DTC_OVERLAY_FILE: foo.overlay + OVERLAY_CONFIG: foo.conf + +Namespacing +*********** + +When writing devicetree overlays in a snippet, use ``snippet_`` or +``snippet-`` as a namespace prefix when choosing names for node labels, +node names, etc. This avoids namespace conflicts. + +For example, if your snippet is named ``foo-bar``, write your devicetree +overlays like this: + +.. code-block:: DTS + + chosen { + zephyr,baz = &snippet_foo_bar_dev; + }; + + snippet_foo_bar_dev: device@12345678 { + /* ... */ + }; + +Where snippets are located +************************** + +The build system looks for snippets in these places: + +#. In directories configured by the :makevar:`SNIPPET_ROOT` CMake variable. + This always includes the zephyr repository (so + :zephyr_file:`zephyr/snippets` is always a source of snippets) and the + application source directory (so :file:`/snippets` is also). + + Additional directories can be added manually at CMake time. + + The variable is a whitespace- or semicolon-separated list of directories + which may contain snippet definitions. + + For each directory in the list, the build system looks for + :file:`snippet.yml` files underneath a subdirectory named :file:`snippets/`, + if one exists. + + For example, if :makevar:`SNIPPET_ROOT` is set to ``/foo;/bar``, the build + system will look for :file:`snippet.yml` files underneath the following + subdirectories: + + - :file:`/foo/snippets/` + - :file:`/bar/snippets/` + + The :file:`snippet.yml` files can be nested anywhere underneath these + locations. + +#. In any :ref:`module ` whose :file:`module.yml` file provides a + ``snippet_root`` setting. + + For example, in a zephyr module named ``baz``, you can add this to your + :file:`module.yml` file: + + .. code-block:: yaml + + settings: + snippet_root: . + + And then any :file:`snippet.yml` files in ``baz/snippets`` will + automatically be discovered by the build system, just as if + the path to ``baz`` had appeared in :makevar:`SNIPPET_ROOT`. + +Processing order +**************** + +The order that snippets are processed is currently not defined. +Therefore, you should write your :file:`snippet.yml` file so that +it is not dependent on other snippets. + +.. _snippets-devicetree-overlays: + +Devicetree overlays (``.overlay``) +********************************** + +This :file:`snippet.yml` adds :file:`foo.overlay` to the build: + +.. code-block:: yaml + + name: foo + append: + DTC_OVERLAY_FILE: foo.overlay + +The path to :file:`foo.overlay` is relative to the directory containing +:file:`snippet.yml`. + +.. _snippets-conf-files: + +``.conf`` files +*************** + +This :file:`snippet.yml` adds :file:`foo.conf` to the build: + +.. code-block:: yaml + + name: foo + append: + OVERLAY_CONFIG: foo.conf + +The path to :file:`foo.conf` is relative to the directory containing +:file:`snippet.yml`. + +Board-specific settings +*********************** + +You can write settings that only apply to some boards. + +The settings described here are applied in **addition** to snippet settings +that apply to all boards. (This is similar, for example, to the way that an +application with both :file:`prj.conf` and :file:`boards/foo.conf` files will +use both ``.conf`` files in the build when building for board ``foo``, instead +of just :file:`boards/foo.conf`) + +By name +======= + +.. code-block:: yaml + + name: ... + boards: + bar: # settings for board "bar" go here + append: + DTC_OVERLAY_FILE: bar.overlay + baz: # settings for board "baz" go here + append: + DTC_OVERLAY_FILE: baz.overlay + +The above example uses :file:`bar.overlay` when building for board ``bar``, and +:file:`baz.overlay` when building for ``baz``. + +By regular expression +===================== + +You can enclose the board name in slashes (``/``) to match the name against a +regular expression in the `CMake syntax`_. The regular expression must match +the entire board name. + +.. _CMake syntax: + https://cmake.org/cmake/help/latest/command/string.html#regex-specification + +For example: + +.. code-block:: yaml + + name: foo + boards: + /my_vendor_.*/: + append: + DTC_OVERLAY_FILE: my_vendor.overlay + +The above example uses devicetree overlay :file:`my_vendor.overlay` when +building for either board ``my_vendor_board1`` or ``my_vendor_board2``. It +would not use the overlay when building for either ``another_vendor_board`` or +``x_my_vendor_board``. diff --git a/doc/conf.py b/doc/conf.py index 4229a78232..aeccbd204b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -269,6 +269,7 @@ vcs_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr/blob/{vcs_lin vcs_link_prefixes = { "samples/.*": "", "boards/.*": "", + "snippets/.*": "", ".*": "doc", } vcs_link_exclude = [ @@ -290,6 +291,8 @@ external_content_contents = [ (ZEPHYR_BASE, "boards/**/doc"), (ZEPHYR_BASE, "samples/**/*.rst"), (ZEPHYR_BASE, "samples/**/doc"), + (ZEPHYR_BASE, "snippets/**/*.rst"), + (ZEPHYR_BASE, "snippets/**/doc"), ] external_content_keep = [ "reference/kconfig/*", diff --git a/doc/develop/modules.rst b/doc/develop/modules.rst index a75f1f849e..8846722348 100644 --- a/doc/develop/modules.rst +++ b/doc/develop/modules.rst @@ -850,6 +850,12 @@ Build settings supported in the :file:`module.yml` file are: - ``dts_root``: Contains additional dts files related to the architecture/soc families. Additional dts files must be located in a :file:`/dts` folder. +- ``snippet_root``: Contains additional snippets that are available for use. + These snippets must be defined in :file:`snippet.yml` files underneath the + :file:`/snippets` folder. For example, if you have + ``snippet_root: foo``, then you should place your module's + :file:`snippet.yml` files in :file:`/foo/snippets` or any + nested subdirectory. - ``soc_root``: Contains additional SoCs that are available to the build system. Additional SoCs must be located in a :file:`/soc` folder. - ``arch_root``: Contains additional architectures that are available to the diff --git a/doc/develop/west/build-flash-debug.rst b/doc/develop/west/build-flash-debug.rst index df8fe92165..8fd6827217 100644 --- a/doc/develop/west/build-flash-debug.rst +++ b/doc/develop/west/build-flash-debug.rst @@ -350,6 +350,11 @@ build the specific target for the target, for example:: west build --sysbuild --domain hello_world --target help +Use a snippet +------------- + +See :ref:`using-snippets`. + .. _west-building-config: Configuration Options diff --git a/snippets/index.rst b/snippets/index.rst new file mode 100644 index 0000000000..f0604abfae --- /dev/null +++ b/snippets/index.rst @@ -0,0 +1,10 @@ +.. _built-in-snippets: + +Built-in snippets +################# + +.. toctree:: + :maxdepth: 1 + :glob: + + **/*