Lines Matching full:zephyr
3 Zephyr CMake Package
6 The Zephyr `CMake package`_ is a convenient way to create a Zephyr-based application.
9 The :ref:`zephyr-app-types` section introduces the application types
12 The Zephyr CMake package ensures that CMake can automatically select a Zephyr installation to use f…
13 the application, whether it is a :ref:`Zephyr repository application <zephyr-repo-app>`,
14 a :ref:`Zephyr workspace application <zephyr-workspace-app>`, or a
15 :ref:`Zephyr freestanding application <zephyr-freestanding-app>`.
17 When developing a Zephyr-based application, then a developer simply needs to write
18 ``find_package(Zephyr)`` in the beginning of the application :file:`CMakeLists.txt` file.
20 To use the Zephyr CMake package it must first be exported to the `CMake user package registry`_.
21 This is means creating a reference to the current Zephyr installation inside the
31 ``~/.cmake/packages/Zephyr``
37 ``~/.cmake/packages/Zephyr``
43 ``HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\Zephyr``
46 The Zephyr CMake package allows CMake to automatically find a Zephyr base.
47 One or more Zephyr installations must be exported.
48 Exporting multiple Zephyr installations may be useful when developing or testing
49 Zephyr freestanding applications, Zephyr workspace application with vendor forks, etc..
52 Zephyr CMake package export (west)
55 When installing Zephyr using :ref:`west <get_the_code>` then it is recommended
56 to export Zephyr using ``west zephyr-export``.
60 Zephyr CMake package export (without west)
63 Zephyr CMake package is exported to the CMake user package registry using the following commands:
67 cmake -P <PATH-TO-ZEPHYR>/share/zephyr-package/cmake/zephyr_export.cmake
69 This will export the current Zephyr to the CMake user package registry.
71 To also export the Zephyr Unittest CMake package, run the following command in addition:
75 cmake -P <PATH-TO-ZEPHYR>/share/zephyrunittest-package/cmake/zephyr_export.cmake
79 Zephyr Base Environment Setting
82 The Zephyr CMake package search functionality allows for explicitly specifying
83 a Zephyr base using an environment variable.
89 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
91 This syntax instructs CMake to first search for Zephyr using the Zephyr base environment setting
96 Zephyr CMake Package Search Order
99 When Zephyr base environment setting is not used for searching, the Zephyr installation matching
102 * A Zephyr repository application will use the Zephyr in which it is located.
107 <projects>/zephyr-workspace/zephyr
111 in this example, ``hello_world`` will use ``<projects>/zephyr-workspace/zephyr``.
114 * Zephyr workspace application will use the Zephyr that share the same workspace.
119 <projects>/zephyr-workspace
120 ├── zephyr
125 in this example, ``my_first_app`` will use ``<projects>/zephyr-workspace/zephyr`` as this Zephyr
126 is located in the same workspace as the Zephyr workspace application.
129 The root of a Zephyr workspace is identical to ``west topdir`` if the workspace was
132 * Zephyr freestanding application will use the Zephyr registered in the CMake user package registry.
137 <projects>/zephyr-workspace-1
138 └── zephyr (Not exported to CMake)
140 <projects>/zephyr-workspace-2
141 └── zephyr (Exported to CMake)
149 in this example, only ``<projects>/zephyr-workspace-2/zephyr`` is exported to the CMake package
150 registry and therefore this Zephyr will be used by the Zephyr freestanding application
153 If user wants to test the application with ``<projects>/zephyr-workspace-1/zephyr``, this can be
154 done by using the Zephyr Base environment setting, meaning set
155 ``ZEPHYR_BASE=<projects>/zephyr-workspace-1/zephyr``, before
160 The Zephyr package selected on the first CMake invocation will be used for all subsequent
161 builds. To change the Zephyr package, for example to test the application using Zephyr base
165 Zephyr CMake Package Version
168 When writing an application then it is possible to specify a Zephyr version number ``x.y.z`` that
171 Specifying a version is especially useful for a Zephyr freestanding application as it ensures the
172 application is built with a minimal Zephyr version.
174 It also helps CMake to select the correct Zephyr to use for building, when there are multiple
175 Zephyr installations in the system.
181 find_package(Zephyr 2.2.0)
184 will require ``app`` to be built with Zephyr 2.2.0 as minimum.
185 CMake will search all exported candidates to find a Zephyr installation which matches this version
188 Thus it is possible to have multiple Zephyr installations and have CMake automatically select
195 <projects>/zephyr-workspace-2.a
196 └── zephyr (Exported to CMake)
198 <projects>/zephyr-workspace-2.b
199 └── zephyr (Exported to CMake)
207 in this case, there are two released versions of Zephyr installed at their own workspaces.
208 Workspace 2.a and 2.b, corresponding to the Zephyr version.
215 find_package(Zephyr 2.a)
226 find_package(Zephyr 2.a EXACT)
229 In case no Zephyr is found which satisfies the version required, as example, the application specif…
233 find_package(Zephyr 2.z)
240 Could not find a configuration file for package "Zephyr" that is compatible
245 …<projects>/zephyr-workspace-2.a/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake, version: 2.a…
246 …<projects>/zephyr-workspace-2.b/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake, version: 2.b…
249 .. note:: It can also be beneficial to specify a version number for Zephyr repository applications
250 and Zephyr workspace applications. Specifying a version in those cases ensures the
251 application will only build if the Zephyr repository or workspace is matching.
256 Multiple Zephyr Installations (Zephyr workspace)
259 Testing out a new Zephyr version, while at the same time keeping the existing Zephyr in the
262 Or having both an upstream Zephyr, Vendor specific, and a custom Zephyr in same workspace.
268 <projects>/zephyr-workspace
269 ├── zephyr
270 ├── zephyr-vendor
271 ├── zephyr-custom
277 in this setup, ``find_package(Zephyr)`` has the following order of precedence for selecting
278 which Zephyr to use:
280 * Project name: ``zephyr``
281 * First project, when Zephyr projects are ordered lexicographical, in this case.
283 * ``zephyr-custom``
284 * ``zephyr-vendor``
286 This means that ``my_first_app`` will use ``<projects>/zephyr-workspace/zephyr``.
288 It is possible to specify a Zephyr preference list in the application.
290 A Zephyr preference list can be specified as:
294 set(ZEPHYR_PREFER "zephyr-custom" "zephyr-vendor")
295 find_package(Zephyr)
301 If a Zephyr is specified in the list, but not found in the system, it is simply ignored and
302 ``find_package(Zephyr)`` will continue to the next candidate.
305 This allows for temporary creation of a new Zephyr release to be tested, without touching current
306 Zephyr. When testing is done, the ``zephyr-test`` folder can simply be removed.
311 set(ZEPHYR_PREFER "zephyr-test")
312 find_package(Zephyr)
318 Zephyr Build Configuration CMake packages
321 There are two Zephyr Build configuration packages which provide control over the build
322 settings in Zephyr in a more generic way. These packages are:
324 * **ZephyrBuildConfiguration**: Applies to all Zephyr applications in the workspace
332 The Zephyr Build Configuration CMake packages will be loaded in the Zephyr boilerplate code after
336 This allows the Zephyr Build Configuration CMake packages to setup or extend properties such as:
357 can be set on the CMake command line, **before** ``find_package(Zephyr ...)``, as environment
374 <projects>/zephyr-workspace
375 ├── zephyr
380 └── zephyr application
408 Zephyr CMake package source code
411 The Zephyr CMake package source code in
412 :zephyr_file:`share/zephyr-package/cmake` and
416 It also contains code for exporting Zephyr as a CMake config package.
421 The Zephyr package version file. This file is called by CMake to determine
423 ``find_package(Zephyr ...)``. It is also responsible for detection of Zephyr
431 The Zephyr package file. This file is called by CMake to for the package
433 ``find_package(Zephyr ...)``. This file is responsible for sourcing of
441 Common file used for detection of Zephyr repository and workspace candidates.