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