Lines Matching +full:check +full:- +full:common +full:- +full:files
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.)
26 The build system is application-centric, and requires Zephyr-based applications
31 The main zephyr repository contains Zephyr's source code, configuration files,
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
66 more devicetree overlays, and other default files are also searched for.
70 * **prj.conf**: This is a Kconfig fragment that specifies application-specific
77 Kconfig fragments, and other default files are also searched for.
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
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
96 in a separate build directory: Zephyr does not support "in-tree" builds.
101 .. _zephyr-app-types:
111 +------------------------------+--------------------------------+
113 +------------------------------+--------------------------------+
115 | <zephyr-repo-app>` | |
116 +------------------------------+--------------------------------+
118 | <zephyr-workspace-app>` | installed |
119 +------------------------------+--------------------------------+
121 | <zephyr-freestanding-app>` | |
122 +------------------------------+--------------------------------+
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
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
274 needed. Make any other changes you need to other files.
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
323 #. Create your source code files.
327 files and sources.
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
370 defines the target. You can add as many files as you want with
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`.
381 #. Set up any other files you may need, such as :ref:`twister <twister_script>`
382 configuration files, continuous integration files, documentation, etc.
384 .. _important-build-vars:
400 ``-D`` command-line switch. If you have multiple overlay files, you should
412 built-in boards, and :ref:`board_porting_guide` for information on
416 fragment files. Multiple filenames can be separated with either spaces or
420 See :ref:`initial-conf` for more information.
422 * :makevar:`EXTRA_CONF_FILE`: Additional Kconfig configuration fragment files.
427 * :makevar:`DTC_OVERLAY_FILE`: One or more devicetree overlay files to use.
428 Multiple files can be separated with semicolons.
429 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
432 * :makevar:`EXTRA_DTC_OVERLAY_FILE`: Additional devicetree overlay files to use.
433 Multiple files can be separated with semicolons. This can be useful to leave
435 overlay files.
449 fragments and devicetree overlays (if these files exists, otherwise will fallback to
450 the name without the prefix). See :ref:`application-file-suffixes` for details.
454 You can use a :ref:`cmake_build_config_package` to share common settings for
457 .. _zephyr-app-cmakelists:
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
498 variable to these files appropriately. If multiple filenames are given,
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`.
530 .. literalinclude:: application-kconfig.include
550 .. code-block:: cmake
561 #. Now add any application source files to the 'app' target
564 .. code-block:: cmake
570 .. code-block:: cmake
581 Kconfig and CMake to let you merge externally built hex files
585 .. code-block:: cmake
592 .. _zephyr-app-cmakecache:
610 .. _application-configuration-directory:
615 Zephyr will use configuration files from the application's configuration
616 directory except for files with an absolute path provided by the arguments
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
677 .. code-block:: none
684 See :ref:`set-devicetree-overlays`.
686 .. _application-file-suffixes:
695 Kconfig fragments and board overlays but with a fallback so that if such files do not exist, the
696 files without these suffixes will be used instead.
700 .. code-block:: none
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
751 libraries and applications have certain compiler flags in common. It may also
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
761 third-party build system.
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
787 source files and generate an image. To learn more about these concepts refer to
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
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
880 The most notable files in the build directory are:
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
902 * Various object files (:file:`.o` files and :file:`.a` files) containing
917 rebuild and test after any major changes to the application's source files,
918 CMakeLists.txt files, or configuration settings.
927 because it fails to recompile one or more necessary files. You can force
936 files, except for the :file:`.config` file that contains the
939 .. code-block:: console
941 west build -t clean
945 .. code-block:: console
950 generated files, including the :file:`.config` files that contain
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
978 support files to make minor adjustments to a board configuration without
979 duplicating all the files described in :ref:`create-your-board-directory` for
985 .. zephyr-app-commands::
987 :cd-into:
992 Check your board's documentation for details on whether it has multiple
998 .. code-block:: console
1000 -- Board: plank, Revision: 1.5.0
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
1050 .. note:: When developing on Linux, it's common to need to install
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
1080 .. code-block:: console
1082 west build -t run
1086 .. code-block:: console
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
1162 Documentation (under ``doc/``) and support files (under ``support/``) are optional, but
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>
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
1217 ├── common
1221 The file :zephyr_file:`soc/Kconfig` will create the top-level
1225 CMake variable. This variable contains a semicolon-separated list of directories
1226 which contain SoC support files.
1228 Following the structure above, the following files can be added to load
1231 .. code-block:: none
1241 The Kconfig files above may describe the SoC or load additional SoC Kconfig files.
1243 An example of loading ``stm31l0`` specific Kconfig files in this structure:
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>
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
1299 dts/common/
1306 directories contain files that can be included from DT sources.
1311 .. zephyr-app-commands::
1314 :gen-args: -DDTS_ROOT=<path to dts root>
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
1330 include files that can be located in a ``DTS_ROOT`` directory. By
1331 convention devicetree include files have a ``.dtsi`` extension.
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