Skip to content

Commit 0482e6f

Browse files
ArekBalysNordicArekBalysNordic
committed
docs: Describe migration from static to dynamic zap generation
- Added migration guide entry Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
1 parent 0fa0802 commit 0482e6f

3 files changed

Lines changed: 192 additions & 0 deletions

File tree

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,4 @@ For additional context on other solutions, refer to the following resources:
2626
software_maturity
2727
release_notes
2828
known_issues
29+
migration_guides

‎docs/migration/migration_guide_110.rst‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
:orphan:
2+
3+
.. _migration_110:
4+
5+
Migration notes for |addon| v1.1.0
6+
##################################
7+
8+
.. contents::
9+
:local:
10+
:depth: 3
11+
12+
This document describes the changes required or recommended when migrating your Matter application from the |NCS| Matter samples to the |addon| v1.0.0.
13+
14+
.. _migration_110_required:
15+
16+
Required changes
17+
****************
18+
19+
The following changes are mandatory to make your application work in the same way as in previous releases.
20+
21+
Build-time ZAP code generation
22+
==============================
23+
24+
.. toggle::
25+
26+
The |addon| samples no longer include pre-generated ZAP output under :file:`zap-generated/` in the sample source tree.
27+
By default, ZAP artifacts are generated automatically during the build.
28+
29+
The default Kconfig option is :kconfig:option:`CONFIG_MATTER_ZAP_GENERATION_BUILD_TIME`.
30+
No other source changes are required when you adopt this mode.
31+
32+
.. important::
33+
34+
On the first build of a sample, the build system downloads and installs the ZAP tool into the Matter SDK :file:`.zap-install` directory.
35+
This happens automatically when :kconfig:option:`CONFIG_MATTER_ZAP_CLI_INSTALL_PATH` is empty and ``zap-cli`` is not already available on :envvar:`PATH`.
36+
The download runs once per Matter SDK revision. Later builds reuse the installed tool.
37+
38+
You can provide ``zap-cli`` in one of the following ways:
39+
40+
* Leave both :envvar:`PATH` and :kconfig:option:`CONFIG_MATTER_ZAP_CLI_INSTALL_PATH` unset and let the build system install ZAP automatically (recommended for most users).
41+
* Add the Matter SDK :file:`.zap-install` directory to :envvar:`PATH` before building.
42+
* Set :kconfig:option:`CONFIG_MATTER_ZAP_CLI_INSTALL_PATH` to the directory that contains ``zap-cli``.
43+
44+
Automatic ZAP installation (default)
45+
------------------------------------
46+
47+
.. tabs::
48+
49+
.. group-tab:: |nRFVSC|
50+
51+
Build the application as usual.
52+
On the first build, the build system downloads and installs the ZAP tool automatically.
53+
No extra configuration is required.
54+
55+
See `How to work with build configurations`_ in the |nRFVSC| documentation for more information.
56+
57+
.. group-tab:: Command line
58+
59+
Build the sample from the command line.
60+
On the first build, the build system downloads and installs the ZAP tool automatically.
61+
62+
.. code-block:: console
63+
64+
west build -b nrf52840dk/nrf52840
65+
66+
Provide ``zap-cli`` on :envvar:`PATH`
67+
-------------------------------------
68+
69+
.. tabs::
70+
71+
.. group-tab:: |nRFVSC|
72+
73+
Before building, add the Matter SDK :file:`.zap-install` directory to :envvar:`PATH` in the terminal session used by the extension, then build the application as usual.
74+
75+
.. code-block:: console
76+
77+
export PATH="${ZEPHYR_BASE}/../modules/lib/matter/.zap-install:${PATH}"
78+
79+
Alternatively, add the same export to your shell startup file so it applies to every |nRFVSC| terminal session.
80+
81+
.. group-tab:: Command line
82+
83+
Export the Matter SDK :file:`.zap-install` directory on :envvar:`PATH`, then build the sample:
84+
85+
.. code-block:: console
86+
87+
export PATH="${ZEPHYR_BASE}/../modules/lib/matter/.zap-install:${PATH}"
88+
west build -b nrf52840dk/nrf52840
89+
90+
Provide an explicit ZAP install path
91+
------------------------------------
92+
93+
.. tabs::
94+
95+
.. group-tab:: |nRFVSC|
96+
97+
Add :kconfig:option:`CONFIG_MATTER_ZAP_CLI_INSTALL_PATH` to the build configuration's :guilabel:`Extra CMake arguments`, pointing to the directory that contains ``zap-cli``.
98+
Rebuild the build configuration after adding the argument.
99+
100+
See `How to work with build configurations`_ in the |nRFVSC| documentation for more information.
101+
102+
.. group-tab:: Command line
103+
104+
Pass the install path as a CMake argument when building:
105+
106+
.. code-block:: console
107+
108+
west build -b nrf52840dk/nrf52840 -- -DCONFIG_MATTER_ZAP_CLI_INSTALL_PATH=\"${ZEPHYR_BASE}/../modules/lib/matter/.zap-install\"
109+
110+
.. _migration_110_recommended:
111+
112+
Recommended changes
113+
*******************
114+
115+
The following changes are not mandatory, but improve your workflow when migrating.
116+
117+
Continue using the legacy static ZAP workflow
118+
=============================================
119+
120+
.. toggle::
121+
122+
If you prefer to keep generating ZAP output manually and checking it into your project, select the legacy mode in Kconfig:
123+
124+
* Set :kconfig:option:`CONFIG_MATTER_ZAP_GENERATION_STATIC` to ``y``.
125+
126+
Apart from this Kconfig change, your existing workflow stays the same.
127+
You still generate C++ files with the Matter west commands described on the :ref:`ug_matter_gs_tools_matter_west_commands` page:
128+
129+
* :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool_gui` — edit the :file:`.zap` file.
130+
* :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool_generate` — generate the :file:`zap-generated/` directory.
131+
132+
.. tabs::
133+
134+
.. group-tab:: |nRFVSC|
135+
136+
1. Open the :guilabel:`Kconfig` configuration for your build configuration.
137+
2. Search for ``MATTER_ZAP_GENERATION`` and enable :kconfig:option:`CONFIG_MATTER_ZAP_GENERATION_STATIC`.
138+
3. Rebuild the application.
139+
4. After editing the :file:`.zap` file, open a terminal with the toolchain environment and run:
140+
141+
.. code-block:: console
142+
143+
west zap-generate
144+
145+
.. group-tab:: Command line
146+
147+
Add the following options to :file:`prj.conf`, or pass them as CMake arguments:
148+
149+
.. code-block:: none
150+
151+
CONFIG_MATTER_ZAP_GENERATION_STATIC=y
152+
153+
After editing the :file:`.zap` file, generate the output files:
154+
155+
.. code-block:: console
156+
157+
west zap-generate
158+
159+
Generated files are written to :file:`zap-generated/` next to the :file:`.zap` file unless you pass ``--output``.
160+
161+
.. note::
162+
163+
When using static generation, you are responsible for re-running ``west zap-generate`` after every :file:`.zap` change and for keeping the generated files in version control.
164+
165+
Remove checked-in :file:`zap-generated/` directories
166+
=====================================================
167+
168+
.. toggle::
169+
170+
If you switch to build-time generation, delete any :file:`zap-generated/` directories from your application source tree.
171+
They are recreated in the build directory during compilation and no longer need to be stored in the repository.

‎docs/migration_guides.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. _migration_guides:
2+
3+
Migration notes
4+
################
5+
6+
The |addon| provides migration notes for major releases to assist your transition from the previous release.
7+
8+
.. note::
9+
While we strive to document all breaking changes, the migration guides might not include the detailed migration steps for your use case.
10+
If you need help, contact Nordic Semiconductor through `DevZone`_.
11+
12+
.. toctree::
13+
:maxdepth: 1
14+
:glob:
15+
:caption: Matter add-on version migration notes
16+
17+
Matter add-on version migration notes
18+
*************************************
19+
20+
* :ref:`migration_110`

0 commit comments

Comments
 (0)