Lines Matching +full:zephyr +full:- +full:main +full:- +full:ci +full:- +full:push +full:- +full:1
10 …- your **application directory**, :file:`<app>`, is something like :file:`<home>/zephyrproject/app`
11 - its **build directory** is :file:`<app>/build`
19 <important-build-vars>` is set appropriately, though.)
24 Zephyr's build system is based on `CMake`_.
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,
31 The main zephyr repository contains Zephyr's source code, configuration files,
33 alongside the zephyr repository, which provide third party source code
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
50 └── main.c
55 application files, and links the application directory with Zephyr's CMake
56 build system. This link provides features supported by Zephyr's build system,
57 such as board-specific configuration files, the ability to run and
61 application-specific changes which should be applied to the base devicetree
70 * **prj.conf**: This is a Kconfig fragment that specifies application-specific
79 See :ref:`application-kconfig` below for more information.
85 See :ref:`app-version-details` for more information about this file and how to use it.
87 * **main.c**: A source code file. Applications typically contain source files
88 written in C, C++, or assembly language. The Zephyr convention is to place
93 Zephyr, then link them together into a final binary you can run on your board.
94 The easiest way to do this is with :ref:`west build <west-building>`, but you
96 in a separate build directory: Zephyr does not support "in-tree" builds.
98 The following sections describe how to create, build, and run Zephyr
101 .. _zephyr-app-types:
106 We distinguish three basic types of Zephyr application based on where
111 +------------------------------+--------------------------------+
113 +------------------------------+--------------------------------+
114 | :ref:`repository | zephyr repository |
115 | <zephyr-repo-app>` | |
116 +------------------------------+--------------------------------+
117 | :ref:`workspace | west workspace where Zephyr is |
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
142 └─── zephyr/
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
166 ├─── zephyr/
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
189 │ ├── zephyr/
198 └── main.c
200 .. _zephyr-creating-app:
205 In Zephyr, you can either use a reference workspace application or create your application by hand.
207 .. _zephyr-creating-app-from-example:
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
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
229 an existing Zephyr workspace is to follow these steps:
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
238 you are using an existing Zephyr workspace, you can use ``west build`` or any
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,
285 you can share your work with others. For example, let's say you push the
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:
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.
312 .. code-block:: console
318 Building Zephyr or creating an application in a directory with spaces
331 .. code-block:: console
336 #. Place your application source code in the :file:`src` sub-directory. For
337 this example, we'll assume you created a file named :file:`src/main.c`.
342 .. code-block:: cmake
346 find_package(Zephyr)
349 target_sources(app PRIVATE src/main.c)
353 - The ``cmake_minimum_required()`` call is required by CMake. It is also
354 invoked by the Zephyr package on the next line. CMake will error out if
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
365 project. This must be called after ``find_package(Zephyr)`` to avoid
366 interference with Zephyr's ``project(Zephyr-Kernel)``.
368 - ``target_sources(app PRIVATE src/main.c)`` is to add your source file to
369 the ``app`` target. This must come after ``find_package(Zephyr)`` which
375 there. See :ref:`application-kconfig`. If no Kconfig options need to be set,
379 file named :file:`app.overlay`. See :ref:`set-devicetree-overlays`.
384 .. _important-build-vars:
389 You can control the Zephyr build system using many variables. This
390 section describes the most important ones that every Zephyr developer
400 ``-D`` command-line switch. If you have multiple overlay files, you should
405 * :makevar:`ZEPHYR_BASE`: Zephyr base variable used by the build system.
406 ``find_package(Zephyr)`` will automatically set this as a cached CMake
408 order to force CMake to use a specific Zephyr installation.
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`
430 for information about devicetree and Zephyr.
450 the name without the prefix). See :ref:`application-file-suffixes` for details.
457 .. _zephyr-app-cmakelists:
463 entry point, or top level, of the build system. The final :file:`zephyr.elf`
472 .. code-block:: cmake
478 The Zephyr build system determines a value for :makevar:`BOARD` by checking
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`
503 .. code-block:: cmake
508 See :ref:`initial-conf` for more information.
511 :ref:`DTC_OVERLAY_FILE <important-build-vars>`.
512 See :ref:`set-devicetree-overlays`.
525 If you just want to set application specific **values** for existing Zephyr
530 .. literalinclude:: application-kconfig.include
547 #. Specify that the application requires Zephyr on a new line, **after any
550 .. code-block:: cmake
552 find_package(Zephyr)
555 .. note:: ``find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})`` can be used if
556 enforcing a specific Zephyr installation by explicitly
558 supported. All samples in Zephyr supports the ``ZEPHYR_BASE``
564 .. code-block:: cmake
566 target_sources(app PRIVATE src/main.c)
570 .. code-block:: cmake
574 find_package(Zephyr)
577 target_sources(app PRIVATE src/main.c)
582 with the hex file generated when building the Zephyr application.
585 .. code-block:: cmake
592 .. _zephyr-app-cmakecache:
610 .. _application-configuration-directory:
615 Zephyr will use configuration files from the application's configuration
626 1. If ``APPLICATION_CONFIG_DIR`` is specified by the user with
627 ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before
628 ``find_package(Zephyr)`` then this folder is used a the application's
633 .. _application-kconfig:
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`
662 Zephyr is a project under constant development and thus there are features that
669 .. code-block:: cfg
677 .. code-block:: none
684 See :ref:`set-devicetree-overlays`.
686 .. _application-file-suffixes:
691 Zephyr applications might want to have a single code base with multiple configurations for
693 configuration. In order to better configure this, Zephyr provides a :makevar:`FILE_SUFFIX` option
700 .. code-block:: none
710 └── main.c
731 Application-Specific Code
734 Application-specific source code files are normally added to the
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
752 be useful for glue code to have access to Zephyr kernel header files.
754 To make it easier to integrate third-party components, the Zephyr
756 scripts access to the zephyr compiler options. The functions are
761 third-party build system.
766 Zephyr kernel version.
777 The Zephyr build system compiles and links all components of an application
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
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
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
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:
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
878 └── zephyr
884 * A :file:`zephyr` directory, which is the working directory of the
889 the :file:`zephyr` sub-directory of the build directory. (This is **not the
890 Zephyr base directory**, which contains the Zephyr source code etc. and is
905 * :file:`zephyr.elf`, which contains the final combined application and
922 The Zephyr build system rebuilds only the parts of the application image
939 .. code-block:: console
941 west build -t clean
945 .. code-block:: console
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
976 The Zephyr build system has support for specifying multiple hardware revisions
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
1014 Most boards supported by Zephyr let you flash a compiled binary using
1025 :file:`<app>/build`, to flash the compiled Zephyr image and run it on
1028 .. code-block:: console
1034 .. code-block:: console
1038 The Zephyr build system integrates with the board support files to
1039 use hardware-specific tools to flash the Zephyr binary to your
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,
1061 Zephyr has built-in emulator support for QEMU.
1065 Check out :ref:`beyond-GSG` for additional steps needed on Windows.
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
1102 If the (Linux only) :ref:`Zephyr SDK <toolchain_zephyr_sdk>` is installed, the ``run``
1110 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
1119 supported by Zephyr, you can add board, Devicetree and SOC definitions
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
1125 the Zephyr tree after your initial development is done.
1130 .. code-block:: console
1141 .. code-block:: console
1153 supported by a SOC that is available in the Zephyr tree.
1159 :zephyr_file:`dts/bindings/vendor-prefixes.txt` if submitting upstream to Zephyr, or be
1163 will be needed when submitting to Zephyr.
1166 Zephyr board, and provide the following files::
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.
1196 :file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the Zephyr
1197 boilerplate with ``find_package(Zephyr ...)``.
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
1210 the Zephyr tree, for example:
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
1245 .. code-block:: none
1256 .. code-block:: kconfig
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.
1276 :file:`zephyr/module.yml` file.
1280 Zephyr boilerplate with ``find_package(Zephyr ...)``.
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
1311 .. zephyr-app-commands::
1314 :gen-args: -DDTS_ROOT=<path to dts root>
1319 file. Make sure to do so **before** pulling in the Zephyr boilerplate with
1320 ``find_package(Zephyr ...)``.
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
1337 .. zephyr-app-commands::
1340 :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE
1345 .. _CMake introduction: https://cmake.org/cmake/help/latest/manual/cmake.1.html#description
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