1Writing Snippets
2################
3
4.. contents::
5   :local:
6
7Basics
8******
9
10Snippets are defined using YAML files named :file:`snippet.yml`.
11
12A :file:`snippet.yml` file contains the name of the snippet, along with
13additional build system settings, like this:
14
15.. code-block:: yaml
16
17   name: snippet-name
18   # ... build system settings go here ...
19
20Build system settings go in other keys in the file as described later on in
21this page.
22
23You can combine settings whenever they appear under the same keys. For example,
24you can combine a snippet-specific devicetree overlay and a ``.conf`` file like
25this:
26
27.. code-block:: yaml
28
29   name: foo
30   append:
31     EXTRA_DTC_OVERLAY_FILE: foo.overlay
32     EXTRA_CONF_FILE: foo.conf
33
34In addition, snippets can also be applied to sysbuild configuration like so:
35
36.. code-block:: yaml
37
38   name: foo
39   append:
40     SB_EXTRA_CONF_FILE: sb.conf
41     EXTRA_CONF_FILE: app.conf
42
43Namespacing
44***********
45
46When writing devicetree overlays in a snippet, use ``snippet_<name>`` or
47``snippet-<name>`` as a namespace prefix when choosing names for node labels,
48node names, etc. This avoids namespace conflicts.
49
50For example, if your snippet is named ``foo-bar``, write your devicetree
51overlays like this:
52
53.. code-block:: DTS
54
55   chosen {
56           zephyr,baz = &snippet_foo_bar_dev;
57   };
58
59   snippet_foo_bar_dev: device@12345678 {
60           /* ... */
61   };
62
63Where snippets are located
64**************************
65
66The build system looks for snippets in these places:
67
68#. In directories configured by the :makevar:`SNIPPET_ROOT` CMake variable.
69   This always includes the zephyr repository (so
70   :zephyr_file:`snippets/` is always a source of snippets) and the
71   application source directory (so :file:`<app>/snippets` is also).
72
73   Additional directories can be added manually at CMake time.
74
75   The variable is a whitespace- or semicolon-separated list of directories
76   which may contain snippet definitions.
77
78   For each directory in the list, the build system looks for
79   :file:`snippet.yml` files underneath a subdirectory named :file:`snippets/`,
80   if one exists.
81
82   For example, if :makevar:`SNIPPET_ROOT` is set to ``/foo;/bar``, the build
83   system will look for :file:`snippet.yml` files underneath the following
84   subdirectories:
85
86   - :file:`/foo/snippets/`
87   - :file:`/bar/snippets/`
88
89   The :file:`snippet.yml` files can be nested anywhere underneath these
90   locations.
91
92#. In any :ref:`module <modules>` whose :file:`module.yml` file provides a
93   ``snippet_root`` setting.
94
95   For example, in a zephyr module named ``baz``, you can add this to your
96   :file:`module.yml` file:
97
98   .. code-block:: yaml
99
100      settings:
101        snippet_root: .
102
103   And then any :file:`snippet.yml` files in ``baz/snippets`` will
104   automatically be discovered by the build system, just as if
105   the path to ``baz`` had appeared in :makevar:`SNIPPET_ROOT`.
106
107Processing order
108****************
109
110Snippets are processed in the order they are listed in the :makevar:`SNIPPET`
111variable, or in the order of the ``-S`` arguments if using west.
112
113To apply ``bar`` after ``foo``:
114
115.. code-block:: console
116
117   cmake -Sapp -Bbuild -DSNIPPET="foo;bar" [...]
118   cmake --build build
119
120The same can be achieved with west as follows:
121
122.. code-block:: console
123
124   west build -S foo -S bar [...] app
125
126When multiple snippets set the same configuration, the configuration value set
127by the last processed snippet ends up in the final configurations.
128
129For instance, if ``foo`` sets ``CONFIG_FOO=1`` and ``bar`` sets
130``CONFIG_FOO=2`` in the above example, the resulting final configuration will
131be ``CONFIG_FOO=2`` because ``bar`` is processed after ``foo``.
132
133This principle applies to both Kconfig fragments (``.conf`` files) and
134devicetree overlays (``.overlay`` files).
135
136.. _snippets-devicetree-overlays:
137
138Devicetree overlays (``.overlay``)
139**********************************
140
141This :file:`snippet.yml` adds :file:`foo.overlay` to the build:
142
143.. code-block:: yaml
144
145   name: foo
146   append:
147     EXTRA_DTC_OVERLAY_FILE: foo.overlay
148
149The path to :file:`foo.overlay` is relative to the directory containing
150:file:`snippet.yml`.
151
152.. _snippets-conf-files:
153
154``.conf`` files
155***************
156
157This :file:`snippet.yml` adds :file:`foo.conf` to the build:
158
159.. code-block:: yaml
160
161   name: foo
162   append:
163     EXTRA_CONF_FILE: foo.conf
164
165The path to :file:`foo.conf` is relative to the directory containing
166:file:`snippet.yml`.
167
168Sysbuild ``.conf`` files
169************************
170
171This :file:`snippet.yml` adds :file:`foo.conf` to the sysbuild configuration:
172
173.. code-block:: yaml
174
175   name: foo
176   append:
177     SB_EXTRA_CONF_FILE: foo.conf
178
179The path to :file:`foo.conf` is relative to the directory containing
180:file:`snippet.yml`.
181
182``DTS_EXTRA_CPPFLAGS``
183**********************
184
185This :file:`snippet.yml` adds ``DTS_EXTRA_CPPFLAGS`` CMake Cache variables
186to the build:
187
188.. code-block:: yaml
189
190   name: foo
191   append:
192     DTS_EXTRA_CPPFLAGS: -DMY_DTS_CONFIGURE
193
194Adding these flags enables control over the content of a devicetree file.
195
196Board-specific settings
197***********************
198
199You can write settings that only apply to some boards.
200
201The settings described here are applied in **addition** to snippet settings
202that apply to all boards. (This is similar, for example, to the way that an
203application with both :file:`prj.conf` and :file:`boards/foo.conf` files will
204use both ``.conf`` files in the build when building for board ``foo``, instead
205of just :file:`boards/foo.conf`)
206
207By name
208=======
209
210.. code-block:: yaml
211
212   name: ...
213   boards:
214     bar: # settings for board "bar" go here
215       append:
216         EXTRA_DTC_OVERLAY_FILE: bar.overlay
217     baz: # settings for board "baz" go here
218       append:
219         EXTRA_DTC_OVERLAY_FILE: baz.overlay
220
221The above example uses :file:`bar.overlay` when building for board ``bar``, and
222:file:`baz.overlay` when building for ``baz``.
223
224By regular expression
225=====================
226
227You can enclose the board name in slashes (``/``) to match the name against a
228regular expression in the `CMake syntax`_. The regular expression must match
229the entire board name.
230
231.. _CMake syntax:
232   https://cmake.org/cmake/help/latest/command/string.html#regex-specification
233
234For example:
235
236.. code-block:: yaml
237
238   name: foo
239   boards:
240     /my_vendor_.*/:
241       append:
242         EXTRA_DTC_OVERLAY_FILE: my_vendor.overlay
243
244The above example uses devicetree overlay :file:`my_vendor.overlay` when
245building for either board ``my_vendor_board1`` or ``my_vendor_board2``. It
246would not use the overlay when building for either ``another_vendor_board`` or
247``x_my_vendor_board``.
248