Lines Matching +full:application +full:- +full:specific
3 Application Development
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.
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.
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
342 .. code-block:: cmake
353 - The ``cmake_minimum_required()`` call is required by CMake. It is also
358 - ``find_package(Zephyr)`` pulls in the Zephyr build system, which creates a
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:
400 ``-D`` command-line switch. If you have multiple overlay files, you should
408 order to force CMake to use a specific Zephyr installation.
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.
429 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
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.
470 configuration for your application on a new line. For example:
472 .. code-block:: cmake
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`
496 #. If your application uses a configuration file or files other than
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,
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
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
556 enforcing a specific Zephyr installation by explicitly
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:
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`
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:
700 .. code-block:: none
716 ``prj.conf`` will be used, no application devicetree overlay will be used.
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
754 To make it easier to integrate third-party components, the Zephyr
755 build system has defined CMake functions that give application build
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
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
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
861 <west-building-config>`.
863 .. _build-directory-contents:
870 .. code-block:: none
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
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
1051 board-specific udev rules to enable USB device access to
1052 your board as a non-root user. If flashing fails,
1061 Zephyr has built-in emulator support for QEMU.
1062 It allows you to run and test an application virtually, before
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
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
1093 The application stops running and the terminal console prompt
1096 Each time you execute the run command, your application is rebuilt and run
1109 You can choose a specific emulator by appending ``_<emulator>`` to your
1110 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
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
1127 Add the custom board to your application or a dedicated repository using the
1130 .. code-block:: console
1141 .. code-block:: console
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
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.
1212 .. code-block:: none
1221 The file :zephyr_file:`soc/Kconfig` will create the top-level
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
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.
1278 Or you can define the ``SOC_ROOT`` variable in the application
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.
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`
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.
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