blob: d7b2ea58b7f276eecc9f241a96575e85f37327f9 [file] [log] [blame]
Rodrigo Caballerod838f822015-08-07 16:44:34 -05001.. _application:
2
Anas Nashif276c5892019-01-05 10:23:34 -05003Application Development
4#######################
Rodrigo Caballerod838f822015-08-07 16:44:34 -05005
Marti Bolivarccfdff62017-11-02 13:16:20 -04006.. note::
7
8 In this document, we'll assume your **application directory** is
Carles Cufi0008e342018-01-18 18:02:12 +01009 :file:`<home>/app`, and that its **build directory** is
10 :file:`<home>/app/build`.
Marti Bolivarccfdff62017-11-02 13:16:20 -040011 (These terms are defined in the following Overview.)
Carles Cufi0008e342018-01-18 18:02:12 +010012 On Linux/macOS, <home> is equivalent to ``~``, whereas on Windows it's
13 ``%userprofile%``.
Marti Bolivarccfdff62017-11-02 13:16:20 -040014
Anas Nashif7cb8a162016-12-22 10:47:01 -050015Overview
David B. Kinder2cb04542017-01-20 15:58:05 -080016********
Anas Nashif7cb8a162016-12-22 10:47:01 -050017
Carles Cufib4766432019-06-13 21:59:12 +020018Zephyr's build system is based on `CMake`_.
Marti Bolivarccfdff62017-11-02 13:16:20 -040019
20The build system is application-centric, and requires Zephyr-based applications
21to initiate building the kernel source tree. The application build controls
22the configuration and build process of both the application and Zephyr itself,
Anas Nashif7cb8a162016-12-22 10:47:01 -050023compiling them into a single binary.
24
Marti Bolivarccfdff62017-11-02 13:16:20 -040025Zephyr's base directory hosts Zephyr's own source code, its kernel
26configuration options, and its build definitions.
Anas Nashif7cb8a162016-12-22 10:47:01 -050027
Marti Bolivarccfdff62017-11-02 13:16:20 -040028The files in the **application directory** link Zephyr with the
29application. This directory contains all application-specific files, such as
30configuration options and source code.
Anas Nashif7cb8a162016-12-22 10:47:01 -050031
Marti Bolivarccfdff62017-11-02 13:16:20 -040032An application in its simplest form has the following contents:
33
34.. code-block:: none
35
Carles Cufi0008e342018-01-18 18:02:12 +010036 <home>/app
Marti Bolivarccfdff62017-11-02 13:16:20 -040037 ├── CMakeLists.txt
38 ├── prj.conf
39 └── src
40 └── main.c
41
42These contents are:
43
44* **CMakeLists.txt**: This file tells the build system where to find the other
45 application files, and links the application directory with Zephyr's CMake
46 build system. This link provides features supported by Zephyr's build system,
47 such as board-specific kernel configuration files, the ability to run and
48 debug compiled binaries on real or emulated hardware, and more.
49
Ulf Magnusson303484a2018-04-23 15:39:12 +020050* **Kernel configuration files**: An application typically provides a
Ulf Magnussone32686d2019-12-04 11:13:12 +010051 Kconfig configuration file (usually called :file:`prj.conf`) that specifies
Ulf Magnusson303484a2018-04-23 15:39:12 +020052 application-specific values for one or more kernel configuration options.
53 These application settings are merged with board-specific settings to produce
54 a kernel configuration.
55
Ulf Magnussone32686d2019-12-04 11:13:12 +010056 See :ref:`application-kconfig` below for more information.
Anas Nashif7cb8a162016-12-22 10:47:01 -050057
58* **Application source code files**: An application typically provides one
59 or more application-specific files, written in C or assembly language. These
60 files are usually located in a sub-directory called :file:`src`.
61
Marti Bolivar9c85c7f2017-11-03 12:34:22 -040062Once an application has been defined, you can use CMake to create project files
63for building it from a directory where you want to host these files. This is
64known as the **build directory**. Application build artifacts are always
65generated in a build directory; Zephyr does not support "in-tree" builds.
Anas Nashif7cb8a162016-12-22 10:47:01 -050066
Marti Bolivar9c85c7f2017-11-03 12:34:22 -040067The following sections describe how to create, build, and run Zephyr
68applications, followed by more detailed reference material.
Anas Nashif7cb8a162016-12-22 10:47:01 -050069
Anas Nashif218599d2019-01-21 20:45:59 -050070
71.. _source_tree_v2:
72
73Source Tree Structure
74*********************
75
76Understanding the Zephyr source tree can be helpful in locating the code
77associated with a particular Zephyr feature.
78
Carles Cufi7335ef92019-01-23 14:56:00 +010079At the top of the tree there are several files that are of importance:
80
81:file:`CMakeLists.txt`
82 The top-level file for the CMake build system, containing a lot of the
83 logic required to build Zephyr.
84
85:file:`Kconfig`
86 The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr`
87 also found at the top-level directory.
88
Ulf Magnussone32686d2019-12-04 11:13:12 +010089 See :ref:`the Kconfig section of the manual <kconfig>` for detailed Kconfig
90 documentation.
91
Carles Cufi7335ef92019-01-23 14:56:00 +010092:file:`west.yml`
Carles Cufi01e05522019-01-31 19:32:02 +010093 The :ref:`west` manifest, listing the external repositories managed by
94 the west command-line tool.
Carles Cufi7335ef92019-01-23 14:56:00 +010095
96The Zephyr source tree also contains the following top-level
97directories, each of which may have one or more additional levels of
98subdirectories which are not described here.
Anas Nashif218599d2019-01-21 20:45:59 -050099
100:file:`arch`
101 Architecture-specific kernel and system-on-chip (SoC) code.
102 Each supported architecture (for example, x86 and ARM)
103 has its own subdirectory,
104 which contains additional subdirectories for the following areas:
105
106 * architecture-specific kernel source files
107 * architecture-specific kernel include files for private APIs
108
109:file:`soc`
110 SoC related code and configuration files.
111
112:file:`boards`
113 Board related code and configuration files.
114
115:file:`doc`
116 Zephyr technical documentation source files and tools used to
117 generate the https://docs.zephyrproject.org web content.
118
119:file:`drivers`
120 Device driver code.
121
122:file:`dts`
Martí Bolívar6e57b422020-03-10 18:16:25 -0700123 :ref:`devicetree <dt-guide>` source files used to describe non-discoverable
Marti Bolivar27e5dd12019-10-07 10:37:09 -0700124 board-specific hardware details.
Anas Nashif218599d2019-01-21 20:45:59 -0500125
Anas Nashif218599d2019-01-21 20:45:59 -0500126:file:`include`
127 Include files for all public APIs, except those defined under :file:`lib`.
128
129:file:`kernel`
130 Architecture-independent kernel code.
131
132:file:`lib`
133 Library code, including the minimal standard C library.
134
135:file:`misc`
136 Miscellaneous code that doesn't belong to any of the other top-level
137 directories.
138
139:file:`samples`
140 Sample applications that demonstrate the use of Zephyr features.
141
142:file:`scripts`
143 Various programs and other files used to build and test Zephyr
144 applications.
145
146:file:`cmake`
147 Additional build scripts needed to build Zephyr.
148
149:file:`subsys`
150 Subsystems of Zephyr, including:
151
152 * USB device stack code.
153 * Networking code, including the Bluetooth stack and networking stacks.
154 * File system code.
155 * Bluetooth host and controller
156
157:file:`tests`
158 Test code and benchmarks for Zephyr features.
159
Torsten Rasmussendb0b4e12020-03-12 23:34:12 +0100160:file:`share`
161 Additional architecture independent data. Currently containing Zephyr CMake
162 package.
163
Anas Nashif218599d2019-01-21 20:45:59 -0500164
Gerard Marull-Paretasc1a97ac2021-05-26 16:13:39 +0200165Example standalone application
166******************************
167
168A reference standalone application contained in its own Git repository can be found in the `Example Application`_
169repository. It can be used as a reference on how to structure out-of-tree, Zephyr-based
170applications using the :ref:`T2 star topology <west-t2>`. It also demonstrates the out-of-tree use of features commonly used in applications such as:
171
172- Custom boards
173- Custom devicetree bindings
174- Custom drivers
175- Continuous Integration (CI) setup
176
Marti Bolivarccfdff62017-11-02 13:16:20 -0400177Creating an Application
178***********************
Anas Nashif7cb8a162016-12-22 10:47:01 -0500179
Marti Bolivarccfdff62017-11-02 13:16:20 -0400180Follow these steps to create a new application directory. (Refer to
Gerard Marull-Paretasc1a97ac2021-05-26 16:13:39 +0200181the `Example Application`_ repository for a reference standalone application in its own Git repository
182or to :ref:`samples-and-demos` for existing applications provided as part of
183Zephyr.)
Anas Nashif7cb8a162016-12-22 10:47:01 -0500184
Marti Bolivarccfdff62017-11-02 13:16:20 -0400185#. Create an application directory on your workstation computer, outside of the
186 Zephyr base directory. Usually you'll want to create it somewhere under
187 your user's home directory.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500188
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600189 For example, in a Unix shell or Windows ``cmd.exe`` prompt, navigate to
190 where you want to create your application, then enter:
Anas Nashif7cb8a162016-12-22 10:47:01 -0500191
192 .. code-block:: console
193
Carles Cufi0008e342018-01-18 18:02:12 +0100194 mkdir app
Anas Nashif7cb8a162016-12-22 10:47:01 -0500195
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600196 .. warning::
197
198 Building Zephyr or creating an application in a directory with spaces
199 anywhere on the path is not supported. So the Windows path
200 :file:`C:\\Users\\YourName\\app` will work, but :file:`C:\\Users\\Your
201 Name\\app` will not.
202
Marti Bolivarccfdff62017-11-02 13:16:20 -0400203#. It's recommended to place all application source code in a subdirectory
204 named :file:`src`. This makes it easier to distinguish between project
205 files and sources.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500206
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600207 Continuing the previous example, enter:
Anas Nashif7cb8a162016-12-22 10:47:01 -0500208
209 .. code-block:: console
210
Carles Cufi0008e342018-01-18 18:02:12 +0100211 cd app
212 mkdir src
Anas Nashif7cb8a162016-12-22 10:47:01 -0500213
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600214#. Place your application source code in the :file:`src` sub-directory. For
215 this example, we'll assume you created a file named :file:`src/main.c`.
Carles Cufi1cce63a2018-01-31 18:00:49 +0100216
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600217#. Create a file named :file:`CMakeLists.txt` in the ``app`` directory with the
218 following contents:
Anas Nashif7cb8a162016-12-22 10:47:01 -0500219
Marti Bolivarccfdff62017-11-02 13:16:20 -0400220 .. code-block:: cmake
Anas Nashif7cb8a162016-12-22 10:47:01 -0500221
Yasushi SHOJI27c79d22021-10-03 02:47:54 +0900222 cmake_minimum_required(VERSION 3.20.0)
223
Torsten Rasmussendb0b4e12020-03-12 23:34:12 +0100224 find_package(Zephyr)
Reto Schneider7eabab22018-10-25 16:54:09 +0200225 project(my_zephyr_app)
Anas Nashif7cb8a162016-12-22 10:47:01 -0500226
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600227 target_sources(app PRIVATE src/main.c)
228
Yasushi SHOJI27c79d22021-10-03 02:47:54 +0900229 ``cmake_minimum_required()`` is required to be in your
Nazar Kazakovf483b1b2022-03-16 21:07:43 +0000230 :file:`CMakeLists.txt` by CMake. It is also invoked by the Zephyr
Yasushi SHOJI27c79d22021-10-03 02:47:54 +0900231 package. The most recent of the two versions will be enforced by CMake.
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600232
Yasushi SHOJI27c79d22021-10-03 02:47:54 +0900233 ``find_package(Zephyr)`` pulls in the Zephyr build system, which creates a
234 CMake target named ``app`` (see :ref:`cmake_pkg`). Adding sources to this
235 target is how you include them in the build. The Zephyr package will define
236 ``Zephyr-Kernel`` as a CMake project and enable support for the ``C``,
237 ``CXX``, ``ASM`` languages.
238
239 ``project(my_zephyr_app)`` is required for defining your application
240 project. This must be called after ``find_package(Zephyr)`` to avoid
241 interference with Zephyr's ``project(Zephyr-Kernel)``.
242
243 ``target_sources(app PRIVATE src/main.c)`` is to add your source file to the
244 ``app`` target. This must come after ``find_package(Zephyr)`` which defines
245 the target.
Sebastian Bøe3747b5b2018-08-03 09:37:11 +0200246
Ulf Magnussone32686d2019-12-04 11:13:12 +0100247#. Set Kconfig configuration options. See :ref:`application-kconfig`.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500248
Martí Bolívar6e57b422020-03-10 18:16:25 -0700249#. Configure any devicetree overlays needed by your application.
250 See :ref:`set-devicetree-overlays`.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500251
Torsten Rasmussendb0b4e12020-03-12 23:34:12 +0100252.. note::
253
254 ``include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)``
255 is still supported for backward compatibility with older applications.
Martí Bolívar71f17bc2021-11-12 16:44:59 -0800256 Including ``boilerplate.cmake`` directly in the sample still requires using
257 :ref:`zephyr-env` before building the application.
Anas Nashifbf9ceac2021-04-15 14:40:00 -0400258
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600259.. _important-build-vars:
Anas Nashif7cb8a162016-12-22 10:47:01 -0500260
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600261Important Build System Variables
262********************************
Anas Nashif7cb8a162016-12-22 10:47:01 -0500263
Marti Bolivar0b6bbcf62018-10-14 23:20:17 -0600264You can control the Zephyr build system using many variables. This
265section describes the most important ones that every Zephyr developer
266should know about.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500267
Carles Cufi997ef852019-02-19 13:37:57 +0100268.. note::
Marti Bolivar7eca2562019-04-02 13:55:25 -0600269
270 The variables :makevar:`BOARD`, :makevar:`CONF_FILE`, and
271 :makevar:`DTC_OVERLAY_FILE` can be supplied to the build system in
272 3 ways (in order of precedence):
Carles Cufi997ef852019-02-19 13:37:57 +0100273
Carles Cufib4766432019-06-13 21:59:12 +0200274 * As a parameter to the ``west build`` or ``cmake`` invocation via the
Maksim Masalski124b55a2020-08-14 03:17:05 +0800275 ``-D`` command-line switch. If you have multiple overlay files, you should
276 use quotations, ``"file1.overlay;file2.overlay"``
Marti Bolivar5edb6d52019-05-06 23:36:30 -0600277 * As :ref:`env_vars`.
Marti Bolivar7eca2562019-04-02 13:55:25 -0600278 * As a ``set(<VARIABLE> <VALUE>)`` statement in your :file:`CMakeLists.txt`
Carles Cufi997ef852019-02-19 13:37:57 +0100279
Torsten Rasmussendb0b4e12020-03-12 23:34:12 +0100280* :makevar:`ZEPHYR_BASE`: Zephyr base variable used by the build system.
281 ``find_package(Zephyr)`` will automatically set this as a cached CMake
282 variable. But ``ZEPHYR_BASE`` can also be set as an environment variable in
283 order to force CMake to use a specific Zephyr installation.
Marti Bolivarccfdff62017-11-02 13:16:20 -0400284
Marti Bolivar7eca2562019-04-02 13:55:25 -0600285* :makevar:`BOARD`: Selects the board that the application's build
286 will use for the default configuration. See :ref:`boards` for
287 built-in boards, and :ref:`board_porting_guide` for information on
288 adding board support.
Marti Bolivarccfdff62017-11-02 13:16:20 -0400289
Martí Bolívar43102ca2020-09-15 13:17:30 -0700290* :makevar:`CONF_FILE`: Indicates the name of one or more Kconfig configuration
Marti Bolivar7eca2562019-04-02 13:55:25 -0600291 fragment files. Multiple filenames can be separated with either spaces or
292 semicolons. Each file includes Kconfig configuration values that override
293 the default configuration values.
Marti Bolivarccfdff62017-11-02 13:16:20 -0400294
Ulf Magnussone32686d2019-12-04 11:13:12 +0100295 See :ref:`initial-conf` for more information.
296
Martí Bolívar43102ca2020-09-15 13:17:30 -0700297* :makevar:`OVERLAY_CONFIG`: Additional Kconfig configuration fragment files.
298 Multiple filenames can be separated with either spaces or semicolons. This
299 can be useful in order to leave :makevar:`CONF_FILE` at its default value,
300 but "mix in" some additional configuration options.
301
Martí Bolívar6e57b422020-03-10 18:16:25 -0700302* :makevar:`DTC_OVERLAY_FILE`: One or more devicetree overlay files to use.
Maksim Masalski124b55a2020-08-14 03:17:05 +0800303 Multiple files can be separated with semicolons.
Martí Bolívar6e57b422020-03-10 18:16:25 -0700304 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
305 for information about devicetree and Zephyr.
Marti Bolivar7eca2562019-04-02 13:55:25 -0600306
Martí Bolívar71f17bc2021-11-12 16:44:59 -0800307* :makevar:`SHIELD`: see :ref:`shields`
308
Marti Bolivar7eca2562019-04-02 13:55:25 -0600309* :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of
310 additional directories with source code, Kconfig, etc. that should be used in
Martí Bolívar71f17bc2021-11-12 16:44:59 -0800311 the application build. See :ref:`modules` for details. If you set this
312 variable, it must be a complete list of all modules to use, as the build
313 system will not automatically pick up any modules from west.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400314
Martí Bolívar71f17bc2021-11-12 16:44:59 -0800315* :makevar:`ZEPHYR_EXTRA_MODULES`: Like :makevar:`ZEPHYR_MODULES`, except these
316 will be added to the list of modules found via west, instead of replacing it.
317
318.. note::
319
320 You can use a :ref:`cmake_build_config_package` to share common settings for
321 these variables.
Anas Nashif5342bc62021-05-06 09:48:14 -0400322
323Application CMakeLists.txt
324**************************
325
326Every application must have a :file:`CMakeLists.txt` file. This file is the
327entry point, or top level, of the build system. The final :file:`zephyr.elf`
328image contains both the application and the kernel libraries.
329
330This section describes some of what you can do in your :file:`CMakeLists.txt`.
331Make sure to follow these steps in order.
332
333#. If you only want to build for one board, add the name of the board
334 configuration for your application on a new line. For example:
335
336 .. code-block:: cmake
337
338 set(BOARD qemu_x86)
339
340 Refer to :ref:`boards` for more information on available boards.
341
342 The Zephyr build system determines a value for :makevar:`BOARD` by checking
343 the following, in order (when a BOARD value is found, CMake stops looking
344 further down the list):
345
346 - Any previously used value as determined by the CMake cache takes highest
347 precedence. This ensures you don't try to run a build with a different
348 :makevar:`BOARD` value than you set during the build configuration step.
349
350 - Any value given on the CMake command line (directly or indirectly via
351 ``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and
352 used next.
353
354 - If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
355 will then be used.
356
357 - Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
358 as described in this step, this value will be used.
359
360#. If your application uses a configuration file or files other than
361 the usual :file:`prj.conf` (or :file:`prj_YOUR_BOARD.conf`, where
362 ``YOUR_BOARD`` is a board name), add lines setting the
363 :makevar:`CONF_FILE` variable to these files appropriately.
364 If multiple filenames are given, separate them by a single space or
365 semicolon. CMake lists can be used to build up configuration fragment
366 files in a modular way when you want to avoid setting :makevar:`CONF_FILE`
367 in a single place. For example:
368
369 .. code-block:: cmake
370
371 set(CONF_FILE "fragment_file1.conf")
372 list(APPEND CONF_FILE "fragment_file2.conf")
373
374 See :ref:`initial-conf` for more information.
375
376#. If your application uses devicetree overlays, you may need to set
377 :ref:`DTC_OVERLAY_FILE <important-build-vars>`.
378 See :ref:`set-devicetree-overlays`.
379
380#. If your application has its own kernel configuration options,
381 create a :file:`Kconfig` file in the same directory as your
382 application's :file:`CMakeLists.txt`.
383
384 See :ref:`the Kconfig section of the manual <kconfig>` for detailed
385 Kconfig documentation.
386
387 An (unlikely) advanced use case would be if your application has its own
388 unique configuration **options** that are set differently depending on the
389 build configuration.
390
391 If you just want to set application specific **values** for existing Zephyr
392 configuration options, refer to the :makevar:`CONF_FILE` description above.
393
394 Structure your :file:`Kconfig` file like this:
395
396 .. literalinclude:: application-kconfig.include
397
398 .. note::
399
400 Environment variables in ``source`` statements are expanded directly, so
401 you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig
402 "bounce" symbol. If you use such a symbol, it must have the same name as
403 the environment variable.
404
405 See :ref:`kconfig_extensions` for more information.
406
407 The :file:`Kconfig` file is automatically detected when placed in
408 the application directory, but it is also possible for it to be
409 found elsewhere if the CMake variable :makevar:`KCONFIG_ROOT` is
410 set with an absolute path.
411
412#. Specify that the application requires Zephyr on a new line, **after any
413 lines added from the steps above**:
414
415 .. code-block:: cmake
416
417 find_package(Zephyr)
418 project(my_zephyr_app)
419
420 .. note:: ``find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})`` can be used if
421 enforcing a specific Zephyr installation by explicitly
422 setting the ``ZEPHYR_BASE`` environment variable should be
423 supported. All samples in Zephyr supports the ``ZEPHYR_BASE``
424 environment variable.
425
426#. Now add any application source files to the 'app' target
427 library, each on their own line, like so:
428
429 .. code-block:: cmake
430
431 target_sources(app PRIVATE src/main.c)
432
433Below is a simple example :file:`CMakeList.txt`:
434
435.. code-block:: cmake
436
437 set(BOARD qemu_x86)
438
439 find_package(Zephyr)
440 project(my_zephyr_app)
441
442 target_sources(app PRIVATE src/main.c)
443
444The Cmake property ``HEX_FILES_TO_MERGE``
445leverages the application configuration provided by
446Kconfig and CMake to let you merge externally built hex files
447with the hex file generated when building the Zephyr application.
448For example:
449
450.. code-block:: cmake
451
452 set_property(GLOBAL APPEND PROPERTY HEX_FILES_TO_MERGE
453 ${app_bootloader_hex}
454 ${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME}
455 ${app_provision_hex})
456
457CMakeCache.txt
458**************
459
460CMake uses a CMakeCache.txt file as persistent key/value string
461storage used to cache values between runs, including compile and build
462options and paths to library dependencies. This cache file is created
463when CMake is run in an empty build folder.
464
465For more details about the CMakeCache.txt file see the official CMake
466documentation `runningcmake`_ .
467
468.. _runningcmake: http://cmake.org/runningcmake/
469
470Application Configuration
471*************************
472
Torsten Rasmussen11980872021-09-01 11:26:53 +0200473.. _application-configuration-directory:
474
475Application Configuration Directory
476===================================
477
478Zephyr will use configuration files from the application's configuration
479directory except for files with an absolute path provided by the arguments
480described earlier, for example ``CONF_FILE``, ``OVERLAY_CONFIG``, and
481``DTC_OVERLAY_FILE``.
482
483The application configuration directory is defined by the
484``APPLICATION_CONFIG_DIR`` variable.
485
486``APPLICATION_CONFIG_DIR`` will be set by one of the sources below with the
487highest priority listed first.
488
4891. If ``APPLICATION_CONFIG_DIR`` is specified by the user with
490 ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before
491 ``find_package(Zephyr)`` then this folder is used a the application's
492 configuration directory.
493
4942. The application's source directory.
495
Anas Nashif5342bc62021-05-06 09:48:14 -0400496.. _application-kconfig:
497
498Kconfig Configuration
499=====================
500
501Application configuration options are usually set in :file:`prj.conf` in the
502application directory. For example, C++ support could be enabled with this
503assignment:
504
505.. code-block:: none
506
507 CONFIG_CPLUSPLUS=y
508
509Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
510started.
511
512See :ref:`setting_configuration_values` for detailed documentation on setting
513Kconfig configuration values. The :ref:`initial-conf` section on the same page
Gerard Marull-Paretasfc942ef2022-01-12 13:41:15 +0100514explains how the initial configuration is derived. See :ref:`kconfig-search`
515for a complete list of configuration options.
Anas Nashif5342bc62021-05-06 09:48:14 -0400516See :ref:`hardening` for security information related with Kconfig options.
517
518The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
519worth going through, especially if you planning to add new configuration
520options.
521
Torsten Rasmussenf17630b2021-10-22 09:26:51 +0200522Experimental features
523*********************
524
525Zephyr is a project under constant development and thus there are features that
526are still in early stages of their development cycle. Such features will be
527marked ``[EXPERIMENTAL]`` in their Kconfig title.
528
Gerard Marull-Paretas260decc2022-02-07 17:27:43 +0100529The :kconfig:option:`CONFIG_WARN_EXPERIMENTAL` setting can be used to enable warnings
Torsten Rasmussenf17630b2021-10-22 09:26:51 +0200530at CMake configure time if any experimental feature is enabled.
531
532.. code-block:: none
533
534 CONFIG_WARN_EXPERIMENTAL=y
535
Martí Bolívar254ceb62022-02-16 12:33:44 -0800536For example, if option ``CONFIG_FOO`` is experimental, then enabling it and
Nazar Kazakovf483b1b2022-03-16 21:07:43 +0000537:kconfig:option:`CONFIG_WARN_EXPERIMENTAL` will print the following warning at
Gerard Marull-Paretas260decc2022-02-07 17:27:43 +0100538CMake configure time when you build an application:
Torsten Rasmussenf17630b2021-10-22 09:26:51 +0200539
Martí Bolívar254ceb62022-02-16 12:33:44 -0800540.. code-block:: none
Torsten Rasmussenf17630b2021-10-22 09:26:51 +0200541
Martí Bolívar254ceb62022-02-16 12:33:44 -0800542 warning: Experimental symbol FOO is enabled.
Torsten Rasmussenf17630b2021-10-22 09:26:51 +0200543
Anas Nashif5342bc62021-05-06 09:48:14 -0400544Devicetree Overlays
545===================
546
547See :ref:`set-devicetree-overlays`.
548
549Application-Specific Code
550*************************
551
552Application-specific source code files are normally added to the
553application's :file:`src` directory. If the application adds a large
554number of files the developer can group them into sub-directories
555under :file:`src`, to whatever depth is needed.
556
557Application-specific source code should not use symbol name prefixes that have
558been reserved by the kernel for its own use. For more information, see `Naming
559Conventions
560<https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
561
562Third-party Library Code
563========================
564
565It is possible to build library code outside the application's :file:`src`
566directory but it is important that both application and library code targets
567the same Application Binary Interface (ABI). On most architectures there are
568compiler flags that control the ABI targeted, making it important that both
569libraries and applications have certain compiler flags in common. It may also
570be useful for glue code to have access to Zephyr kernel header files.
571
572To make it easier to integrate third-party components, the Zephyr
573build system has defined CMake functions that give application build
574scripts access to the zephyr compiler options. The functions are
575documented and defined in :zephyr_file:`cmake/extensions.cmake`
576and follow the naming convention ``zephyr_get_<type>_<format>``.
577
578The following variables will often need to be exported to the
579third-party build system.
580
581* ``CMAKE_C_COMPILER``, ``CMAKE_AR``.
582
583* ``ARCH`` and ``BOARD``, together with several variables that identify the
584 Zephyr kernel version.
585
586:zephyr_file:`samples/application_development/external_lib` is a sample
587project that demonstrates some of these features.
588
589
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400590.. _build_an_application:
591
Carles Cufiafcbc992019-08-25 19:06:22 +0200592Building an Application
593***********************
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400594
595The Zephyr build system compiles and links all components of an application
596into a single application image that can be run on simulated hardware or real
597hardware.
Marti Bolivarccfdff62017-11-02 13:16:20 -0400598
Carles Cufib4766432019-06-13 21:59:12 +0200599Like any other CMake-based system, the build process takes place :ref:`in
600two stages <cmake-details>`. First, build files (also known as a buildsystem)
601are generated using the ``cmake`` command-line tool while specifying a
602generator. This generator determines the native build tool the buildsystem
603will use in the second stage.
604The second stage runs the native build tool to actually build the
605source files and generate an image. To learn more about these concepts refer to
606the `CMake introduction`_ in the official CMake documentation.
607
Carles Cufiafcbc992019-08-25 19:06:22 +0200608Although the default build tool in Zephyr is :std:ref:`west <west>`, Zephyr's
609meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or
610``make``) behind the scenes, you can also choose to invoke ``cmake`` directly if
611you prefer. On Linux and macOS you can choose between the ``make`` and
612``ninja``
Carles Cufib4766432019-06-13 21:59:12 +0200613generators (i.e. build tools), whereas on Windows you need to use ``ninja``,
614since ``make`` is not supported on this platform.
615For simplicity we will use ``ninja`` throughout this guide, and if you
616choose to use ``west build`` to build your application know that it will
617default to ``ninja`` under the hood.
Anas Nashif7cb8a162016-12-22 10:47:01 -0500618
Carles Cufiafcbc992019-08-25 19:06:22 +0200619As an example, let's build the Hello World sample for the ``reel_board``:
620
621.. zephyr-app-commands::
622 :tool: all
623 :app: samples/hello_world
624 :board: reel_board
625 :goals: build
626
627On Linux and macOS, you can also build with ``make`` instead of ``ninja``:
628
629Using west:
630
631- to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
632 command line; see the :ref:`west build <west-building-generator>`
633 documentation for an example.
634- to use ``make`` by default from now on, run ``west config build.generator
635 "Unix Makefiles"``.
636
637Using CMake directly:
638
639.. zephyr-app-commands::
640 :tool: cmake
641 :app: samples/hello_world
642 :generator: make
643 :host-os: unix
644 :board: reel_board
645 :goals: build
646
647
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400648Basics
649======
650
Daniel Wong14f09a32021-07-25 20:57:13 +1000651.. note::
652
653 In the below example, ``west`` is used outside of a west workspace. For this
654 to work, you must set the ``ZEPHYR_BASE`` environment variable to the path
655 of your zephyr git repository, using one of the methods on the
656 :ref:`Environment Variables <env_vars>` page.
657
Carles Cufi0008e342018-01-18 18:02:12 +0100658#. Navigate to the application directory :file:`<home>/app`.
Carles Cufi997ef852019-02-19 13:37:57 +0100659#. Enter the following commands to build the application's :file:`zephyr.elf`
660 image for the board specified in the command-line parameters:
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400661
Carles Cufi997ef852019-02-19 13:37:57 +0100662 .. zephyr-app-commands::
Carles Cufib4766432019-06-13 21:59:12 +0200663 :tool: all
664 :cd-into:
Carles Cufi997ef852019-02-19 13:37:57 +0100665 :board: <board>
666 :goals: build
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400667
668 If desired, you can build the application using the configuration settings
669 specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
670 parameter. These settings will override the settings in the application's
671 :file:`.config` file or its default :file:`.conf` file. For example:
672
Carles Cufib4766432019-06-13 21:59:12 +0200673 .. zephyr-app-commands::
674 :tool: all
675 :cd-into:
676 :board: <board>
677 :gen-args: -DCONF_FILE=prj.alternate.conf
678 :goals: build
679 :compact:
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400680
Carles Cufi997ef852019-02-19 13:37:57 +0100681 As described in the previous section, you can instead choose to permanently
682 set the board and configuration settings by either exporting :makevar:`BOARD`
683 and :makevar:`CONF_FILE` environment variables or by setting their values
684 in your :file:`CMakeLists.txt` using ``set()`` statements.
Carles Cufib4766432019-06-13 21:59:12 +0200685 Additionally, ``west`` allows you to :ref:`set a default board
686 <west-building-config>`.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400687
Ruth Fuchss81a61072020-07-16 09:54:52 +0200688.. _build-directory-contents:
689
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400690Build Directory Contents
691========================
692
Carles Cufi0008e342018-01-18 18:02:12 +0100693When using the Ninja generator a build directory looks like this:
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400694
695.. code-block:: none
696
Carles Cufi0008e342018-01-18 18:02:12 +0100697 <home>/app/build
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400698 ├── build.ninja
699 ├── CMakeCache.txt
700 ├── CMakeFiles
701 ├── cmake_install.cmake
702 ├── rules.ninja
703 └── zephyr
704
705The most notable files in the build directory are:
706
707* :file:`build.ninja`, which can be invoked to build the application.
708
709* A :file:`zephyr` directory, which is the working directory of the
710 generated build system, and where most generated files are created and
711 stored.
712
713After running ``ninja``, the following build output files will be written to
714the :file:`zephyr` sub-directory of the build directory. (This is **not the
715Zephyr base directory**, which contains the Zephyr source code etc. and is
716described above.)
717
718* :file:`.config`, which contains the configuration settings
719 used to build the application.
720
Ulf Magnusson57b28ca2018-12-08 05:32:00 +0100721 .. note::
722
723 The previous version of :file:`.config` is saved to :file:`.config.old`
724 whenever the configuration is updated. This is for convenience, as
725 comparing the old and new versions can be handy.
726
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400727* Various object files (:file:`.o` files and :file:`.a` files) containing
728 compiled kernel and application code.
729
730* :file:`zephyr.elf`, which contains the final combined application and
731 kernel binary. Other binary output formats, such as :file:`.hex` and
732 :file:`.bin`, are also supported.
733
Torsten Rasmussendb0b4e12020-03-12 23:34:12 +0100734.. _application_rebuild:
735
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400736Rebuilding an Application
737=========================
738
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400739Application development is usually fastest when changes are continually tested.
740Frequently rebuilding your application makes debugging less painful
741as the application becomes more complex. It's usually a good idea to
742rebuild and test after any major changes to the application's source files,
743CMakeLists.txt files, or configuration settings.
744
745.. important::
746
747 The Zephyr build system rebuilds only the parts of the application image
748 potentially affected by the changes. Consequently, rebuilding an application
749 is often significantly faster than building it the first time.
750
751Sometimes the build system doesn't rebuild the application correctly
752because it fails to recompile one or more necessary files. You can force
753the build system to rebuild the entire application from scratch with the
754following procedure:
755
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400756#. Open a terminal console on your host computer, and navigate to the
Carles Cufi0008e342018-01-18 18:02:12 +0100757 build directory :file:`<home>/app/build`.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400758
Carles Cufib4766432019-06-13 21:59:12 +0200759#. Enter one of the following commands, depending on whether you want to use
760 ``west`` or ``cmake`` directly to delete the application's generated
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400761 files, except for the :file:`.config` file that contains the
762 application's current configuration information.
763
764 .. code-block:: console
765
Carles Cufib4766432019-06-13 21:59:12 +0200766 west build -t clean
767
768 or
769
770 .. code-block:: console
771
Carles Cufi0008e342018-01-18 18:02:12 +0100772 ninja clean
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400773
Carles Cufib4766432019-06-13 21:59:12 +0200774 Alternatively, enter one of the following commands to delete *all*
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400775 generated files, including the :file:`.config` files that contain
776 the application's current configuration information for those board
777 types.
778
779 .. code-block:: console
780
Carles Cufib4766432019-06-13 21:59:12 +0200781 west build -t pristine
782
783 or
784
785 .. code-block:: console
786
Carles Cufi0008e342018-01-18 18:02:12 +0100787 ninja pristine
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400788
Carles Cufib4766432019-06-13 21:59:12 +0200789 If you use west, you can take advantage of its capability to automatically
790 :ref:`make the build folder pristine <west-building-config>` whenever it is
791 required.
792
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400793#. Rebuild the application normally following the steps specified
794 in :ref:`build_an_application` above.
795
Torsten Rasmussen0f4fc992020-11-13 09:14:42 +0100796.. _application_board_version:
797
798Building for a board revision
799=============================
800
801The Zephyr build system has support for specifying multiple hardware revisions
802of a single board with small variations. Using revisions allows the board
803support files to make minor adjustments to a board configuration without
804duplicating all the files described in :ref:`create-your-board-directory` for
805each revision.
806
807To build for a particular revision, use ``<board>@<revision>`` instead of plain
808``<board>``. For example:
809
810.. zephyr-app-commands::
811 :tool: all
812 :cd-into:
813 :board: <board>@<revision>
814 :goals: build
815 :compact:
816
817Check your board's documentation for details on whether it has multiple
818revisions, and what revisions are supported.
819
820When targeting a board revision, the active revision will be printed at CMake
821configure time, like this:
822
823.. code-block:: console
824
825 -- Board: plank, Revision: 1.5.0
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400826
827.. _application_run:
828
829Run an Application
830******************
831
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400832An application image can be run on a real board or emulated hardware.
833
Carles Cufi8f05a4c2019-03-07 15:59:20 +0100834.. _application_run_board:
835
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400836Running on a Board
837==================
838
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400839Most boards supported by Zephyr let you flash a compiled binary using
Carles Cufib4766432019-06-13 21:59:12 +0200840the ``flash`` target to copy the binary to the board and run it.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400841Follow these instructions to flash and run an application on real
842hardware:
843
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400844#. Build your application, as described in :ref:`build_an_application`.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400845
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400846#. Make sure your board is attached to your host computer. Usually, you'll do
847 this via USB.
848
Carles Cufib4766432019-06-13 21:59:12 +0200849#. Run one of these console commands from the build directory,
850 :file:`<home>/app/build`, to flash the compiled Zephyr image and run it on
851 your board:
852
853 .. code-block:: console
854
855 west flash
856
857 or
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400858
859 .. code-block:: console
860
Carles Cufi0008e342018-01-18 18:02:12 +0100861 ninja flash
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400862
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400863The Zephyr build system integrates with the board support files to
864use hardware-specific tools to flash the Zephyr binary to your
865hardware, then run it.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400866
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400867Each time you run the flash command, your application is rebuilt and flashed
868again.
869
870In cases where board support is incomplete, flashing via the Zephyr build
871system may not be supported. If you receive an error message about flash
872support being unavailable, consult :ref:`your board's documentation <boards>`
873for additional information on how to flash your board.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400874
875.. note:: When developing on Linux, it's common to need to install
876 board-specific udev rules to enable USB device access to
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400877 your board as a non-root user. If flashing fails,
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400878 consult your board's documentation to see if this is
879 necessary.
880
Carles Cufi8f05a4c2019-03-07 15:59:20 +0100881.. _application_run_qemu:
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400882
883Running in an Emulator
884======================
885
Carles Cufi0008e342018-01-18 18:02:12 +0100886The kernel has built-in emulator support for QEMU (on Linux/macOS only, this
887is not yet supported on Windows). It allows you to run and test an application
888virtually, before (or in lieu of) loading and running it on actual target
889hardware. Follow these instructions to run an application via QEMU:
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400890
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400891#. Build your application for one of the QEMU boards, as described in
892 :ref:`build_an_application`.
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400893
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400894 For example, you could set ``BOARD`` to:
895
896 - ``qemu_x86`` to emulate running on an x86-based board
897 - ``qemu_cortex_m3`` to emulate running on an ARM Cortex M3-based board
898
Carles Cufib4766432019-06-13 21:59:12 +0200899#. Run one of these console commands from the build directory,
900 :file:`<home>/app/build`, to run the Zephyr binary in QEMU:
901
902 .. code-block:: console
903
904 west build -t run
905
906 or
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400907
908 .. code-block:: console
909
Carles Cufi0008e342018-01-18 18:02:12 +0100910 ninja run
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400911
912#. Press :kbd:`Ctrl A, X` to stop the application from running
913 in QEMU.
914
915 The application stops running and the terminal console prompt
916 redisplays.
917
Marti Bolivarca46dfa2017-11-03 14:12:46 -0400918Each time you execute the run command, your application is rebuilt and run
919again.
920
Anas Nashif1d4e0892018-08-21 10:25:52 -0500921
Marti Bolivara506baf2019-05-14 08:29:18 -0600922.. note::
923
924 If the (Linux only) :ref:`Zephyr SDK <zephyr_sdk>` is installed, the ``run``
925 target will use the SDK's QEMU binary by default. To use another version of
926 QEMU, :ref:`set the environment variable <env_vars>` :envvar:`QEMU_BIN_PATH`
927 to the path of the QEMU binary you want to use instead.
Anas Nashif1d4e0892018-08-21 10:25:52 -0500928
Filip Kokosinski5980f892021-10-05 12:16:09 +0200929.. note::
930
931 You can choose a specific emulator by appending ``_<emulator>`` to your
932 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
933 for QEMU.
934
Marti Bolivar9c85c7f2017-11-03 12:34:22 -0400935.. _application_debugging:
Anas Nashif5342bc62021-05-06 09:48:14 -0400936
937Application Debugging
938*********************
939
940This section is a quick hands-on reference to start debugging your
941application with QEMU. Most content in this section is already covered in
942`QEMU`_ and `GNU_Debugger`_ reference manuals.
943
944.. _QEMU: http://wiki.qemu.org/Main_Page
945
946.. _GNU_Debugger: http://www.gnu.org/software/gdb
947
948In this quick reference, you'll find shortcuts, specific environmental
949variables, and parameters that can help you to quickly set up your debugging
950environment.
951
952The simplest way to debug an application running in QEMU is using the GNU
953Debugger and setting a local GDB server in your development system through QEMU.
954
955You will need an Executable and Linkable Format (ELF) binary image for
956debugging purposes. The build system generates the image in the build
957directory. By default, the kernel binary name is
958:file:`zephyr.elf`. The name can be changed using a Kconfig option.
959
960We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
961server instance. This port number can be changed for a port that best suits the
962development environment.
963
964You can run QEMU to listen for a "gdb connection" before it starts executing any
965code to debug it.
966
967.. code-block:: bash
968
969 qemu -s -S <image>
970
971will setup Qemu to listen on port 1234 and wait for a GDB connection to it.
972
973The options used above have the following meaning:
974
975* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
976 monitor.
977* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
978 TCP port 1234.
979
980To debug with QEMU and to start a GDB server and wait for a remote connect, run
981either of the following inside the build directory of an application:
982
983.. code-block:: bash
984
985 ninja debugserver
986
987The build system will start a QEMU instance with the CPU halted at startup
988and with a GDB server instance listening at the TCP port 1234.
989
990Using a local GDB configuration :file:`.gdbinit` can help initialize your GDB
991instance on every run.
992In this example, the initialization file points to the GDB server instance.
993It configures a connection to a remote target at the local host on the TCP
994port 1234. The initialization sets the kernel's root directory as a
995reference.
996
997The :file:`.gdbinit` file contains the following lines:
998
999.. code-block:: bash
1000
1001 target remote localhost:1234
1002 dir ZEPHYR_BASE
1003
1004.. note::
1005
1006 Substitute the correct :ref:`ZEPHYR_BASE <important-build-vars>` for your
1007 system.
1008
1009Execute the application to debug from the same directory that you chose for
1010the :file:`gdbinit` file. The command can include the ``--tui`` option
1011to enable the use of a terminal user interface. The following commands
1012connects to the GDB server using :file:`gdb`. The command loads the symbol
1013table from the elf binary file. In this example, the elf binary file name
1014corresponds to :file:`zephyr.elf` file:
1015
1016.. code-block:: bash
1017
1018 ..../path/to/gdb --tui zephyr.elf
1019
1020.. note::
1021
1022 The GDB version on the development system might not support the --tui
1023 option. Please make sure you use the GDB binary from the SDK which
1024 corresponds to the toolchain that has been used to build the binary.
1025
1026If you are not using a .gdbinit file, issue the following command inside GDB to
1027connect to the remote GDB server on port 1234:
1028
1029.. code-block:: bash
1030
1031 (gdb) target remote localhost:1234
1032
1033Finally, the command below connects to the GDB server using the Data
1034Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
1035elf binary file, in this instance, the :file:`zephyr.elf` file.
1036
1037The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
1038development system by default. Follow your system instructions to install
1039it. For example, use ``sudo apt-get install ddd`` on an Ubuntu system.
1040
1041.. code-block:: bash
1042
1043 ddd --gdb --debugger "gdb zephyr.elf"
1044
1045
1046Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might
1047change depending on the toolchain you are using and your cross-development
1048tools.
1049
Sebastian Bøebdc5c722018-03-26 09:48:57 +02001050.. _custom_board_definition:
Anas Nashife172fa32018-02-11 22:30:57 -06001051
Peter A. Bigotb7ce0a22020-08-21 14:47:44 -05001052Custom Board, Devicetree and SOC Definitions
Sebastian Bøe397abd42019-03-14 13:06:40 +01001053********************************************
Anas Nashife172fa32018-02-11 22:30:57 -06001054
Sebastian Bøe397abd42019-03-14 13:06:40 +01001055In cases where the board or platform you are developing for is not yet
Peter A. Bigotb7ce0a22020-08-21 14:47:44 -05001056supported by Zephyr, you can add board, Devicetree and SOC definitions
Sebastian Bøe397abd42019-03-14 13:06:40 +01001057to your application without having to add them to the Zephyr tree.
Anas Nashife172fa32018-02-11 22:30:57 -06001058
Anas Nashif16661302018-09-12 22:04:17 -05001059The structure needed to support out-of-tree board and SOC development
1060is similar to how boards and SOCs are maintained in the Zephyr tree. By using
1061this structure, it will be much easier to upstream your platform related work into
Anas Nashife172fa32018-02-11 22:30:57 -06001062the Zephyr tree after your initial development is done.
1063
Anas Nashif16661302018-09-12 22:04:17 -05001064Add the custom board to your application or a dedicated repository using the
1065following structure:
Anas Nashife172fa32018-02-11 22:30:57 -06001066
1067.. code-block:: console
1068
1069 boards/
Anas Nashif16661302018-09-12 22:04:17 -05001070 soc/
Anas Nashife172fa32018-02-11 22:30:57 -06001071 CMakeLists.txt
1072 prj.conf
1073 README.rst
1074 src/
1075
1076where the ``boards`` directory hosts the board you are building for:
1077
1078.. code-block:: console
1079
1080 .
1081 ├── boards
David B. Kinder7760b942018-05-31 14:09:46 -07001082 │ └── x86
1083 │ └── my_custom_board
1084 │ ├── doc
1085 │ │ └── img
1086 │ └── support
Anas Nashife172fa32018-02-11 22:30:57 -06001087 └── src
1088
Anas Nashif16661302018-09-12 22:04:17 -05001089and the ``soc`` directory hosts any SOC code. You can also have boards that are
1090supported by a SOC that is available in the Zephyr tree.
1091
1092Boards
1093======
Anas Nashife172fa32018-02-11 22:30:57 -06001094
1095Use the proper architecture folder name (e.g., ``x86``, ``arm``, etc.)
1096under ``boards`` for ``my_custom_board``. (See :ref:`boards` for a
1097list of board architectures.)
1098
1099Documentation (under ``doc/``) and support files (under ``support/``) are optional, but
1100will be needed when submitting to Zephyr.
1101
1102The contents of ``my_custom_board`` should follow the same guidelines for any
1103Zephyr board, and provide the following files::
1104
1105 my_custom_board_defconfig
1106 my_custom_board.dts
1107 my_custom_board.yaml
1108 board.cmake
1109 board.h
1110 CMakeLists.txt
1111 doc/
Sebastian Bøe8eb734c2018-10-08 10:55:43 +02001112 dts_fixup.h
Anas Nashife172fa32018-02-11 22:30:57 -06001113 Kconfig.board
1114 Kconfig.defconfig
1115 pinmux.c
1116 support/
1117
1118
1119Once the board structure is in place, you can build your application
1120targeting this board by specifying the location of your custom board
1121information with the ``-DBOARD_ROOT`` parameter to the CMake
Carles Cufib4766432019-06-13 21:59:12 +02001122build system:
Anas Nashife172fa32018-02-11 22:30:57 -06001123
Carles Cufib4766432019-06-13 21:59:12 +02001124.. zephyr-app-commands::
1125 :tool: all
1126 :board: <board name>
1127 :gen-args: -DBOARD_ROOT=<path to boards>
1128 :goals: build
1129 :compact:
Anas Nashife172fa32018-02-11 22:30:57 -06001130
1131This will use your custom board configuration and will generate the
1132Zephyr binary into your application directory.
1133
1134You can also define the ``BOARD_ROOT`` variable in the application
Martí Bolívare2b72a02020-06-23 16:55:10 -07001135:file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the Zephyr
1136boilerplate with ``find_package(Zephyr ...)``.
Anas Nashife172fa32018-02-11 22:30:57 -06001137
Torsten Rasmussenfb16a3d2020-09-08 14:07:00 +02001138.. note::
1139
1140 When specifying ``BOARD_ROOT`` in a CMakeLists.txt, then an absolute path must
1141 be provided, for example ``list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>``.
1142 When using ``-DBOARD_ROOT=<board-root>`` both absolute and relative paths can
1143 be used. Relative paths are treated relatively to the application directory.
Anas Nashif16661302018-09-12 22:04:17 -05001144
1145SOC Definitions
1146===============
1147
1148Similar to board support, the structure is similar to how SOCs are maintained in
1149the Zephyr tree, for example:
1150
Ulf Magnussonacc829c2019-12-04 12:29:07 +01001151.. code-block:: none
Anas Nashif16661302018-09-12 22:04:17 -05001152
1153 soc
1154 └── arm
1155 └── st_stm32
1156 ├── common
Erwan Gouriou7a9f4f62018-09-13 14:13:32 +02001157 └── stm32l0
Anas Nashif16661302018-09-12 22:04:17 -05001158
1159
1160
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001161The file :zephyr_file:`soc/Kconfig` will create the top-level
1162``SoC/CPU/Configuration Selection`` menu in Kconfig.
Anas Nashif16661302018-09-12 22:04:17 -05001163
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001164Out of tree SoC definitions can be added to this menu using the ``SOC_ROOT``
1165CMake variable. This variable contains a semicolon-separated list of directories
1166which contain SoC support files.
Anas Nashif16661302018-09-12 22:04:17 -05001167
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001168Following the structure above, the following files can be added to load
1169more SoCs into the menu.
Anas Nashif16661302018-09-12 22:04:17 -05001170
Ulf Magnussonacc829c2019-12-04 12:29:07 +01001171.. code-block:: none
Anas Nashif16661302018-09-12 22:04:17 -05001172
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001173 soc
1174 └── arm
1175 └── st_stm32
1176 ├── Kconfig
1177 ├── Kconfig.soc
1178 └── Kconfig.defconfig
Anas Nashif16661302018-09-12 22:04:17 -05001179
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001180The Kconfig files above may describe the SoC or load additional SoC Kconfig files.
Anas Nashif16661302018-09-12 22:04:17 -05001181
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001182An example of loading ``stm31l0`` specific Kconfig files in this structure:
Anas Nashif16661302018-09-12 22:04:17 -05001183
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001184.. code-block:: none
Anas Nashif16661302018-09-12 22:04:17 -05001185
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001186 soc
1187 └── arm
1188 └── st_stm32
1189 ├── Kconfig.soc
1190 └── stm32l0
1191 └── Kconfig.series
1192
1193can be done with the following content in ``st_stm32/Kconfig.soc``:
1194
1195.. code-block:: none
1196
1197 rsource "*/Kconfig.series"
Anas Nashif16661302018-09-12 22:04:17 -05001198
1199Once the SOC structure is in place, you can build your application
1200targeting this platform by specifying the location of your custom platform
1201information with the ``-DSOC_ROOT`` parameter to the CMake
Carles Cufib4766432019-06-13 21:59:12 +02001202build system:
Anas Nashif16661302018-09-12 22:04:17 -05001203
Carles Cufib4766432019-06-13 21:59:12 +02001204.. zephyr-app-commands::
1205 :tool: all
1206 :board: <board name>
1207 :gen-args: -DSOC_ROOT=<path to soc> -DBOARD_ROOT=<path to boards>
1208 :goals: build
1209 :compact:
Anas Nashif16661302018-09-12 22:04:17 -05001210
1211This will use your custom platform configurations and will generate the
1212Zephyr binary into your application directory.
1213
Torsten Rasmussen650cf3c2020-08-07 14:34:13 +02001214See :ref:`modules_build_settings` for information on setting SOC_ROOT in a module's
1215:file:`zephyr/module.yml` file.
1216
1217Or you can define the ``SOC_ROOT`` variable in the application
Martí Bolívare2b72a02020-06-23 16:55:10 -07001218:file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the
1219Zephyr boilerplate with ``find_package(Zephyr ...)``.
Anas Nashif16661302018-09-12 22:04:17 -05001220
Torsten Rasmussenfb16a3d2020-09-08 14:07:00 +02001221.. note::
1222
1223 When specifying ``SOC_ROOT`` in a CMakeLists.txt, then an absolute path must
1224 be provided, for example ``list(APPEND SOC_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-soc-root>``.
1225 When using ``-DSOC_ROOT=<soc-root>`` both absolute and relative paths can be
1226 used. Relative paths are treated relatively to the application directory.
1227
Martí Bolívar6e57b422020-03-10 18:16:25 -07001228.. _dts_root:
1229
Peter A. Bigotb7ce0a22020-08-21 14:47:44 -05001230Devicetree Definitions
Sebastian Bøe397abd42019-03-14 13:06:40 +01001231======================
1232
Peter A. Bigotb7ce0a22020-08-21 14:47:44 -05001233Devicetree directory trees are found in ``APPLICATION_SOURCE_DIR``,
Peter A. Bigot8437ab12019-07-04 09:48:53 -05001234``BOARD_DIR``, and ``ZEPHYR_BASE``, but additional trees, or DTS_ROOTs,
1235can be added by creating this directory tree::
Sebastian Bøe397abd42019-03-14 13:06:40 +01001236
Peter A. Bigot8437ab12019-07-04 09:48:53 -05001237 include/
Sebastian Bøe397abd42019-03-14 13:06:40 +01001238 dts/common/
1239 dts/arm/
Peter A. Bigot8437ab12019-07-04 09:48:53 -05001240 dts/
1241 dts/bindings/
Sebastian Bøe397abd42019-03-14 13:06:40 +01001242
1243Where 'arm' is changed to the appropriate architecture. Each directory
1244is optional. The binding directory contains bindings and the other
1245directories contain files that can be included from DT sources.
1246
1247Once the directory structure is in place, you can use it by specifying
Carles Cufib4766432019-06-13 21:59:12 +02001248its location through the ``DTS_ROOT`` CMake Cache variable:
Sebastian Bøe397abd42019-03-14 13:06:40 +01001249
Carles Cufib4766432019-06-13 21:59:12 +02001250.. zephyr-app-commands::
1251 :tool: all
1252 :board: <board name>
1253 :gen-args: -DDTS_ROOT=<path to dts root>
1254 :goals: build
1255 :compact:
Sebastian Bøe397abd42019-03-14 13:06:40 +01001256
Martí Bolívare2b72a02020-06-23 16:55:10 -07001257You can also define the variable in the application :file:`CMakeLists.txt`
1258file. Make sure to do so **before** pulling in the Zephyr boilerplate with
1259``find_package(Zephyr ...)``.
Sebastian Bøe397abd42019-03-14 13:06:40 +01001260
Torsten Rasmussenfb16a3d2020-09-08 14:07:00 +02001261.. note::
1262
1263 When specifying ``DTS_ROOT`` in a CMakeLists.txt, then an absolute path must
1264 be provided, for example ``list(APPEND DTS_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-dts-root>``.
1265 When using ``-DDTS_ROOT=<dts-root>`` both absolute and relative paths can be
1266 used. Relative paths are treated relatively to the application directory.
1267
Peter A. Bigot0950b252020-08-21 14:52:15 -05001268Devicetree source are passed through the C preprocessor, so you can
1269include files that can be located in a ``DTS_ROOT`` directory. By
1270convention devicetree include files have a ``.dtsi`` extension.
1271
1272You can also use the preprocessor to control the content of a devicetree
1273file, by specifying directives through the ``DTS_EXTRA_CPPFLAGS`` CMake
1274Cache variable:
1275
1276.. zephyr-app-commands::
1277 :tool: all
1278 :board: <board name>
1279 :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE
1280 :goals: build
1281 :compact:
Carles Cufi01e05522019-01-31 19:32:02 +01001282
Marti Bolivar9c85c7f2017-11-03 12:34:22 -04001283
1284
Anas Nashif5342bc62021-05-06 09:48:14 -04001285Debug with Eclipse
1286******************
Maureen Helme2d73fb2018-03-19 15:27:19 -05001287
1288Overview
1289========
1290
1291CMake supports generating a project description file that can be imported into
1292the Eclipse Integrated Development Environment (IDE) and used for graphical
1293debugging.
1294
1295The `GNU MCU Eclipse plug-ins`_ provide a mechanism to debug ARM projects in
1296Eclipse with pyOCD, Segger J-Link, and OpenOCD debugging tools.
1297
1298The following tutorial demonstrates how to debug a Zephyr application in
1299Eclipse with pyOCD in Windows. It assumes you have already installed the GCC
1300ARM Embedded toolchain and pyOCD.
1301
1302Set Up the Eclipse Development Environment
1303==========================================
1304
1305#. Download and install `Eclipse IDE for C/C++ Developers`_.
1306
1307#. In Eclipse, install the GNU MCU Eclipse plug-ins by opening the menu
1308 ``Window->Eclipse Marketplace...``, searching for ``GNU MCU Eclipse``, and
1309 clicking ``Install`` on the matching result.
1310
1311#. Configure the path to the pyOCD GDB server by opening the menu
1312 ``Window->Preferences``, navigating to ``MCU``, and setting the ``Global
1313 pyOCD Path``.
1314
1315Generate and Import an Eclipse Project
1316======================================
1317
Marti Bolivar5edb6d52019-05-06 23:36:30 -06001318#. Set up a GNU Arm Embedded toolchain as described in
1319 :ref:`third_party_x_compilers`.
Maureen Helme2d73fb2018-03-19 15:27:19 -05001320
1321#. Navigate to a folder outside of the Zephyr tree to build your application.
1322
1323 .. code-block:: console
1324
1325 # On Windows
1326 cd %userprofile%
1327
1328 .. note::
1329 If the build directory is a subdirectory of the source directory, as is
1330 usually done in Zephyr, CMake will warn:
1331
1332 "The build directory is a subdirectory of the source directory.
1333
1334 This is not supported well by Eclipse. It is strongly recommended to use
1335 a build directory which is a sibling of the source directory."
1336
1337#. Configure your application with CMake and build it with ninja. Note the
1338 different CMake generator specified by the ``-G"Eclipse CDT4 - Ninja"``
1339 argument. This will generate an Eclipse project description file,
1340 :file:`.project`, in addition to the usual ninja build files.
1341
Carles Cufib4766432019-06-13 21:59:12 +02001342 .. zephyr-app-commands::
1343 :tool: all
1344 :app: %ZEPHYR_BASE%\samples\synchronization
1345 :host-os: win
1346 :board: frdm_k64f
1347 :gen-args: -G"Eclipse CDT4 - Ninja"
1348 :goals: build
1349 :compact:
Maureen Helme2d73fb2018-03-19 15:27:19 -05001350
1351#. In Eclipse, import your generated project by opening the menu
1352 ``File->Import...`` and selecting the option ``Existing Projects into
1353 Workspace``. Browse to your application build directory in the choice,
1354 ``Select root directory:``. Check the box for your project in the list of
1355 projects found and click the ``Finish`` button.
1356
1357Create a Debugger Configuration
1358===============================
1359
1360#. Open the menu ``Run->Debug Configurations...``.
1361
1362#. Select ``GDB PyOCD Debugging``, click the ``New`` button, and configure the
1363 following options:
1364
1365 - In the Main tab:
1366
Reto Schneider7eabab22018-10-25 16:54:09 +02001367 - Project: my_zephyr_app@build
Maureen Helme2d73fb2018-03-19 15:27:19 -05001368 - C/C++ Application: :file:`zephyr/zephyr.elf`
1369
1370 - In the Debugger tab:
1371
1372 - pyOCD Setup
1373
David B. Kinder34d02e52018-03-21 10:10:46 -07001374 - Executable path: :file:`${pyocd_path}\\${pyocd_executable}`
Maureen Helme2d73fb2018-03-19 15:27:19 -05001375 - Uncheck "Allocate console for semihosting"
1376
1377 - Board Setup
1378
1379 - Bus speed: 8000000 Hz
1380 - Uncheck "Enable semihosting"
1381
1382 - GDB Client Setup
1383
Marti Bolivar5edb6d52019-05-06 23:36:30 -06001384 - Executable path example (use your :envvar:`GNUARMEMB_TOOLCHAIN_PATH`):
David B. Kinder34d02e52018-03-21 10:10:46 -07001385 :file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe`
Maureen Helme2d73fb2018-03-19 15:27:19 -05001386
1387 - In the SVD Path tab:
1388
Martí Bolívar2d9baf92020-05-05 09:45:25 -07001389 - File path: :file:`<workspace
1390 top>\\modules\\hal\\nxp\\mcux\\devices\\MK64F12\\MK64F12.xml`
Maureen Helme2d73fb2018-03-19 15:27:19 -05001391
1392 .. note::
1393 This is optional. It provides the SoC's memory-mapped register
1394 addresses and bitfields to the debugger.
1395
1396#. Click the ``Debug`` button to start debugging.
1397
1398RTOS Awareness
1399==============
1400
Maureen Helmd7d10902018-07-26 08:37:31 -05001401Support for Zephyr RTOS awareness is implemented in `pyOCD v0.11.0`_ and later.
1402It is compatible with GDB PyOCD Debugging in Eclipse, but you must enable
Carles Cufid2465d62021-03-11 19:51:35 +01001403CONFIG_DEBUG_THREAD_INFO=y in your application.
Maureen Helme2d73fb2018-03-19 15:27:19 -05001404
Daniel Thompson4d096a42017-02-17 10:21:20 +00001405
Maureen Helme2d73fb2018-03-19 15:27:19 -05001406
Carles Cufib4766432019-06-13 21:59:12 +02001407.. _CMake: https://www.cmake.org
1408.. _CMake introduction: https://cmake.org/cmake/help/latest/manual/cmake.1.html#description
Maureen Helme2d73fb2018-03-19 15:27:19 -05001409.. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygen2
1410.. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/
Maureen Helmd7d10902018-07-26 08:37:31 -05001411.. _pyOCD v0.11.0: https://github.com/mbedmicro/pyOCD/releases/tag/v0.11.0
Marti Bolivar7eca2562019-04-02 13:55:25 -06001412.. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists
1413.. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html
Anas Nashifbf9ceac2021-04-15 14:40:00 -04001414.. _using Chocolatey: https://chocolatey.org/packages/RapidEE
Gerard Marull-Paretasc1a97ac2021-05-26 16:13:39 +02001415.. _Example Application: https://github.com/zephyrproject-rtos/example-application