Lines Matching +full:repo +full:- +full:path
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
37 application. This directory contains all application-specific files, such as
38 application-specific configuration files and source code.
42 .. code-block:: none
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.
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
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
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 :ref:`samples-and-demos` as a starting point is likely to be easier.
312 .. code-block:: console
319 anywhere on the path is not supported. So the Windows path
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
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:
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
420 See :ref:`initial-conf` for more information.
429 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
450 the name without the prefix). See :ref:`application-file-suffixes` for details.
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`
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
545 set with an absolute path.
550 .. code-block:: cmake
564 .. code-block:: cmake
570 .. code-block:: cmake
585 .. code-block:: cmake
592 .. _zephyr-app-cmakecache:
610 .. _application-configuration-directory:
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 :ref:`existing samples <samples-and-demos>` 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:
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
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
791 meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or
803 .. zephyr-app-commands::
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::
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
889 the :file:`zephyr` sub-directory of the build directory. (This is **not the
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
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
1028 .. code-block:: console
1034 .. code-block:: console
1039 use hardware-specific tools to flash the Zephyr binary to your
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
1105 to the path of the QEMU binary you want to use instead.
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
1182 information with the ``-DBOARD_ROOT`` parameter to the CMake
1185 .. zephyr-app-commands::
1188 :gen-args: -DBOARD_ROOT=<path to boards>
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
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>
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
1311 .. zephyr-app-commands::
1314 :gen-args: -DDTS_ROOT=<path to dts root>
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
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