Skip to content

Commit 2c36a7a

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 3aca14c commit 2c36a7a

3 files changed

Lines changed: 193 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: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
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 for each Matter SDK revision.
37+
Later builds reuse the installed tool.
38+
39+
You can provide ``zap-cli`` in one of the following ways:
40+
41+
* 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).
42+
* Add the Matter SDK :file:`.zap-install` directory to :envvar:`PATH` before building.
43+
* Set :kconfig:option:`CONFIG_MATTER_ZAP_CLI_INSTALL_PATH` to the directory that contains ``zap-cli``.
44+
45+
Automatic ZAP installation (default)
46+
------------------------------------
47+
48+
.. tabs::
49+
50+
.. group-tab:: |nRFVSC|
51+
52+
Build the application as usual.
53+
On the first build, the build system downloads and installs the ZAP tool automatically.
54+
No extra configuration is required.
55+
56+
See `How to work with build configurations`_ in the |nRFVSC| documentation for more information.
57+
58+
.. group-tab:: Command line
59+
60+
Build the sample from the command line.
61+
On the first build, the build system downloads and installs the ZAP tool automatically.
62+
63+
.. code-block:: console
64+
65+
west build -b nrf52840dk/nrf52840
66+
67+
Provide ``zap-cli`` on :envvar:`PATH`
68+
-------------------------------------
69+
70+
.. tabs::
71+
72+
.. group-tab:: |nRFVSC|
73+
74+
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.
75+
76+
.. code-block:: console
77+
78+
export PATH="${ZEPHYR_BASE}/../modules/lib/matter/.zap-install:${PATH}"
79+
80+
Alternatively, add the same export to your shell startup file so it applies to every |nRFVSC| terminal session.
81+
82+
.. group-tab:: Command line
83+
84+
Export the Matter SDK :file:`.zap-install` directory on :envvar:`PATH`, then build the sample:
85+
86+
.. code-block:: console
87+
88+
export PATH="${ZEPHYR_BASE}/../modules/lib/matter/.zap-install:${PATH}"
89+
west build -b nrf52840dk/nrf52840
90+
91+
Provide an explicit ZAP install path
92+
------------------------------------
93+
94+
.. tabs::
95+
96+
.. group-tab:: |nRFVSC|
97+
98+
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``.
99+
Rebuild the build configuration after adding the argument.
100+
101+
See `How to work with build configurations`_ in the |nRFVSC| documentation for more information.
102+
103+
.. group-tab:: Command line
104+
105+
Pass the install path as a CMake argument when building:
106+
107+
.. code-block:: console
108+
109+
west build -b nrf52840dk/nrf52840 -- -DCONFIG_MATTER_ZAP_CLI_INSTALL_PATH=\"${ZEPHYR_BASE}/../modules/lib/matter/.zap-install\"
110+
111+
.. _migration_110_recommended:
112+
113+
Recommended changes
114+
*******************
115+
116+
The following changes are not mandatory, but improve your workflow when migrating.
117+
118+
Continue using the legacy static ZAP workflow
119+
=============================================
120+
121+
.. toggle::
122+
123+
If you prefer to keep generating ZAP output manually and checking it into your project, select the legacy mode in Kconfig:
124+
125+
* Set :kconfig:option:`CONFIG_MATTER_ZAP_GENERATION_STATIC` to ``y``.
126+
127+
Apart from this Kconfig change, your existing workflow stays the same.
128+
You still generate C++ files with the Matter west commands described on the :ref:`ug_matter_gs_tools_matter_west_commands` page:
129+
130+
* :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool_gui` - Edit the :file:`.zap` file.
131+
* :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool_generate` - Generate the :file:`zap-generated/` directory.
132+
133+
.. tabs::
134+
135+
.. group-tab:: |nRFVSC|
136+
137+
1. Open the :guilabel:`Kconfig` configuration for your build configuration.
138+
2. Search for ``MATTER_ZAP_GENERATION`` and enable :kconfig:option:`CONFIG_MATTER_ZAP_GENERATION_STATIC`.
139+
3. Rebuild the application.
140+
4. After editing the :file:`.zap` file, open a terminal with the toolchain environment and run:
141+
142+
.. code-block:: console
143+
144+
west zap-generate
145+
146+
.. group-tab:: Command line
147+
148+
Add the following options to :file:`prj.conf`, or pass them as CMake arguments:
149+
150+
.. code-block:: none
151+
152+
CONFIG_MATTER_ZAP_GENERATION_STATIC=y
153+
154+
After editing the :file:`.zap` file, generate the output files:
155+
156+
.. code-block:: console
157+
158+
west zap-generate
159+
160+
The generated files are written to :file:`zap-generated/` next to the :file:`.zap` file unless you pass ``--output``.
161+
162+
.. note::
163+
164+
When using static generation, you are responsible for re-running ``west zap-generate`` after every change in the :file:`.zap` and for keeping the generated files in version control.
165+
166+
Remove checked-in :file:`zap-generated/` directories
167+
=====================================================
168+
169+
.. toggle::
170+
171+
If you switch to build-time generation, delete any :file:`zap-generated/` directories from your application source tree.
172+
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 all breaking changes are documented, 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)