Lines Matching +full:ninja +full:- +full:build
10 …- your **application directory**, :file:`<app>`, is something like :file:`<home>/zephyrproject/app`
11 - its **build directory** is :file:`<app>/build`
17 makes it easier to use ``west build`` and other commands with it. (You can
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,
32 and build system. You also likely have installed various :ref:`modules`
37 application. This directory contains all application-specific files, such as
38 application-specific configuration files and source code.
42 .. code-block:: none
54 * **CMakeLists.txt**: This file tells the build system where to find the other
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
62 for any board you build for. The purpose of devicetree overlays is
65 The build system looks for :file:`app.overlay` by default, but you can add
70 * **prj.conf**: This is a Kconfig fragment that specifies application-specific
76 The build system looks for :file:`prj.conf` by default, but you can add more
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.
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.
98 The following sections describe how to create, build, and run Zephyr
101 .. _zephyr-app-types:
111 +------------------------------+--------------------------------+
113 +------------------------------+--------------------------------+
115 | <zephyr-repo-app>` | |
116 +------------------------------+--------------------------------+
118 | <zephyr-workspace-app>` | installed |
119 +------------------------------+--------------------------------+
121 | <zephyr-freestanding-app>` | |
122 +------------------------------+--------------------------------+
124 We'll discuss these more below. To learn how the build system supports each
127 .. _zephyr-repo-app:
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
137 .. code-block:: none
152 .. _zephyr-workspace-app:
157 An application located within a :ref:`workspace <west-workspaces>`, but outside
161 .. code-block:: none
170 ├─── <vendor/private-repositories>/
174 .. _zephyr-freestanding-app:
180 <west-workspaces>` is referred to as a Zephyr freestanding application. In the
183 .. code-block:: none
200 .. _zephyr-creating-app:
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
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
239 other west commands to build, flash, and debug.
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:
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
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
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
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:
386 Important Build System Variables
389 You can control the Zephyr build system using many variables. This
396 :makevar:`DTC_OVERLAY_FILE` can be supplied to the build system in
399 * As a parameter to the ``west build`` or ``cmake`` invocation via the
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.
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
442 variable, it must be a complete list of all modules to use, as the build
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`
469 #. If you only want to build for one board, add the name of the board
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
483 precedence. This ensures you don't try to run a build with a different
484 :makevar:`BOARD` value than you set during the build configuration step.
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`
500 build up configuration fragment files in a modular way when you want to
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`.
523 build configuration.
530 .. literalinclude:: application-kconfig.include
550 .. code-block:: cmake
564 .. code-block:: cmake
570 .. code-block:: cmake
585 .. code-block:: cmake
592 .. _zephyr-app-cmakecache:
598 storage used to cache values between runs, including compile and build
600 when CMake is run in an empty build folder.
610 .. _application-configuration-directory:
627 ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before
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`
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:
692 different build/product variants which would necessitate different Kconfig options and devicetree
700 .. code-block:: none
715 * If this is build normally without ``FILE_SUFFIX`` being defined for ``qemu_cortex_m3`` then
722 * If this is build with ``FILE_SUFFIX`` set to ``mouse`` for ``qemu_cortex_m3`` then
728 build type. If this is combined with ``FILE_SUFFIX`` then the file suffix option will take
729 priority over the build type.
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
747 It is possible to build library code outside the application's :file:`src`
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.
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
784 generator. This generator determines the native build tool the buildsystem
786 The second stage runs the native build tool to actually build the
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
794 ``ninja``
795 generators (i.e. build tools), whereas on Windows you need to use ``ninja``,
797 For simplicity we will use ``ninja`` throughout this guide, and if you
798 choose to use ``west build`` to build your application know that it will
799 default to ``ninja`` under the hood.
801 As an example, let's build the Hello World sample for the ``reel_board``:
803 .. zephyr-app-commands::
805 :zephyr-app: samples/hello_world
807 :goals: build
809 On Linux and macOS, you can also build with ``make`` instead of ``ninja``:
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
827 :goals: build
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:
841 :goals: build
843 If desired, you can build the application using the configuration settings
848 .. zephyr-app-commands::
850 :cd-into:
852 :gen-args: -DCONF_FILE=prj.alternate.conf
853 :goals: build
861 <west-building-config>`.
863 .. _build-directory-contents:
865 Build Directory Contents
868 When using the Ninja generator a build directory looks like this:
870 .. code-block:: none
872 <app>/build
873 ├── build.ninja
877 ├── rules.ninja
880 The most notable files in the build directory are:
882 * :file:`build.ninja`, which can be invoked to build the application.
885 generated build system, and where most generated files are created and
888 After running ``ninja``, the following build output files will be written to
889 the :file:`zephyr` sub-directory of the build directory. (This is **not the
894 used to build the application.
922 The Zephyr build system rebuilds only the parts of the application image
926 Sometimes the build system doesn't rebuild the application correctly
928 the build system to rebuild the entire application from scratch with the
932 build directory :file:`<app>/build`.
939 .. code-block:: console
941 west build -t clean
945 .. code-block:: console
947 ninja clean
954 .. code-block:: console
956 west build -t pristine
960 .. code-block:: console
962 ninja pristine
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
982 To build for a particular revision, use ``<board>@<revision>`` instead of plain
985 .. zephyr-app-commands::
987 :cd-into:
989 :goals: build
998 .. code-block:: console
1000 -- Board: plank, Revision: 1.5.0
1019 #. Build your application, as described in :ref:`build_an_application`.
1024 #. Run one of these console commands from the build directory,
1025 :file:`<app>/build`, to flash the compiled Zephyr image and run it on
1028 .. code-block:: console
1034 .. code-block:: console
1036 ninja flash
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.
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
1077 #. Run one of these console commands from the build directory,
1078 :file:`<app>/build`, to run the Zephyr binary in QEMU:
1080 .. code-block:: console
1082 west build -t run
1086 .. code-block:: console
1088 ninja run
1110 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
1122 The structure needed to support out-of-tree board and SOC development
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
1183 build system:
1185 .. zephyr-app-commands::
1188 :gen-args: -DBOARD_ROOT=<path to boards>
1189 :goals: build
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
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
1260 Once the SOC structure is in place, you can build your application
1262 information with the ``-DSOC_ROOT`` parameter to the CMake
1263 build system:
1265 .. zephyr-app-commands::
1268 :gen-args: -DSOC_ROOT=<path to soc> -DBOARD_ROOT=<path to boards>
1269 :goals: build
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>
1315 :goals: build
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
1341 :goals: build
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