Snippets are defined using YAML files named snippet.yml
.
A snippet.yml
file contains the name of the snippet, along with additional build system settings, like this:
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:
name: foo
append:
EXTRA_DTC_OVERLAY_FILE: foo.overlay
EXTRA_CONF_FILE: foo.conf
When writing devicetree overlays in a snippet, use snippet_<name>
or snippet-<name>
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:
chosen {
zephyr,baz = &snippet_foo_bar_dev;
};
snippet_foo_bar_dev: device@12345678 {
/* ... */
};
The build system looks for snippets in these places:
In directories configured by the
SNIPPET_ROOT
CMake variable. This always includes the zephyr repository (so :zephyr_file:`snippets/ is always a source of snippets) and the application source directory (so :file:<app>/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
snippet.yml
files underneath a subdirectory namedsnippets/
, if one exists.For example, if
SNIPPET_ROOT
is set to/foo;/bar
, the build system will look forsnippet.yml
files underneath the following subdirectories:/foo/snippets/
/bar/snippets/
The
snippet.yml
files can be nested anywhere underneath these locations.In any
module <modules>
whosemodule.yml
file provides asnippet_root
setting.For example, in a zephyr module named
baz
, you can add this to yourmodule.yml
file:settings: snippet_root: .
And then any
snippet.yml
files inbaz/snippets
will automatically be discovered by the build system, just as if the path tobaz
had appeared inSNIPPET_ROOT
.
Snippets are processed in the order they are listed in the SNIPPET
variable, or in the order of the -S
arguments if using west.
To apply bar
after foo
:
cmake -Sapp -Bbuild -DSNIPPET="foo;bar" [...]
cmake --build build
The same can be achieved with west as follows:
west build -S foo -S bar [...] app
When multiple snippets set the same configuration, the configuration value set by the last processed snippet ends up in the final configurations.
For instance, if foo
sets CONFIG_FOO=1
and bar
sets CONFIG_FOO=2
in the above example, the resulting final configuration will be CONFIG_FOO=2
because bar
is processed after foo
.
This principle applies to both Kconfig fragments (.conf
files) and devicetree overlays (.overlay
files).
This snippet.yml
adds foo.overlay
to the build:
name: foo
append:
EXTRA_DTC_OVERLAY_FILE: foo.overlay
The path to foo.overlay
is relative to the directory containing snippet.yml
.
This snippet.yml
adds foo.conf
to the build:
name: foo
append:
EXTRA_CONF_FILE: foo.conf
The path to foo.conf
is relative to the directory containing snippet.yml
.
This snippet.yml
adds DTS_EXTRA_CPPFLAGS
CMake Cache variables to the build:
name: foo
append:
DTS_EXTRA_CPPFLAGS: -DMY_DTS_CONFIGURE
Adding these flags enables control over the content of a devicetree file.
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 prj.conf
and boards/foo.conf
files will use both .conf
files in the build when building for board foo
, instead of just boards/foo.conf
)
name: ...
boards:
bar: # settings for board "bar" go here
append:
EXTRA_DTC_OVERLAY_FILE: bar.overlay
baz: # settings for board "baz" go here
append:
EXTRA_DTC_OVERLAY_FILE: baz.overlay
The above example uses bar.overlay
when building for board bar
, and baz.overlay
when building for baz
.
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.
For example:
name: foo
boards:
/my_vendor_.*/:
append:
EXTRA_DTC_OVERLAY_FILE: my_vendor.overlay
The above example uses devicetree overlay 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
.