Lines Matching +full:in +full:- +full:application
3 Application Development
8 In this document, we'll assume:
10 …- your **application directory**, :file:`<app>`, is something like :file:`<home>/zephyrproject/app`
11 - its **build directory** is :file:`<app>/build`
16 Keeping your application inside the workspace (:file:`<home>/zephyrproject`)
18 put your application anywhere as long as :ref:`ZEPHYR_BASE
19 <important-build-vars>` is set appropriately, though.)
26 The build system is application-centric, and requires Zephyr-based applications
27 to initiate building the Zephyr source code. The application build controls
28 the configuration and build process of both the application and Zephyr itself,
36 The files in the **application directory** link Zephyr and any modules with the
37 application. This directory contains all application-specific files, such as
38 application-specific configuration files and source code.
40 Here are the files in a simple Zephyr application:
42 .. code-block:: none
55 application files, and links the application directory with Zephyr's CMake
57 such as board-specific configuration files, the ability to run and
61 application-specific changes which should be applied to the base devicetree
63 usually to configure something about the hardware used by the application.
70 * **prj.conf**: This is a Kconfig fragment that specifies application-specific
71 values for one or more Kconfig options. These application settings are merged
74 the application.
79 See :ref:`application-kconfig` below for more information.
82 These fields let you manage the lifecycle of the application and automate
83 providing the application version when signing application images.
85 See :ref:`app-version-details` for more information about this file and how to use it.
88 written in C, C++, or assembly language. The Zephyr convention is to place
89 them in a subdirectory of :file:`<app>` named :file:`src`.
91 Once an application has been defined, you will use CMake to generate a **build
92 directory**, which contains the files you need to build the application and
94 The easiest way to do this is with :ref:`west build <west-building>`, but you
95 can use CMake directly also. Application build artifacts are always generated
96 in a separate build directory: Zephyr does not support "in-tree" builds.
101 .. _zephyr-app-types:
103 Application types
106 We distinguish three basic types of Zephyr application based on where
111 +------------------------------+--------------------------------+
112 | Application type | :file:`<app>` location |
113 +------------------------------+--------------------------------+
115 | <zephyr-repo-app>` | |
116 +------------------------------+--------------------------------+
118 | <zephyr-workspace-app>` | installed |
119 +------------------------------+--------------------------------+
121 | <zephyr-freestanding-app>` | |
122 +------------------------------+--------------------------------+
127 .. _zephyr-repo-app:
129 Zephyr repository application
132 An application located within the ``zephyr`` source code repository in a Zephyr
133 :ref:`west workspace <west-workspaces>` is referred to as a Zephyr repository
134 application. In the following example, the :zephyr:code-sample:`hello_world sample
135 <hello_world>` is a Zephyr repository application:
137 .. code-block:: none
152 .. _zephyr-workspace-app:
154 Zephyr workspace application
157 An application located within a :ref:`workspace <west-workspaces>`, but outside
158 the zephyr repository itself, is referred to as a Zephyr workspace application.
159 In the following example, ``app`` is a Zephyr workspace application:
161 .. code-block:: none
170 ├─── <vendor/private-repositories>/
174 .. _zephyr-freestanding-app:
176 Zephyr freestanding application
179 A Zephyr application located outside of a Zephyr :ref:`workspace
180 <west-workspaces>` is referred to as a Zephyr freestanding application. In the
181 following example, ``app`` is a Zephyr freestanding application:
183 .. code-block:: none
200 .. _zephyr-creating-app:
202 Creating an Application
205 In Zephyr, you can either use a reference workspace application or create your application by hand.
207 .. _zephyr-creating-app-from-example:
209 Using a Reference Workspace Application argument
212 The `example-application`_ Git repository contains a reference :ref:`workspace
213 application <zephyr-workspace-app>`. It is recommended to use it as a reference
214 when creating your own application as described in the following sections.
216 The example-application repository demonstrates how to use several
217 commonly-used features, such as:
219 - Custom :ref:`board ports <board_porting_guide>`
220 - Custom :ref:`devicetree bindings <dt-bindings>`
221 - Custom :ref:`device drivers <device_model_api>`
222 - Continuous Integration (CI) setup, including using :ref:`twister <twister_script>`
223 - A custom west :ref:`extension command <west-extensions>`
225 Basic example-application Usage
228 The easiest way to get started with the example-application repository within
231 .. code-block:: console
234 git clone https://github.com/zephyrproject-rtos/example-application my-app
236 The directory name :file:`my-app` above is arbitrary: change it as needed. You
241 Advanced example-application Usage
244 You can also use the example-application repository as a starting point for
245 building your own customized Zephyr-based software distribution. This lets you
248 - remove Zephyr modules you don't need
249 - add additional custom repositories of your own
250 - override repositories provided by Zephyr with your own versions
251 - share the results with others and collaborate further
253 The example-application repository contains a :file:`west.yml` file and is
254 therefore also a west :ref:`manifest repository <west-workspace>`. Use this to
257 .. code-block:: console
260 mkdir my-workspace
261 cd my-workspace
262 git clone https://github.com/zephyrproject-rtos/example-application my-manifest-repo
263 west init -l my-manifest-repo
265 This will create a new workspace with the :ref:`T2 topology <west-t2>`, with
266 :file:`my-manifest-repo` as the manifest repository. The :file:`my-workspace`
267 and :file:`my-manifest-repo` names are arbitrary: change them as needed.
270 repository will match the example-application's contents when you clone it. You
271 can then edit :file:`my-manifest-repo/west.yml` to your liking, changing the
272 set of repositories in it as you wish. See :ref:`west-manifest-import` for many
278 .. code-block::
284 If you push the resulting :file:`my-manifest-repo` repository somewhere else,
286 repository to ``https://git.example.com/my-manifest-repo``. Other people can
289 .. code-block::
291 west init -m https://git.example.com/my-manifest-repo my-workspace
292 cd my-workspace
296 the repositories you are using and updating :file:`my-manifest-repo/west.yml`
299 .. _zephyr-creating-app-by-hand:
301 Creating an Application by Hand argument
304 You can follow these steps to create a basic application directory from
305 scratch. However, using the `example-application`_ repository or one of
306 Zephyr's :zephyr:code-sample-category:`samples` as a starting point is likely to be easier.
308 #. Create an application directory.
310 For example, in a Unix shell or Windows ``cmd.exe`` prompt:
312 .. code-block:: console
318 Building Zephyr or creating an application in a directory with spaces
325 It's recommended to place all application source code in a subdirectory
331 .. code-block:: console
336 #. Place your application source code in the :file:`src` sub-directory. For
339 #. Create a file named :file:`CMakeLists.txt` in the ``app`` directory with the
342 .. code-block:: cmake
353 - The ``cmake_minimum_required()`` call is required by CMake. It is also
355 its version is older than either the version in your
356 :file:`CMakeLists.txt` or the version number in the Zephyr package.
358 - ``find_package(Zephyr)`` pulls in the Zephyr build system, which creates a
360 target is how you include them in the build. The Zephyr package will
361 define ``Zephyr-Kernel`` as a CMake project and enable support for the
364 - ``project(my_zephyr_app)`` defines your application's CMake
366 interference with Zephyr's ``project(Zephyr-Kernel)``.
368 - ``target_sources(app PRIVATE src/main.c)`` is to add your source file to
373 #. Create at least one Kconfig fragment for your application (usually named
374 :file:`prj.conf`) and set Kconfig option values needed by your application
375 there. See :ref:`application-kconfig`. If no Kconfig options need to be set,
378 #. Configure any devicetree overlays needed by your application, usually in a
379 file named :file:`app.overlay`. See :ref:`set-devicetree-overlays`.
384 .. _important-build-vars:
396 :makevar:`DTC_OVERLAY_FILE` can be supplied to the build system in
397 3 ways (in order of precedence):
400 ``-D`` command-line switch. If you have multiple overlay files, you should
403 * As a ``set(<VARIABLE> <VALUE>)`` statement in your :file:`CMakeLists.txt`
407 variable. But ``ZEPHYR_BASE`` can also be set as an environment variable in
410 * :makevar:`BOARD`: Selects the board that the application's build
412 built-in boards, and :ref:`board_porting_guide` for information on
420 See :ref:`initial-conf` for more information.
424 can be useful in order to leave :makevar:`CONF_FILE` at its default value,
425 but "mix in" some additional configuration options.
429 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
434 :makevar:`DTC_OVERLAY_FILE` at its default value, but "mix in" some additional
440 additional directories with source code, Kconfig, etc. that should be used in
441 the application build. See :ref:`modules` for details. If you set this
450 the name without the prefix). See :ref:`application-file-suffixes` for details.
457 .. _zephyr-app-cmakelists:
459 Application CMakeLists.txt
462 Every application must have a :file:`CMakeLists.txt` file. This file is the
464 image contains both the application and the kernel libraries.
466 This section describes some of what you can do in your :file:`CMakeLists.txt`.
467 Make sure to follow these steps in order.
470 configuration for your application on a new line. For example:
472 .. code-block:: cmake
479 the following, in order (when a BOARD value is found, CMake stops looking
482 - Any previously used value as determined by the CMake cache takes highest
486 - Any value given on the CMake command line (directly or indirectly via
487 ``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and
490 - If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
493 - Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
494 as described in this step, this value will be used.
496 #. If your application uses a configuration file or files other than
500 build up configuration fragment files in a modular way when you want to
501 avoid setting :makevar:`CONF_FILE` in a single place. For example:
503 .. code-block:: cmake
508 See :ref:`initial-conf` for more information.
510 #. If your application uses devicetree overlays, you may need to set
511 :ref:`DTC_OVERLAY_FILE <important-build-vars>`.
512 See :ref:`set-devicetree-overlays`.
514 #. If your application has its own kernel configuration options,
515 create a :file:`Kconfig` file in the same directory as your
516 application's :file:`CMakeLists.txt`.
521 An (unlikely) advanced use case would be if your application has its own
525 If you just want to set application specific **values** for existing Zephyr
530 .. literalinclude:: application-kconfig.include
535 Environment variables in ``source`` statements are expanded directly, so
542 The :file:`Kconfig` file is automatically detected when placed in
543 the application directory, but it is also possible for it to be
547 #. Specify that the application requires Zephyr on a new line, **after any
550 .. code-block:: cmake
558 supported. All samples in Zephyr supports the ``ZEPHYR_BASE``
561 #. Now add any application source files to the 'app' target
564 .. code-block:: cmake
570 .. code-block:: cmake
580 leverages the application configuration provided by
582 with the hex file generated when building the Zephyr application.
585 .. code-block:: cmake
592 .. _zephyr-app-cmakecache:
600 when CMake is run in an empty build folder.
607 Application Configuration
610 .. _application-configuration-directory:
612 Application Configuration Directory
615 Zephyr will use configuration files from the application's configuration
620 The application configuration directory is defined by the
627 ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before
628 ``find_package(Zephyr)`` then this folder is used a the application's
631 2. The application's source directory.
633 .. _application-kconfig:
638 Application configuration options are usually set in :file:`prj.conf` in the
639 application directory. For example, C++ support could be enabled with this
642 .. code-block:: cfg
646 Looking at :zephyr:code-sample-category:`existing samples <samples>` is a good way to get
650 Kconfig configuration values. The :ref:`initial-conf` section on the same page
651 explains how the initial configuration is derived. See :ref:`kconfig-search`
655 The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
663 are still in early stages of their development cycle. Such features will be
664 marked ``[EXPERIMENTAL]`` in their Kconfig title.
669 .. code-block:: cfg
675 CMake configure time when you build an application:
677 .. code-block:: none
684 See :ref:`set-devicetree-overlays`.
686 .. _application-file-suffixes:
693 configuration. In order to better configure this, Zephyr provides a :makevar:`FILE_SUFFIX` option
700 .. code-block:: none
716 ``prj.conf`` will be used, no application devicetree overlay will be used.
727 When ``CONF_FILE`` is set in the form of ``prj_X.conf`` then the ``X`` will be used as the
731 Application-Specific Code
734 Application-specific source code files are normally added to the
735 application's :file:`src` directory. If the application adds a large
736 number of files the developer can group them into sub-directories
739 Application-specific source code should not use symbol name prefixes that have
742 <https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
744 Third-party Library Code
747 It is possible to build library code outside the application's :file:`src`
748 directory but it is important that both application and library code targets
749 the same Application Binary Interface (ABI). On most architectures there are
751 libraries and applications have certain compiler flags in common. It may also
754 To make it easier to integrate third-party components, the Zephyr
755 build system has defined CMake functions that give application build
757 documented and defined in :zephyr_file:`cmake/modules/extensions.cmake`
761 third-party build system.
774 Building an Application
777 The Zephyr build system compiles and links all components of an application
778 into a single application image that can be run on simulated hardware or real
781 Like any other CMake-based system, the build process takes place :ref:`in
782 two stages <cmake-details>`. First, build files (also known as a buildsystem)
783 are generated using the ``cmake`` command-line tool while specifying a
785 will use in the second stage.
788 the `CMake introduction`_ in the official CMake documentation.
790 Although the default build tool in Zephyr is :std:ref:`west <west>`, Zephyr's
791 meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or
798 choose to use ``west build`` to build your application know that it will
803 .. zephyr-app-commands::
805 :zephyr-app: samples/hello_world
813 - to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
814 command line; see the :ref:`west build <west-building-generator>`
816 - to use ``make`` by default from now on, run ``west config build.generator
821 .. zephyr-app-commands::
823 :zephyr-app: samples/hello_world
825 :host-os: unix
833 #. Navigate to the application directory :file:`<app>`.
834 #. Enter the following commands to build the application's :file:`zephyr.elf`
835 image for the board specified in the command-line parameters:
837 .. zephyr-app-commands::
839 :cd-into:
843 If desired, you can build the application using the configuration settings
844 specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
845 parameter. These settings will override the settings in the application's
848 .. zephyr-app-commands::
850 :cd-into:
852 :gen-args: -DCONF_FILE=prj.alternate.conf
856 As described in the previous section, you can instead choose to permanently
859 in your :file:`CMakeLists.txt` using ``set()`` statements.
861 <west-building-config>`.
863 .. _build-directory-contents:
870 .. code-block:: none
880 The most notable files in the build directory are:
882 * :file:`build.ninja`, which can be invoked to build the application.
889 the :file:`zephyr` sub-directory of the build directory. (This is **not the
894 used to build the application.
903 compiled kernel and application code.
905 * :file:`zephyr.elf`, which contains the final combined application and
911 Rebuilding an Application argument
914 Application development is usually fastest when changes are continually tested.
915 Frequently rebuilding your application makes debugging less painful
916 as the application becomes more complex. It's usually a good idea to
917 rebuild and test after any major changes to the application's source files,
922 The Zephyr build system rebuilds only the parts of the application image
923 potentially affected by the changes. Consequently, rebuilding an application
926 Sometimes the build system doesn't rebuild the application correctly
928 the build system to rebuild the entire application from scratch with the
935 ``west`` or ``cmake`` directly to delete the application's generated
937 application's current configuration information.
939 .. code-block:: console
941 west build -t clean
945 .. code-block:: console
951 the application's current configuration information for those board
954 .. code-block:: console
956 west build -t pristine
960 .. code-block:: console
965 :ref:`make the build folder pristine <west-building-config>` whenever it is
968 #. Rebuild the application normally following the steps specified
969 in :ref:`build_an_application` above.
979 duplicating all the files described in :ref:`create-your-board-directory` for
985 .. zephyr-app-commands::
987 :cd-into:
998 .. code-block:: console
1000 -- Board: plank, Revision: 1.5.0
1004 Run an Application
1007 An application image can be run on a real board or emulated hardware.
1016 Follow these instructions to flash and run an application on real
1019 #. Build your application, as described in :ref:`build_an_application`.
1028 .. code-block:: console
1034 .. code-block:: console
1039 use hardware-specific tools to flash the Zephyr binary to your
1042 Each time you run the flash command, your application is rebuilt and flashed
1045 In cases where board support is incomplete, flashing via the Zephyr build
1051 board-specific udev rules to enable USB device access to
1052 your board as a non-root user. If flashing fails,
1058 Running in an Emulator
1061 Zephyr has built-in emulator support for QEMU.
1062 It allows you to run and test an application virtually, before
1063 (or in lieu of) loading and running it on actual target hardware.
1065 Check out :ref:`beyond-GSG` for additional steps needed on Windows.
1067 Follow these instructions to run an application via QEMU:
1069 #. Build your application for one of the QEMU boards, as described in
1074 - ``qemu_x86`` to emulate running on an x86-based board
1075 - ``qemu_cortex_m3`` to emulate running on an ARM Cortex M3-based board
1078 :file:`<app>/build`, to run the Zephyr binary in QEMU:
1080 .. code-block:: console
1082 west build -t run
1086 .. code-block:: console
1090 #. Press :kbd:`Ctrl A, X` to stop the application from running
1091 in QEMU.
1093 The application stops running and the terminal console prompt
1096 Each time you execute the run command, your application is rebuilt and run
1110 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
1118 In cases where the board or platform you are developing for is not yet
1120 to your application without having to add them to the Zephyr tree.
1122 The structure needed to support out-of-tree board and SOC development
1123 is similar to how boards and SOCs are maintained in the Zephyr tree. By using
1127 Add the custom board to your application or a dedicated repository using the
1130 .. code-block:: console
1141 .. code-block:: console
1153 supported by a SOC that is available in the Zephyr tree.
1158 Use the vendor name as the folder name (which must match the vendor prefix in
1159 :zephyr_file:`dts/bindings/vendor-prefixes.txt` if submitting upstream to Zephyr, or be
1180 Once the board structure is in place, you can build your application
1182 information with the ``-DBOARD_ROOT`` parameter to the CMake
1185 .. zephyr-app-commands::
1188 :gen-args: -DBOARD_ROOT=<path to boards>
1193 Zephyr binary into your application directory.
1195 You can also define the ``BOARD_ROOT`` variable in the application
1196 :file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the Zephyr
1201 When specifying ``BOARD_ROOT`` in a CMakeLists.txt, then an absolute path must
1202 …be provided, for example ``list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>)`…
1203 When using ``-DBOARD_ROOT=<board-root>`` both absolute and relative paths can
1204 be used. Relative paths are treated relatively to the application directory.
1209 Similar to board support, the structure is similar to how SOCs are maintained in
1212 .. code-block:: none
1221 The file :zephyr_file:`soc/Kconfig` will create the top-level
1222 ``SoC/CPU/Configuration Selection`` menu in Kconfig.
1225 CMake variable. This variable contains a semicolon-separated list of directories
1231 .. code-block:: none
1243 An example of loading ``stm31l0`` specific Kconfig files in this structure:
1245 .. code-block:: none
1254 can be done with the following content in ``st/stm32/Kconfig.soc``:
1256 .. code-block:: kconfig
1260 Once the SOC structure is in place, you can build your application
1262 information with the ``-DSOC_ROOT`` parameter to the CMake
1265 .. zephyr-app-commands::
1268 :gen-args: -DSOC_ROOT=<path to soc> -DBOARD_ROOT=<path to boards>
1273 Zephyr binary into your application directory.
1275 See :ref:`modules_build_settings` for information on setting SOC_ROOT in a module's
1278 Or you can define the ``SOC_ROOT`` variable in the application
1279 :file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the
1284 When specifying ``SOC_ROOT`` in a CMakeLists.txt, then an absolute path must
1285 be provided, for example ``list(APPEND SOC_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-soc-root>``.
1286 When using ``-DSOC_ROOT=<soc-root>`` both absolute and relative paths can be
1287 used. Relative paths are treated relatively to the application directory.
1294 Devicetree directory trees are found in ``APPLICATION_SOURCE_DIR``,
1308 Once the directory structure is in place, you can use it by specifying
1311 .. zephyr-app-commands::
1314 :gen-args: -DDTS_ROOT=<path to dts root>
1318 You can also define the variable in the application :file:`CMakeLists.txt`
1319 file. Make sure to do so **before** pulling in the Zephyr boilerplate with
1324 When specifying ``DTS_ROOT`` in a CMakeLists.txt, then an absolute path must
1325 be provided, for example ``list(APPEND DTS_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-dts-root>``.
1326 When using ``-DDTS_ROOT=<dts-root>`` both absolute and relative paths can be
1327 used. Relative paths are treated relatively to the application directory.
1330 include files that can be located in a ``DTS_ROOT`` directory. By
1337 .. zephyr-app-commands::
1340 :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE
1346 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists
1347 .. _example-application: https://github.com/zephyrproject-rtos/example-application