Lines Matching +full:apt +full:- +full:get
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
56 such as board-specific configuration files, the ability to run and
60 application-specific changes which should be applied to the base devicetree
69 * **prj.conf**: This is a Kconfig fragment that specifies application-specific
78 See :ref:`application-kconfig` below for more information.
87 The easiest way to do this is with :ref:`west build <west-building>`, but you
89 in a separate build directory: Zephyr does not support "in-tree" builds.
94 .. _zephyr-app-types:
104 +------------------------------+--------------------------------+
106 +------------------------------+--------------------------------+
108 | <zephyr-repo-app>` | |
109 +------------------------------+--------------------------------+
111 | <zephyr-workspace-app>` | installed |
112 +------------------------------+--------------------------------+
114 | <zephyr-freestanding-app>` | |
115 +------------------------------+--------------------------------+
120 .. _zephyr-repo-app:
126 :ref:`west workspace <west-workspaces>` is referred to as a Zephyr repository
130 .. code-block:: none
145 .. _zephyr-workspace-app:
150 An application located within a :ref:`workspace <west-workspaces>`, but outside
154 .. code-block:: none
163 ├─── <vendor/private-repositories>/
167 .. _zephyr-freestanding-app:
173 <west-workspaces>` is referred to as a Zephyr freestanding application. In the
176 .. code-block:: none
196 example-application
199 The `example-application`_ Git repository contains a reference :ref:`workspace
200 application <zephyr-workspace-app>`. It is recommended to use it as a reference
203 The example-application repository demonstrates how to use several
204 commonly-used features, such as:
206 - Custom :ref:`board ports <board_porting_guide>`
207 - Custom :ref:`devicetree bindings <dt-bindings>`
208 - Custom :ref:`device drivers <device_model_api>`
209 - Continuous Integration (CI) setup, including using :ref:`twister <twister_script>`
210 - A custom west :ref:`extension command <west-extensions>`
212 Basic example-application Usage
215 The easiest way to get started with the example-application repository within
218 .. code-block:: console
221 git clone https://github.com/zephyrproject-rtos/example-application my-app
223 The directory name :file:`my-app` above is arbitrary: change it as needed. You
228 Advanced example-application Usage
231 You can also use the example-application repository as a starting point for
232 building your own customized Zephyr-based software distribution. This lets you
235 - remove Zephyr modules you don't need
236 - add additional custom repositories of your own
237 - override repositories provided by Zephyr with your own versions
238 - share the results with others and collaborate further
240 The example-application repository contains a :file:`west.yml` file and is
241 therefore also a west :ref:`manifest repository <west-workspace>`. Use this to
244 .. code-block:: console
247 mkdir my-workspace
248 cd my-workspace
249 git clone https://github.com/zephyrproject-rtos/example-application my-manifest-repo
250 west init -l my-manifest-repo
252 This will create a new workspace with the :ref:`T2 topology <west-t2>`, with
253 :file:`my-manifest-repo` as the manifest repository. The :file:`my-workspace`
254 and :file:`my-manifest-repo` names are arbitrary: change them as needed.
257 repository will match the example-application's contents when you clone it. You
258 can then edit :file:`my-manifest-repo/west.yml` to your liking, changing the
259 set of repositories in it as you wish. See :ref:`west-manifest-import` for many
265 .. code-block::
271 If you push the resulting :file:`my-manifest-repo` repository somewhere else,
273 repository to ``https://git.example.com/my-manifest-repo``. Other people can
276 .. code-block::
278 west init -m https://git.example.com/my-manifest-repo my-workspace
279 cd my-workspace
283 the repositories you are using and updating :file:`my-manifest-repo/west.yml`
290 scratch. However, using the `example-application`_ repository or one of
291 Zephyr's :ref:`samples-and-demos` as a starting point is likely to be easier.
297 .. code-block:: console
316 .. code-block:: console
321 #. Place your application source code in the :file:`src` sub-directory. For
327 .. code-block:: cmake
338 - The ``cmake_minimum_required()`` call is required by CMake. It is also
343 - ``find_package(Zephyr)`` pulls in the Zephyr build system, which creates a
346 define ``Zephyr-Kernel`` as a CMake project and enable support for the
349 - ``project(my_zephyr_app)`` defines your application's CMake
351 interference with Zephyr's ``project(Zephyr-Kernel)``.
353 - ``target_sources(app PRIVATE src/main.c)`` is to add your source file to
360 there. See :ref:`application-kconfig`. If no Kconfig options need to be set,
364 file named :file:`app.overlay`. See :ref:`set-devicetree-overlays`.
369 .. _important-build-vars:
385 ``-D`` command-line switch. If you have multiple overlay files, you should
397 built-in boards, and :ref:`board_porting_guide` for information on
405 See :ref:`initial-conf` for more information.
414 See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
446 .. code-block:: cmake
456 - Any previously used value as determined by the CMake cache takes highest
460 - Any value given on the CMake command line (directly or indirectly via
461 ``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and
464 - If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
467 - Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
479 .. code-block:: cmake
484 See :ref:`initial-conf` for more information.
487 :ref:`DTC_OVERLAY_FILE <important-build-vars>`.
488 See :ref:`set-devicetree-overlays`.
506 .. literalinclude:: application-kconfig.include
525 .. code-block:: cmake
539 .. code-block:: cmake
545 .. code-block:: cmake
560 .. code-block:: cmake
583 .. _application-configuration-directory:
600 ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before
606 .. _application-kconfig:
615 .. code-block:: none
619 Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
623 Kconfig configuration values. The :ref:`initial-conf` section on the same page
624 explains how the initial configuration is derived. See :ref:`kconfig-search`
642 .. code-block:: none
650 .. code-block:: none
657 See :ref:`set-devicetree-overlays`.
659 Application-Specific Code
662 Application-specific source code files are normally added to the
664 number of files the developer can group them into sub-directories
667 Application-specific source code should not use symbol name prefixes that have
670 <https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
672 Third-party Library Code
682 To make it easier to integrate third-party components, the Zephyr
689 third-party build system.
709 Like any other CMake-based system, the build process takes place :ref:`in
710 two stages <cmake-details>`. First, build files (also known as a buildsystem)
711 are generated using the ``cmake`` command-line tool while specifying a
719 meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or
731 .. zephyr-app-commands::
741 - to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
742 command line; see the :ref:`west build <west-building-generator>`
744 - to use ``make`` by default from now on, run ``west config build.generator
749 .. zephyr-app-commands::
753 :host-os: unix
763 image for the board specified in the command-line parameters:
765 .. zephyr-app-commands::
767 :cd-into:
776 .. zephyr-app-commands::
778 :cd-into:
780 :gen-args: -DCONF_FILE=prj.alternate.conf
789 <west-building-config>`.
791 .. _build-directory-contents:
798 .. code-block:: none
817 the :file:`zephyr` sub-directory of the build directory. (This is **not the
867 .. code-block:: console
869 west build -t clean
873 .. code-block:: console
882 .. code-block:: console
884 west build -t pristine
888 .. code-block:: console
893 :ref:`make the build folder pristine <west-building-config>` whenever it is
907 duplicating all the files described in :ref:`create-your-board-directory` for
913 .. zephyr-app-commands::
915 :cd-into:
926 .. code-block:: console
928 -- Board: plank, Revision: 1.5.0
956 .. code-block:: console
962 .. code-block:: console
967 use hardware-specific tools to flash the Zephyr binary to your
979 board-specific udev rules to enable USB device access to
980 your board as a non-root user. If flashing fails,
989 The kernel has built-in emulator support for QEMU (on Linux/macOS only, this
999 - ``qemu_x86`` to emulate running on an x86-based board
1000 - ``qemu_cortex_m3`` to emulate running on an ARM Cortex M3-based board
1005 .. code-block:: console
1007 west build -t run
1011 .. code-block:: console
1035 target name, for example ``west build -t run_qemu`` or ``ninja run_qemu``
1043 This section is a quick hands-on reference to start debugging your
1078 .. code-block:: bash
1080 qemu -s -S <image>
1086 * ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
1088 * ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
1097 .. code-block:: console
1102 :makevar:`${QEMU_PIPE}` via CMake, typically :file:`qemu-fifo` within the build
1103 directory. You may monitor this file during the run with :command:`tail -f
1104 qemu-fifo`.
1111 .. code-block:: console
1113 west build -t debugserver_qemu
1125 If the option is unset, then the QEMU invocation will lack a ``-s`` or a
1126 ``-gdb`` parameter. You can then use the :envvar:`QEMU_EXTRA_FLAGS` shell
1134 .. code-block:: bash
1142 Substitute the correct :ref:`ZEPHYR_BASE <important-build-vars>` for your
1151 .. code-block:: none
1159 GDB provides a curses-based interface that runs in the terminal. Pass the ``--tui``
1165 The GDB version on your development system might not support the ``--tui``
1174 .. code-block:: bash
1176 ddd --gdb --debugger "gdb zephyr.elf"
1179 change depending on the toolchain you are using and your cross-development
1184 it. For example, use :command:`sudo apt-get install ddd` on an Ubuntu system.
1210 The structure needed to support out-of-tree board and SOC development
1218 .. code-block:: console
1229 .. code-block:: console
1271 information with the ``-DBOARD_ROOT`` parameter to the CMake
1274 .. zephyr-app-commands::
1277 :gen-args: -DBOARD_ROOT=<path to boards>
1291 …be provided, for example ``list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>)`…
1292 When using ``-DBOARD_ROOT=<board-root>`` both absolute and relative paths can
1301 .. code-block:: none
1311 The file :zephyr_file:`soc/Kconfig` will create the top-level
1315 CMake variable. This variable contains a semicolon-separated list of directories
1321 .. code-block:: none
1334 .. code-block:: none
1345 .. code-block:: none
1351 information with the ``-DSOC_ROOT`` parameter to the CMake
1354 .. zephyr-app-commands::
1357 :gen-args: -DSOC_ROOT=<path to soc> -DBOARD_ROOT=<path to boards>
1374 be provided, for example ``list(APPEND SOC_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-soc-root>``.
1375 When using ``-DSOC_ROOT=<soc-root>`` both absolute and relative paths can be
1400 .. zephyr-app-commands::
1403 :gen-args: -DDTS_ROOT=<path to dts root>
1414 be provided, for example ``list(APPEND DTS_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-dts-root>``.
1415 When using ``-DDTS_ROOT=<dts-root>`` both absolute and relative paths can be
1426 .. zephyr-app-commands::
1429 :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE
1445 The `GNU MCU Eclipse plug-ins`_ provide a mechanism to debug ARM projects in
1446 Eclipse with pyOCD, Segger J-Link, and OpenOCD debugging tools.
1457 #. In Eclipse, install the GNU MCU Eclipse plug-ins by opening the menu
1458 ``Window->Eclipse Marketplace...``, searching for ``GNU MCU Eclipse``, and
1462 ``Window->Preferences``, navigating to ``MCU``, and setting the ``Global
1473 .. code-block:: console
1488 different CMake generator specified by the ``-G"Eclipse CDT4 - Ninja"``
1492 .. zephyr-app-commands::
1495 :host-os: win
1497 :gen-args: -G"Eclipse CDT4 - Ninja"
1502 ``File->Import...`` and selecting the option ``Existing Projects into
1510 #. Open the menu ``Run->Debug Configurations...``.
1515 - In the Main tab:
1517 - Project: ``my_zephyr_app@build``
1518 - C/C++ Application: :file:`zephyr/zephyr.elf`
1520 - In the Debugger tab:
1522 - pyOCD Setup
1524 - Executable path: :file:`${pyocd_path}\\${pyocd_executable}`
1525 - Uncheck "Allocate console for semihosting"
1527 - Board Setup
1529 - Bus speed: 8000000 Hz
1530 - Uncheck "Enable semihosting"
1532 - GDB Client Setup
1534 - Executable path example (use your ``GNUARMEMB_TOOLCHAIN_PATH``):
1535 :file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe`
1537 - In the SVD Path tab:
1539 - File path: :file:`<workspace
1543 This is optional. It provides the SoC's memory-mapped register
1559 .. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-dev…
1560 .. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/
1562 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists
1565 .. _example-application: https://github.com/zephyrproject-rtos/example-application