Rodrigo Caballero | d838f82 | 2015-08-07 16:44:34 -0500 | [diff] [blame] | 1 | .. _application: |
| 2 | |
Anas Nashif | 276c589 | 2019-01-05 10:23:34 -0500 | [diff] [blame] | 3 | Application Development |
| 4 | ####################### |
Rodrigo Caballero | d838f82 | 2015-08-07 16:44:34 -0500 | [diff] [blame] | 5 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 6 | .. note:: |
| 7 | |
| 8 | In this document, we'll assume your **application directory** is |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 9 | :file:`<home>/app`, and that its **build directory** is |
| 10 | :file:`<home>/app/build`. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 11 | (These terms are defined in the following Overview.) |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 12 | On Linux/macOS, <home> is equivalent to ``~``, whereas on Windows it's |
| 13 | ``%userprofile%``. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 14 | |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 15 | Overview |
David B. Kinder | 2cb0454 | 2017-01-20 15:58:05 -0800 | [diff] [blame] | 16 | ******** |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 17 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 18 | Zephyr's build system is based on `CMake`_. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 19 | |
| 20 | The build system is application-centric, and requires Zephyr-based applications |
| 21 | to initiate building the kernel source tree. The application build controls |
| 22 | the configuration and build process of both the application and Zephyr itself, |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 23 | compiling them into a single binary. |
| 24 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 25 | Zephyr's base directory hosts Zephyr's own source code, its kernel |
| 26 | configuration options, and its build definitions. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 27 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 28 | The files in the **application directory** link Zephyr with the |
| 29 | application. This directory contains all application-specific files, such as |
| 30 | configuration options and source code. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 31 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 32 | An application in its simplest form has the following contents: |
| 33 | |
| 34 | .. code-block:: none |
| 35 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 36 | <home>/app |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 37 | ├── CMakeLists.txt |
| 38 | ├── prj.conf |
| 39 | └── src |
| 40 | └── main.c |
| 41 | |
| 42 | These contents are: |
| 43 | |
| 44 | * **CMakeLists.txt**: This file tells the build system where to find the other |
| 45 | application files, and links the application directory with Zephyr's CMake |
| 46 | build system. This link provides features supported by Zephyr's build system, |
| 47 | such as board-specific kernel configuration files, the ability to run and |
| 48 | debug compiled binaries on real or emulated hardware, and more. |
| 49 | |
Ulf Magnusson | 303484a | 2018-04-23 15:39:12 +0200 | [diff] [blame] | 50 | * **Kernel configuration files**: An application typically provides a |
Ulf Magnusson | e32686d | 2019-12-04 11:13:12 +0100 | [diff] [blame] | 51 | Kconfig configuration file (usually called :file:`prj.conf`) that specifies |
Ulf Magnusson | 303484a | 2018-04-23 15:39:12 +0200 | [diff] [blame] | 52 | application-specific values for one or more kernel configuration options. |
| 53 | These application settings are merged with board-specific settings to produce |
| 54 | a kernel configuration. |
| 55 | |
Ulf Magnusson | e32686d | 2019-12-04 11:13:12 +0100 | [diff] [blame] | 56 | See :ref:`application-kconfig` below for more information. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 57 | |
| 58 | * **Application source code files**: An application typically provides one |
| 59 | or more application-specific files, written in C or assembly language. These |
| 60 | files are usually located in a sub-directory called :file:`src`. |
| 61 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 62 | Once an application has been defined, you can use CMake to create project files |
| 63 | for building it from a directory where you want to host these files. This is |
| 64 | known as the **build directory**. Application build artifacts are always |
| 65 | generated in a build directory; Zephyr does not support "in-tree" builds. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 66 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 67 | The following sections describe how to create, build, and run Zephyr |
| 68 | applications, followed by more detailed reference material. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 69 | |
Anas Nashif | 218599d | 2019-01-21 20:45:59 -0500 | [diff] [blame] | 70 | |
| 71 | .. _source_tree_v2: |
| 72 | |
| 73 | Source Tree Structure |
| 74 | ********************* |
| 75 | |
| 76 | Understanding the Zephyr source tree can be helpful in locating the code |
| 77 | associated with a particular Zephyr feature. |
| 78 | |
Carles Cufi | 7335ef9 | 2019-01-23 14:56:00 +0100 | [diff] [blame] | 79 | At the top of the tree there are several files that are of importance: |
| 80 | |
| 81 | :file:`CMakeLists.txt` |
| 82 | The top-level file for the CMake build system, containing a lot of the |
| 83 | logic required to build Zephyr. |
| 84 | |
| 85 | :file:`Kconfig` |
| 86 | The top-level Kconfig file, which refers to the file :file:`Kconfig.zephyr` |
| 87 | also found at the top-level directory. |
| 88 | |
Ulf Magnusson | e32686d | 2019-12-04 11:13:12 +0100 | [diff] [blame] | 89 | See :ref:`the Kconfig section of the manual <kconfig>` for detailed Kconfig |
| 90 | documentation. |
| 91 | |
Carles Cufi | 7335ef9 | 2019-01-23 14:56:00 +0100 | [diff] [blame] | 92 | :file:`west.yml` |
Carles Cufi | 01e0552 | 2019-01-31 19:32:02 +0100 | [diff] [blame] | 93 | The :ref:`west` manifest, listing the external repositories managed by |
| 94 | the west command-line tool. |
Carles Cufi | 7335ef9 | 2019-01-23 14:56:00 +0100 | [diff] [blame] | 95 | |
| 96 | The Zephyr source tree also contains the following top-level |
| 97 | directories, each of which may have one or more additional levels of |
| 98 | subdirectories which are not described here. |
Anas Nashif | 218599d | 2019-01-21 20:45:59 -0500 | [diff] [blame] | 99 | |
| 100 | :file:`arch` |
| 101 | Architecture-specific kernel and system-on-chip (SoC) code. |
| 102 | Each supported architecture (for example, x86 and ARM) |
| 103 | has its own subdirectory, |
| 104 | which contains additional subdirectories for the following areas: |
| 105 | |
| 106 | * architecture-specific kernel source files |
| 107 | * architecture-specific kernel include files for private APIs |
| 108 | |
| 109 | :file:`soc` |
| 110 | SoC related code and configuration files. |
| 111 | |
| 112 | :file:`boards` |
| 113 | Board related code and configuration files. |
| 114 | |
| 115 | :file:`doc` |
| 116 | Zephyr technical documentation source files and tools used to |
| 117 | generate the https://docs.zephyrproject.org web content. |
| 118 | |
| 119 | :file:`drivers` |
| 120 | Device driver code. |
| 121 | |
| 122 | :file:`dts` |
Martí Bolívar | 6e57b42 | 2020-03-10 18:16:25 -0700 | [diff] [blame] | 123 | :ref:`devicetree <dt-guide>` source files used to describe non-discoverable |
Marti Bolivar | 27e5dd1 | 2019-10-07 10:37:09 -0700 | [diff] [blame] | 124 | board-specific hardware details. |
Anas Nashif | 218599d | 2019-01-21 20:45:59 -0500 | [diff] [blame] | 125 | |
Anas Nashif | 218599d | 2019-01-21 20:45:59 -0500 | [diff] [blame] | 126 | :file:`include` |
| 127 | Include files for all public APIs, except those defined under :file:`lib`. |
| 128 | |
| 129 | :file:`kernel` |
| 130 | Architecture-independent kernel code. |
| 131 | |
| 132 | :file:`lib` |
| 133 | Library code, including the minimal standard C library. |
| 134 | |
| 135 | :file:`misc` |
| 136 | Miscellaneous code that doesn't belong to any of the other top-level |
| 137 | directories. |
| 138 | |
| 139 | :file:`samples` |
| 140 | Sample applications that demonstrate the use of Zephyr features. |
| 141 | |
| 142 | :file:`scripts` |
| 143 | Various programs and other files used to build and test Zephyr |
| 144 | applications. |
| 145 | |
| 146 | :file:`cmake` |
| 147 | Additional build scripts needed to build Zephyr. |
| 148 | |
| 149 | :file:`subsys` |
| 150 | Subsystems of Zephyr, including: |
| 151 | |
| 152 | * USB device stack code. |
| 153 | * Networking code, including the Bluetooth stack and networking stacks. |
| 154 | * File system code. |
| 155 | * Bluetooth host and controller |
| 156 | |
| 157 | :file:`tests` |
| 158 | Test code and benchmarks for Zephyr features. |
| 159 | |
Torsten Rasmussen | db0b4e1 | 2020-03-12 23:34:12 +0100 | [diff] [blame] | 160 | :file:`share` |
| 161 | Additional architecture independent data. Currently containing Zephyr CMake |
| 162 | package. |
| 163 | |
Anas Nashif | 218599d | 2019-01-21 20:45:59 -0500 | [diff] [blame] | 164 | |
Gerard Marull-Paretas | c1a97ac | 2021-05-26 16:13:39 +0200 | [diff] [blame] | 165 | Example standalone application |
| 166 | ****************************** |
| 167 | |
| 168 | A reference standalone application contained in its own Git repository can be found in the `Example Application`_ |
| 169 | repository. It can be used as a reference on how to structure out-of-tree, Zephyr-based |
| 170 | applications using the :ref:`T2 star topology <west-t2>`. It also demonstrates the out-of-tree use of features commonly used in applications such as: |
| 171 | |
| 172 | - Custom boards |
| 173 | - Custom devicetree bindings |
| 174 | - Custom drivers |
| 175 | - Continuous Integration (CI) setup |
| 176 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 177 | Creating an Application |
| 178 | *********************** |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 179 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 180 | Follow these steps to create a new application directory. (Refer to |
Gerard Marull-Paretas | c1a97ac | 2021-05-26 16:13:39 +0200 | [diff] [blame] | 181 | the `Example Application`_ repository for a reference standalone application in its own Git repository |
| 182 | or to :ref:`samples-and-demos` for existing applications provided as part of |
| 183 | Zephyr.) |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 184 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 185 | #. Create an application directory on your workstation computer, outside of the |
| 186 | Zephyr base directory. Usually you'll want to create it somewhere under |
| 187 | your user's home directory. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 188 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 189 | For example, in a Unix shell or Windows ``cmd.exe`` prompt, navigate to |
| 190 | where you want to create your application, then enter: |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 191 | |
| 192 | .. code-block:: console |
| 193 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 194 | mkdir app |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 195 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 196 | .. warning:: |
| 197 | |
| 198 | Building Zephyr or creating an application in a directory with spaces |
| 199 | anywhere on the path is not supported. So the Windows path |
| 200 | :file:`C:\\Users\\YourName\\app` will work, but :file:`C:\\Users\\Your |
| 201 | Name\\app` will not. |
| 202 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 203 | #. It's recommended to place all application source code in a subdirectory |
| 204 | named :file:`src`. This makes it easier to distinguish between project |
| 205 | files and sources. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 206 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 207 | Continuing the previous example, enter: |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 208 | |
| 209 | .. code-block:: console |
| 210 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 211 | cd app |
| 212 | mkdir src |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 213 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 214 | #. Place your application source code in the :file:`src` sub-directory. For |
| 215 | this example, we'll assume you created a file named :file:`src/main.c`. |
Carles Cufi | 1cce63a | 2018-01-31 18:00:49 +0100 | [diff] [blame] | 216 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 217 | #. Create a file named :file:`CMakeLists.txt` in the ``app`` directory with the |
| 218 | following contents: |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 219 | |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 220 | .. code-block:: cmake |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 221 | |
Yasushi SHOJI | 27c79d2 | 2021-10-03 02:47:54 +0900 | [diff] [blame] | 222 | cmake_minimum_required(VERSION 3.20.0) |
| 223 | |
Torsten Rasmussen | db0b4e1 | 2020-03-12 23:34:12 +0100 | [diff] [blame] | 224 | find_package(Zephyr) |
Reto Schneider | 7eabab2 | 2018-10-25 16:54:09 +0200 | [diff] [blame] | 225 | project(my_zephyr_app) |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 226 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 227 | target_sources(app PRIVATE src/main.c) |
| 228 | |
Yasushi SHOJI | 27c79d2 | 2021-10-03 02:47:54 +0900 | [diff] [blame] | 229 | ``cmake_minimum_required()`` is required to be in your |
Nazar Kazakov | f483b1b | 2022-03-16 21:07:43 +0000 | [diff] [blame] | 230 | :file:`CMakeLists.txt` by CMake. It is also invoked by the Zephyr |
Yasushi SHOJI | 27c79d2 | 2021-10-03 02:47:54 +0900 | [diff] [blame] | 231 | package. The most recent of the two versions will be enforced by CMake. |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 232 | |
Yasushi SHOJI | 27c79d2 | 2021-10-03 02:47:54 +0900 | [diff] [blame] | 233 | ``find_package(Zephyr)`` pulls in the Zephyr build system, which creates a |
| 234 | CMake target named ``app`` (see :ref:`cmake_pkg`). Adding sources to this |
| 235 | target is how you include them in the build. The Zephyr package will define |
| 236 | ``Zephyr-Kernel`` as a CMake project and enable support for the ``C``, |
| 237 | ``CXX``, ``ASM`` languages. |
| 238 | |
| 239 | ``project(my_zephyr_app)`` is required for defining your application |
| 240 | project. This must be called after ``find_package(Zephyr)`` to avoid |
| 241 | interference with Zephyr's ``project(Zephyr-Kernel)``. |
| 242 | |
| 243 | ``target_sources(app PRIVATE src/main.c)`` is to add your source file to the |
| 244 | ``app`` target. This must come after ``find_package(Zephyr)`` which defines |
| 245 | the target. |
Sebastian Bøe | 3747b5b | 2018-08-03 09:37:11 +0200 | [diff] [blame] | 246 | |
Ulf Magnusson | e32686d | 2019-12-04 11:13:12 +0100 | [diff] [blame] | 247 | #. Set Kconfig configuration options. See :ref:`application-kconfig`. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 248 | |
Martí Bolívar | 6e57b42 | 2020-03-10 18:16:25 -0700 | [diff] [blame] | 249 | #. Configure any devicetree overlays needed by your application. |
| 250 | See :ref:`set-devicetree-overlays`. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 251 | |
Torsten Rasmussen | db0b4e1 | 2020-03-12 23:34:12 +0100 | [diff] [blame] | 252 | .. note:: |
| 253 | |
| 254 | ``include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)`` |
| 255 | is still supported for backward compatibility with older applications. |
Martí Bolívar | 71f17bc | 2021-11-12 16:44:59 -0800 | [diff] [blame] | 256 | Including ``boilerplate.cmake`` directly in the sample still requires using |
| 257 | :ref:`zephyr-env` before building the application. |
Anas Nashif | bf9ceac | 2021-04-15 14:40:00 -0400 | [diff] [blame] | 258 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 259 | .. _important-build-vars: |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 260 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 261 | Important Build System Variables |
| 262 | ******************************** |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 263 | |
Marti Bolivar | 0b6bbcf6 | 2018-10-14 23:20:17 -0600 | [diff] [blame] | 264 | You can control the Zephyr build system using many variables. This |
| 265 | section describes the most important ones that every Zephyr developer |
| 266 | should know about. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 267 | |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 268 | .. note:: |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 269 | |
| 270 | The variables :makevar:`BOARD`, :makevar:`CONF_FILE`, and |
| 271 | :makevar:`DTC_OVERLAY_FILE` can be supplied to the build system in |
| 272 | 3 ways (in order of precedence): |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 273 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 274 | * As a parameter to the ``west build`` or ``cmake`` invocation via the |
Maksim Masalski | 124b55a | 2020-08-14 03:17:05 +0800 | [diff] [blame] | 275 | ``-D`` command-line switch. If you have multiple overlay files, you should |
| 276 | use quotations, ``"file1.overlay;file2.overlay"`` |
Marti Bolivar | 5edb6d5 | 2019-05-06 23:36:30 -0600 | [diff] [blame] | 277 | * As :ref:`env_vars`. |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 278 | * As a ``set(<VARIABLE> <VALUE>)`` statement in your :file:`CMakeLists.txt` |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 279 | |
Torsten Rasmussen | db0b4e1 | 2020-03-12 23:34:12 +0100 | [diff] [blame] | 280 | * :makevar:`ZEPHYR_BASE`: Zephyr base variable used by the build system. |
| 281 | ``find_package(Zephyr)`` will automatically set this as a cached CMake |
| 282 | variable. But ``ZEPHYR_BASE`` can also be set as an environment variable in |
| 283 | order to force CMake to use a specific Zephyr installation. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 284 | |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 285 | * :makevar:`BOARD`: Selects the board that the application's build |
| 286 | will use for the default configuration. See :ref:`boards` for |
| 287 | built-in boards, and :ref:`board_porting_guide` for information on |
| 288 | adding board support. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 289 | |
Martí Bolívar | 43102ca | 2020-09-15 13:17:30 -0700 | [diff] [blame] | 290 | * :makevar:`CONF_FILE`: Indicates the name of one or more Kconfig configuration |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 291 | fragment files. Multiple filenames can be separated with either spaces or |
| 292 | semicolons. Each file includes Kconfig configuration values that override |
| 293 | the default configuration values. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 294 | |
Ulf Magnusson | e32686d | 2019-12-04 11:13:12 +0100 | [diff] [blame] | 295 | See :ref:`initial-conf` for more information. |
| 296 | |
Martí Bolívar | 43102ca | 2020-09-15 13:17:30 -0700 | [diff] [blame] | 297 | * :makevar:`OVERLAY_CONFIG`: Additional Kconfig configuration fragment files. |
| 298 | Multiple filenames can be separated with either spaces or semicolons. This |
| 299 | can be useful in order to leave :makevar:`CONF_FILE` at its default value, |
| 300 | but "mix in" some additional configuration options. |
| 301 | |
Martí Bolívar | 6e57b42 | 2020-03-10 18:16:25 -0700 | [diff] [blame] | 302 | * :makevar:`DTC_OVERLAY_FILE`: One or more devicetree overlay files to use. |
Maksim Masalski | 124b55a | 2020-08-14 03:17:05 +0800 | [diff] [blame] | 303 | Multiple files can be separated with semicolons. |
Martí Bolívar | 6e57b42 | 2020-03-10 18:16:25 -0700 | [diff] [blame] | 304 | See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro` |
| 305 | for information about devicetree and Zephyr. |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 306 | |
Martí Bolívar | 71f17bc | 2021-11-12 16:44:59 -0800 | [diff] [blame] | 307 | * :makevar:`SHIELD`: see :ref:`shields` |
| 308 | |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 309 | * :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of |
| 310 | additional directories with source code, Kconfig, etc. that should be used in |
Martí Bolívar | 71f17bc | 2021-11-12 16:44:59 -0800 | [diff] [blame] | 311 | the application build. See :ref:`modules` for details. If you set this |
| 312 | variable, it must be a complete list of all modules to use, as the build |
| 313 | system will not automatically pick up any modules from west. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 314 | |
Martí Bolívar | 71f17bc | 2021-11-12 16:44:59 -0800 | [diff] [blame] | 315 | * :makevar:`ZEPHYR_EXTRA_MODULES`: Like :makevar:`ZEPHYR_MODULES`, except these |
| 316 | will be added to the list of modules found via west, instead of replacing it. |
| 317 | |
| 318 | .. note:: |
| 319 | |
| 320 | You can use a :ref:`cmake_build_config_package` to share common settings for |
| 321 | these variables. |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 322 | |
| 323 | Application CMakeLists.txt |
| 324 | ************************** |
| 325 | |
| 326 | Every application must have a :file:`CMakeLists.txt` file. This file is the |
| 327 | entry point, or top level, of the build system. The final :file:`zephyr.elf` |
| 328 | image contains both the application and the kernel libraries. |
| 329 | |
| 330 | This section describes some of what you can do in your :file:`CMakeLists.txt`. |
| 331 | Make sure to follow these steps in order. |
| 332 | |
| 333 | #. If you only want to build for one board, add the name of the board |
| 334 | configuration for your application on a new line. For example: |
| 335 | |
| 336 | .. code-block:: cmake |
| 337 | |
| 338 | set(BOARD qemu_x86) |
| 339 | |
| 340 | Refer to :ref:`boards` for more information on available boards. |
| 341 | |
| 342 | The Zephyr build system determines a value for :makevar:`BOARD` by checking |
| 343 | the following, in order (when a BOARD value is found, CMake stops looking |
| 344 | further down the list): |
| 345 | |
| 346 | - Any previously used value as determined by the CMake cache takes highest |
| 347 | precedence. This ensures you don't try to run a build with a different |
| 348 | :makevar:`BOARD` value than you set during the build configuration step. |
| 349 | |
| 350 | - Any value given on the CMake command line (directly or indirectly via |
| 351 | ``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and |
| 352 | used next. |
| 353 | |
| 354 | - If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value |
| 355 | will then be used. |
| 356 | |
| 357 | - Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt` |
| 358 | as described in this step, this value will be used. |
| 359 | |
| 360 | #. If your application uses a configuration file or files other than |
| 361 | the usual :file:`prj.conf` (or :file:`prj_YOUR_BOARD.conf`, where |
| 362 | ``YOUR_BOARD`` is a board name), add lines setting the |
| 363 | :makevar:`CONF_FILE` variable to these files appropriately. |
| 364 | If multiple filenames are given, separate them by a single space or |
| 365 | semicolon. CMake lists can be used to build up configuration fragment |
| 366 | files in a modular way when you want to avoid setting :makevar:`CONF_FILE` |
| 367 | in a single place. For example: |
| 368 | |
| 369 | .. code-block:: cmake |
| 370 | |
| 371 | set(CONF_FILE "fragment_file1.conf") |
| 372 | list(APPEND CONF_FILE "fragment_file2.conf") |
| 373 | |
| 374 | See :ref:`initial-conf` for more information. |
| 375 | |
| 376 | #. If your application uses devicetree overlays, you may need to set |
| 377 | :ref:`DTC_OVERLAY_FILE <important-build-vars>`. |
| 378 | See :ref:`set-devicetree-overlays`. |
| 379 | |
| 380 | #. If your application has its own kernel configuration options, |
| 381 | create a :file:`Kconfig` file in the same directory as your |
| 382 | application's :file:`CMakeLists.txt`. |
| 383 | |
| 384 | See :ref:`the Kconfig section of the manual <kconfig>` for detailed |
| 385 | Kconfig documentation. |
| 386 | |
| 387 | An (unlikely) advanced use case would be if your application has its own |
| 388 | unique configuration **options** that are set differently depending on the |
| 389 | build configuration. |
| 390 | |
| 391 | If you just want to set application specific **values** for existing Zephyr |
| 392 | configuration options, refer to the :makevar:`CONF_FILE` description above. |
| 393 | |
| 394 | Structure your :file:`Kconfig` file like this: |
| 395 | |
| 396 | .. literalinclude:: application-kconfig.include |
| 397 | |
| 398 | .. note:: |
| 399 | |
| 400 | Environment variables in ``source`` statements are expanded directly, so |
| 401 | you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig |
| 402 | "bounce" symbol. If you use such a symbol, it must have the same name as |
| 403 | the environment variable. |
| 404 | |
| 405 | See :ref:`kconfig_extensions` for more information. |
| 406 | |
| 407 | The :file:`Kconfig` file is automatically detected when placed in |
| 408 | the application directory, but it is also possible for it to be |
| 409 | found elsewhere if the CMake variable :makevar:`KCONFIG_ROOT` is |
| 410 | set with an absolute path. |
| 411 | |
| 412 | #. Specify that the application requires Zephyr on a new line, **after any |
| 413 | lines added from the steps above**: |
| 414 | |
| 415 | .. code-block:: cmake |
| 416 | |
| 417 | find_package(Zephyr) |
| 418 | project(my_zephyr_app) |
| 419 | |
| 420 | .. note:: ``find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})`` can be used if |
| 421 | enforcing a specific Zephyr installation by explicitly |
| 422 | setting the ``ZEPHYR_BASE`` environment variable should be |
| 423 | supported. All samples in Zephyr supports the ``ZEPHYR_BASE`` |
| 424 | environment variable. |
| 425 | |
| 426 | #. Now add any application source files to the 'app' target |
| 427 | library, each on their own line, like so: |
| 428 | |
| 429 | .. code-block:: cmake |
| 430 | |
| 431 | target_sources(app PRIVATE src/main.c) |
| 432 | |
| 433 | Below is a simple example :file:`CMakeList.txt`: |
| 434 | |
| 435 | .. code-block:: cmake |
| 436 | |
| 437 | set(BOARD qemu_x86) |
| 438 | |
| 439 | find_package(Zephyr) |
| 440 | project(my_zephyr_app) |
| 441 | |
| 442 | target_sources(app PRIVATE src/main.c) |
| 443 | |
| 444 | The Cmake property ``HEX_FILES_TO_MERGE`` |
| 445 | leverages the application configuration provided by |
| 446 | Kconfig and CMake to let you merge externally built hex files |
| 447 | with the hex file generated when building the Zephyr application. |
| 448 | For example: |
| 449 | |
| 450 | .. code-block:: cmake |
| 451 | |
| 452 | set_property(GLOBAL APPEND PROPERTY HEX_FILES_TO_MERGE |
| 453 | ${app_bootloader_hex} |
| 454 | ${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME} |
| 455 | ${app_provision_hex}) |
| 456 | |
| 457 | CMakeCache.txt |
| 458 | ************** |
| 459 | |
| 460 | CMake uses a CMakeCache.txt file as persistent key/value string |
| 461 | storage used to cache values between runs, including compile and build |
| 462 | options and paths to library dependencies. This cache file is created |
| 463 | when CMake is run in an empty build folder. |
| 464 | |
| 465 | For more details about the CMakeCache.txt file see the official CMake |
| 466 | documentation `runningcmake`_ . |
| 467 | |
| 468 | .. _runningcmake: http://cmake.org/runningcmake/ |
| 469 | |
| 470 | Application Configuration |
| 471 | ************************* |
| 472 | |
Torsten Rasmussen | 1198087 | 2021-09-01 11:26:53 +0200 | [diff] [blame] | 473 | .. _application-configuration-directory: |
| 474 | |
| 475 | Application Configuration Directory |
| 476 | =================================== |
| 477 | |
| 478 | Zephyr will use configuration files from the application's configuration |
| 479 | directory except for files with an absolute path provided by the arguments |
| 480 | described earlier, for example ``CONF_FILE``, ``OVERLAY_CONFIG``, and |
| 481 | ``DTC_OVERLAY_FILE``. |
| 482 | |
| 483 | The application configuration directory is defined by the |
| 484 | ``APPLICATION_CONFIG_DIR`` variable. |
| 485 | |
| 486 | ``APPLICATION_CONFIG_DIR`` will be set by one of the sources below with the |
| 487 | highest priority listed first. |
| 488 | |
| 489 | 1. If ``APPLICATION_CONFIG_DIR`` is specified by the user with |
| 490 | ``-DAPPLICATION_CONFIG_DIR=<path>`` or in a CMake file before |
| 491 | ``find_package(Zephyr)`` then this folder is used a the application's |
| 492 | configuration directory. |
| 493 | |
| 494 | 2. The application's source directory. |
| 495 | |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 496 | .. _application-kconfig: |
| 497 | |
| 498 | Kconfig Configuration |
| 499 | ===================== |
| 500 | |
| 501 | Application configuration options are usually set in :file:`prj.conf` in the |
| 502 | application directory. For example, C++ support could be enabled with this |
| 503 | assignment: |
| 504 | |
| 505 | .. code-block:: none |
| 506 | |
| 507 | CONFIG_CPLUSPLUS=y |
| 508 | |
| 509 | Looking at :ref:`existing samples <samples-and-demos>` is a good way to get |
| 510 | started. |
| 511 | |
| 512 | See :ref:`setting_configuration_values` for detailed documentation on setting |
| 513 | Kconfig configuration values. The :ref:`initial-conf` section on the same page |
Gerard Marull-Paretas | fc942ef | 2022-01-12 13:41:15 +0100 | [diff] [blame] | 514 | explains how the initial configuration is derived. See :ref:`kconfig-search` |
| 515 | for a complete list of configuration options. |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 516 | See :ref:`hardening` for security information related with Kconfig options. |
| 517 | |
| 518 | The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also |
| 519 | worth going through, especially if you planning to add new configuration |
| 520 | options. |
| 521 | |
Torsten Rasmussen | f17630b | 2021-10-22 09:26:51 +0200 | [diff] [blame] | 522 | Experimental features |
| 523 | ********************* |
| 524 | |
| 525 | Zephyr is a project under constant development and thus there are features that |
| 526 | are still in early stages of their development cycle. Such features will be |
| 527 | marked ``[EXPERIMENTAL]`` in their Kconfig title. |
| 528 | |
Gerard Marull-Paretas | 260decc | 2022-02-07 17:27:43 +0100 | [diff] [blame] | 529 | The :kconfig:option:`CONFIG_WARN_EXPERIMENTAL` setting can be used to enable warnings |
Torsten Rasmussen | f17630b | 2021-10-22 09:26:51 +0200 | [diff] [blame] | 530 | at CMake configure time if any experimental feature is enabled. |
| 531 | |
| 532 | .. code-block:: none |
| 533 | |
| 534 | CONFIG_WARN_EXPERIMENTAL=y |
| 535 | |
Martí Bolívar | 254ceb6 | 2022-02-16 12:33:44 -0800 | [diff] [blame] | 536 | For example, if option ``CONFIG_FOO`` is experimental, then enabling it and |
Nazar Kazakov | f483b1b | 2022-03-16 21:07:43 +0000 | [diff] [blame] | 537 | :kconfig:option:`CONFIG_WARN_EXPERIMENTAL` will print the following warning at |
Gerard Marull-Paretas | 260decc | 2022-02-07 17:27:43 +0100 | [diff] [blame] | 538 | CMake configure time when you build an application: |
Torsten Rasmussen | f17630b | 2021-10-22 09:26:51 +0200 | [diff] [blame] | 539 | |
Martí Bolívar | 254ceb6 | 2022-02-16 12:33:44 -0800 | [diff] [blame] | 540 | .. code-block:: none |
Torsten Rasmussen | f17630b | 2021-10-22 09:26:51 +0200 | [diff] [blame] | 541 | |
Martí Bolívar | 254ceb6 | 2022-02-16 12:33:44 -0800 | [diff] [blame] | 542 | warning: Experimental symbol FOO is enabled. |
Torsten Rasmussen | f17630b | 2021-10-22 09:26:51 +0200 | [diff] [blame] | 543 | |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 544 | Devicetree Overlays |
| 545 | =================== |
| 546 | |
| 547 | See :ref:`set-devicetree-overlays`. |
| 548 | |
| 549 | Application-Specific Code |
| 550 | ************************* |
| 551 | |
| 552 | Application-specific source code files are normally added to the |
| 553 | application's :file:`src` directory. If the application adds a large |
| 554 | number of files the developer can group them into sub-directories |
| 555 | under :file:`src`, to whatever depth is needed. |
| 556 | |
| 557 | Application-specific source code should not use symbol name prefixes that have |
| 558 | been reserved by the kernel for its own use. For more information, see `Naming |
| 559 | Conventions |
| 560 | <https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_. |
| 561 | |
| 562 | Third-party Library Code |
| 563 | ======================== |
| 564 | |
| 565 | It is possible to build library code outside the application's :file:`src` |
| 566 | directory but it is important that both application and library code targets |
| 567 | the same Application Binary Interface (ABI). On most architectures there are |
| 568 | compiler flags that control the ABI targeted, making it important that both |
| 569 | libraries and applications have certain compiler flags in common. It may also |
| 570 | be useful for glue code to have access to Zephyr kernel header files. |
| 571 | |
| 572 | To make it easier to integrate third-party components, the Zephyr |
| 573 | build system has defined CMake functions that give application build |
| 574 | scripts access to the zephyr compiler options. The functions are |
| 575 | documented and defined in :zephyr_file:`cmake/extensions.cmake` |
| 576 | and follow the naming convention ``zephyr_get_<type>_<format>``. |
| 577 | |
| 578 | The following variables will often need to be exported to the |
| 579 | third-party build system. |
| 580 | |
| 581 | * ``CMAKE_C_COMPILER``, ``CMAKE_AR``. |
| 582 | |
| 583 | * ``ARCH`` and ``BOARD``, together with several variables that identify the |
| 584 | Zephyr kernel version. |
| 585 | |
| 586 | :zephyr_file:`samples/application_development/external_lib` is a sample |
| 587 | project that demonstrates some of these features. |
| 588 | |
| 589 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 590 | .. _build_an_application: |
| 591 | |
Carles Cufi | afcbc99 | 2019-08-25 19:06:22 +0200 | [diff] [blame] | 592 | Building an Application |
| 593 | *********************** |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 594 | |
| 595 | The Zephyr build system compiles and links all components of an application |
| 596 | into a single application image that can be run on simulated hardware or real |
| 597 | hardware. |
Marti Bolivar | ccfdff6 | 2017-11-02 13:16:20 -0400 | [diff] [blame] | 598 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 599 | Like any other CMake-based system, the build process takes place :ref:`in |
| 600 | two stages <cmake-details>`. First, build files (also known as a buildsystem) |
| 601 | are generated using the ``cmake`` command-line tool while specifying a |
| 602 | generator. This generator determines the native build tool the buildsystem |
| 603 | will use in the second stage. |
| 604 | The second stage runs the native build tool to actually build the |
| 605 | source files and generate an image. To learn more about these concepts refer to |
| 606 | the `CMake introduction`_ in the official CMake documentation. |
| 607 | |
Carles Cufi | afcbc99 | 2019-08-25 19:06:22 +0200 | [diff] [blame] | 608 | Although the default build tool in Zephyr is :std:ref:`west <west>`, Zephyr's |
| 609 | meta-tool, which invokes ``cmake`` and the underlying build tool (``ninja`` or |
| 610 | ``make``) behind the scenes, you can also choose to invoke ``cmake`` directly if |
| 611 | you prefer. On Linux and macOS you can choose between the ``make`` and |
| 612 | ``ninja`` |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 613 | generators (i.e. build tools), whereas on Windows you need to use ``ninja``, |
| 614 | since ``make`` is not supported on this platform. |
| 615 | For simplicity we will use ``ninja`` throughout this guide, and if you |
| 616 | choose to use ``west build`` to build your application know that it will |
| 617 | default to ``ninja`` under the hood. |
Anas Nashif | 7cb8a16 | 2016-12-22 10:47:01 -0500 | [diff] [blame] | 618 | |
Carles Cufi | afcbc99 | 2019-08-25 19:06:22 +0200 | [diff] [blame] | 619 | As an example, let's build the Hello World sample for the ``reel_board``: |
| 620 | |
| 621 | .. zephyr-app-commands:: |
| 622 | :tool: all |
| 623 | :app: samples/hello_world |
| 624 | :board: reel_board |
| 625 | :goals: build |
| 626 | |
| 627 | On Linux and macOS, you can also build with ``make`` instead of ``ninja``: |
| 628 | |
| 629 | Using west: |
| 630 | |
| 631 | - to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build |
| 632 | command line; see the :ref:`west build <west-building-generator>` |
| 633 | documentation for an example. |
| 634 | - to use ``make`` by default from now on, run ``west config build.generator |
| 635 | "Unix Makefiles"``. |
| 636 | |
| 637 | Using CMake directly: |
| 638 | |
| 639 | .. zephyr-app-commands:: |
| 640 | :tool: cmake |
| 641 | :app: samples/hello_world |
| 642 | :generator: make |
| 643 | :host-os: unix |
| 644 | :board: reel_board |
| 645 | :goals: build |
| 646 | |
| 647 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 648 | Basics |
| 649 | ====== |
| 650 | |
Daniel Wong | 14f09a3 | 2021-07-25 20:57:13 +1000 | [diff] [blame] | 651 | .. note:: |
| 652 | |
| 653 | In the below example, ``west`` is used outside of a west workspace. For this |
| 654 | to work, you must set the ``ZEPHYR_BASE`` environment variable to the path |
| 655 | of your zephyr git repository, using one of the methods on the |
| 656 | :ref:`Environment Variables <env_vars>` page. |
| 657 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 658 | #. Navigate to the application directory :file:`<home>/app`. |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 659 | #. Enter the following commands to build the application's :file:`zephyr.elf` |
| 660 | image for the board specified in the command-line parameters: |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 661 | |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 662 | .. zephyr-app-commands:: |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 663 | :tool: all |
| 664 | :cd-into: |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 665 | :board: <board> |
| 666 | :goals: build |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 667 | |
| 668 | If desired, you can build the application using the configuration settings |
| 669 | specified in an alternate :file:`.conf` file using the :code:`CONF_FILE` |
| 670 | parameter. These settings will override the settings in the application's |
| 671 | :file:`.config` file or its default :file:`.conf` file. For example: |
| 672 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 673 | .. zephyr-app-commands:: |
| 674 | :tool: all |
| 675 | :cd-into: |
| 676 | :board: <board> |
| 677 | :gen-args: -DCONF_FILE=prj.alternate.conf |
| 678 | :goals: build |
| 679 | :compact: |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 680 | |
Carles Cufi | 997ef85 | 2019-02-19 13:37:57 +0100 | [diff] [blame] | 681 | As described in the previous section, you can instead choose to permanently |
| 682 | set the board and configuration settings by either exporting :makevar:`BOARD` |
| 683 | and :makevar:`CONF_FILE` environment variables or by setting their values |
| 684 | in your :file:`CMakeLists.txt` using ``set()`` statements. |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 685 | Additionally, ``west`` allows you to :ref:`set a default board |
| 686 | <west-building-config>`. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 687 | |
Ruth Fuchss | 81a6107 | 2020-07-16 09:54:52 +0200 | [diff] [blame] | 688 | .. _build-directory-contents: |
| 689 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 690 | Build Directory Contents |
| 691 | ======================== |
| 692 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 693 | When using the Ninja generator a build directory looks like this: |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 694 | |
| 695 | .. code-block:: none |
| 696 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 697 | <home>/app/build |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 698 | ├── build.ninja |
| 699 | ├── CMakeCache.txt |
| 700 | ├── CMakeFiles |
| 701 | ├── cmake_install.cmake |
| 702 | ├── rules.ninja |
| 703 | └── zephyr |
| 704 | |
| 705 | The most notable files in the build directory are: |
| 706 | |
| 707 | * :file:`build.ninja`, which can be invoked to build the application. |
| 708 | |
| 709 | * A :file:`zephyr` directory, which is the working directory of the |
| 710 | generated build system, and where most generated files are created and |
| 711 | stored. |
| 712 | |
| 713 | After running ``ninja``, the following build output files will be written to |
| 714 | the :file:`zephyr` sub-directory of the build directory. (This is **not the |
| 715 | Zephyr base directory**, which contains the Zephyr source code etc. and is |
| 716 | described above.) |
| 717 | |
| 718 | * :file:`.config`, which contains the configuration settings |
| 719 | used to build the application. |
| 720 | |
Ulf Magnusson | 57b28ca | 2018-12-08 05:32:00 +0100 | [diff] [blame] | 721 | .. note:: |
| 722 | |
| 723 | The previous version of :file:`.config` is saved to :file:`.config.old` |
| 724 | whenever the configuration is updated. This is for convenience, as |
| 725 | comparing the old and new versions can be handy. |
| 726 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 727 | * Various object files (:file:`.o` files and :file:`.a` files) containing |
| 728 | compiled kernel and application code. |
| 729 | |
| 730 | * :file:`zephyr.elf`, which contains the final combined application and |
| 731 | kernel binary. Other binary output formats, such as :file:`.hex` and |
| 732 | :file:`.bin`, are also supported. |
| 733 | |
Torsten Rasmussen | db0b4e1 | 2020-03-12 23:34:12 +0100 | [diff] [blame] | 734 | .. _application_rebuild: |
| 735 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 736 | Rebuilding an Application |
| 737 | ========================= |
| 738 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 739 | Application development is usually fastest when changes are continually tested. |
| 740 | Frequently rebuilding your application makes debugging less painful |
| 741 | as the application becomes more complex. It's usually a good idea to |
| 742 | rebuild and test after any major changes to the application's source files, |
| 743 | CMakeLists.txt files, or configuration settings. |
| 744 | |
| 745 | .. important:: |
| 746 | |
| 747 | The Zephyr build system rebuilds only the parts of the application image |
| 748 | potentially affected by the changes. Consequently, rebuilding an application |
| 749 | is often significantly faster than building it the first time. |
| 750 | |
| 751 | Sometimes the build system doesn't rebuild the application correctly |
| 752 | because it fails to recompile one or more necessary files. You can force |
| 753 | the build system to rebuild the entire application from scratch with the |
| 754 | following procedure: |
| 755 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 756 | #. Open a terminal console on your host computer, and navigate to the |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 757 | build directory :file:`<home>/app/build`. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 758 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 759 | #. Enter one of the following commands, depending on whether you want to use |
| 760 | ``west`` or ``cmake`` directly to delete the application's generated |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 761 | files, except for the :file:`.config` file that contains the |
| 762 | application's current configuration information. |
| 763 | |
| 764 | .. code-block:: console |
| 765 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 766 | west build -t clean |
| 767 | |
| 768 | or |
| 769 | |
| 770 | .. code-block:: console |
| 771 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 772 | ninja clean |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 773 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 774 | Alternatively, enter one of the following commands to delete *all* |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 775 | generated files, including the :file:`.config` files that contain |
| 776 | the application's current configuration information for those board |
| 777 | types. |
| 778 | |
| 779 | .. code-block:: console |
| 780 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 781 | west build -t pristine |
| 782 | |
| 783 | or |
| 784 | |
| 785 | .. code-block:: console |
| 786 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 787 | ninja pristine |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 788 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 789 | If you use west, you can take advantage of its capability to automatically |
| 790 | :ref:`make the build folder pristine <west-building-config>` whenever it is |
| 791 | required. |
| 792 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 793 | #. Rebuild the application normally following the steps specified |
| 794 | in :ref:`build_an_application` above. |
| 795 | |
Torsten Rasmussen | 0f4fc99 | 2020-11-13 09:14:42 +0100 | [diff] [blame] | 796 | .. _application_board_version: |
| 797 | |
| 798 | Building for a board revision |
| 799 | ============================= |
| 800 | |
| 801 | The Zephyr build system has support for specifying multiple hardware revisions |
| 802 | of a single board with small variations. Using revisions allows the board |
| 803 | support files to make minor adjustments to a board configuration without |
| 804 | duplicating all the files described in :ref:`create-your-board-directory` for |
| 805 | each revision. |
| 806 | |
| 807 | To build for a particular revision, use ``<board>@<revision>`` instead of plain |
| 808 | ``<board>``. For example: |
| 809 | |
| 810 | .. zephyr-app-commands:: |
| 811 | :tool: all |
| 812 | :cd-into: |
| 813 | :board: <board>@<revision> |
| 814 | :goals: build |
| 815 | :compact: |
| 816 | |
| 817 | Check your board's documentation for details on whether it has multiple |
| 818 | revisions, and what revisions are supported. |
| 819 | |
| 820 | When targeting a board revision, the active revision will be printed at CMake |
| 821 | configure time, like this: |
| 822 | |
| 823 | .. code-block:: console |
| 824 | |
| 825 | -- Board: plank, Revision: 1.5.0 |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 826 | |
| 827 | .. _application_run: |
| 828 | |
| 829 | Run an Application |
| 830 | ****************** |
| 831 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 832 | An application image can be run on a real board or emulated hardware. |
| 833 | |
Carles Cufi | 8f05a4c | 2019-03-07 15:59:20 +0100 | [diff] [blame] | 834 | .. _application_run_board: |
| 835 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 836 | Running on a Board |
| 837 | ================== |
| 838 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 839 | Most boards supported by Zephyr let you flash a compiled binary using |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 840 | the ``flash`` target to copy the binary to the board and run it. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 841 | Follow these instructions to flash and run an application on real |
| 842 | hardware: |
| 843 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 844 | #. Build your application, as described in :ref:`build_an_application`. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 845 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 846 | #. Make sure your board is attached to your host computer. Usually, you'll do |
| 847 | this via USB. |
| 848 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 849 | #. Run one of these console commands from the build directory, |
| 850 | :file:`<home>/app/build`, to flash the compiled Zephyr image and run it on |
| 851 | your board: |
| 852 | |
| 853 | .. code-block:: console |
| 854 | |
| 855 | west flash |
| 856 | |
| 857 | or |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 858 | |
| 859 | .. code-block:: console |
| 860 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 861 | ninja flash |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 862 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 863 | The Zephyr build system integrates with the board support files to |
| 864 | use hardware-specific tools to flash the Zephyr binary to your |
| 865 | hardware, then run it. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 866 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 867 | Each time you run the flash command, your application is rebuilt and flashed |
| 868 | again. |
| 869 | |
| 870 | In cases where board support is incomplete, flashing via the Zephyr build |
| 871 | system may not be supported. If you receive an error message about flash |
| 872 | support being unavailable, consult :ref:`your board's documentation <boards>` |
| 873 | for additional information on how to flash your board. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 874 | |
| 875 | .. note:: When developing on Linux, it's common to need to install |
| 876 | board-specific udev rules to enable USB device access to |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 877 | your board as a non-root user. If flashing fails, |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 878 | consult your board's documentation to see if this is |
| 879 | necessary. |
| 880 | |
Carles Cufi | 8f05a4c | 2019-03-07 15:59:20 +0100 | [diff] [blame] | 881 | .. _application_run_qemu: |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 882 | |
| 883 | Running in an Emulator |
| 884 | ====================== |
| 885 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 886 | The kernel has built-in emulator support for QEMU (on Linux/macOS only, this |
| 887 | is not yet supported on Windows). It allows you to run and test an application |
| 888 | virtually, before (or in lieu of) loading and running it on actual target |
| 889 | hardware. Follow these instructions to run an application via QEMU: |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 890 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 891 | #. Build your application for one of the QEMU boards, as described in |
| 892 | :ref:`build_an_application`. |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 893 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 894 | For example, you could set ``BOARD`` to: |
| 895 | |
| 896 | - ``qemu_x86`` to emulate running on an x86-based board |
| 897 | - ``qemu_cortex_m3`` to emulate running on an ARM Cortex M3-based board |
| 898 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 899 | #. Run one of these console commands from the build directory, |
| 900 | :file:`<home>/app/build`, to run the Zephyr binary in QEMU: |
| 901 | |
| 902 | .. code-block:: console |
| 903 | |
| 904 | west build -t run |
| 905 | |
| 906 | or |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 907 | |
| 908 | .. code-block:: console |
| 909 | |
Carles Cufi | 0008e34 | 2018-01-18 18:02:12 +0100 | [diff] [blame] | 910 | ninja run |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 911 | |
| 912 | #. Press :kbd:`Ctrl A, X` to stop the application from running |
| 913 | in QEMU. |
| 914 | |
| 915 | The application stops running and the terminal console prompt |
| 916 | redisplays. |
| 917 | |
Marti Bolivar | ca46dfa | 2017-11-03 14:12:46 -0400 | [diff] [blame] | 918 | Each time you execute the run command, your application is rebuilt and run |
| 919 | again. |
| 920 | |
Anas Nashif | 1d4e089 | 2018-08-21 10:25:52 -0500 | [diff] [blame] | 921 | |
Marti Bolivar | a506baf | 2019-05-14 08:29:18 -0600 | [diff] [blame] | 922 | .. note:: |
| 923 | |
| 924 | If the (Linux only) :ref:`Zephyr SDK <zephyr_sdk>` is installed, the ``run`` |
| 925 | target will use the SDK's QEMU binary by default. To use another version of |
| 926 | QEMU, :ref:`set the environment variable <env_vars>` :envvar:`QEMU_BIN_PATH` |
| 927 | to the path of the QEMU binary you want to use instead. |
Anas Nashif | 1d4e089 | 2018-08-21 10:25:52 -0500 | [diff] [blame] | 928 | |
Filip Kokosinski | 5980f89 | 2021-10-05 12:16:09 +0200 | [diff] [blame] | 929 | .. note:: |
| 930 | |
| 931 | You can choose a specific emulator by appending ``_<emulator>`` to your |
| 932 | target name, for example ``west build -t run_qemu`` or ``ninja run_qemu`` |
| 933 | for QEMU. |
| 934 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 935 | .. _application_debugging: |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 936 | |
| 937 | Application Debugging |
| 938 | ********************* |
| 939 | |
| 940 | This section is a quick hands-on reference to start debugging your |
| 941 | application with QEMU. Most content in this section is already covered in |
| 942 | `QEMU`_ and `GNU_Debugger`_ reference manuals. |
| 943 | |
| 944 | .. _QEMU: http://wiki.qemu.org/Main_Page |
| 945 | |
| 946 | .. _GNU_Debugger: http://www.gnu.org/software/gdb |
| 947 | |
| 948 | In this quick reference, you'll find shortcuts, specific environmental |
| 949 | variables, and parameters that can help you to quickly set up your debugging |
| 950 | environment. |
| 951 | |
| 952 | The simplest way to debug an application running in QEMU is using the GNU |
| 953 | Debugger and setting a local GDB server in your development system through QEMU. |
| 954 | |
| 955 | You will need an Executable and Linkable Format (ELF) binary image for |
| 956 | debugging purposes. The build system generates the image in the build |
| 957 | directory. By default, the kernel binary name is |
| 958 | :file:`zephyr.elf`. The name can be changed using a Kconfig option. |
| 959 | |
| 960 | We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)` |
| 961 | server instance. This port number can be changed for a port that best suits the |
| 962 | development environment. |
| 963 | |
| 964 | You can run QEMU to listen for a "gdb connection" before it starts executing any |
| 965 | code to debug it. |
| 966 | |
| 967 | .. code-block:: bash |
| 968 | |
| 969 | qemu -s -S <image> |
| 970 | |
| 971 | will setup Qemu to listen on port 1234 and wait for a GDB connection to it. |
| 972 | |
| 973 | The options used above have the following meaning: |
| 974 | |
| 975 | * ``-S`` Do not start CPU at startup; rather, you must type 'c' in the |
| 976 | monitor. |
| 977 | * ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on |
| 978 | TCP port 1234. |
| 979 | |
| 980 | To debug with QEMU and to start a GDB server and wait for a remote connect, run |
| 981 | either of the following inside the build directory of an application: |
| 982 | |
| 983 | .. code-block:: bash |
| 984 | |
| 985 | ninja debugserver |
| 986 | |
| 987 | The build system will start a QEMU instance with the CPU halted at startup |
| 988 | and with a GDB server instance listening at the TCP port 1234. |
| 989 | |
| 990 | Using a local GDB configuration :file:`.gdbinit` can help initialize your GDB |
| 991 | instance on every run. |
| 992 | In this example, the initialization file points to the GDB server instance. |
| 993 | It configures a connection to a remote target at the local host on the TCP |
| 994 | port 1234. The initialization sets the kernel's root directory as a |
| 995 | reference. |
| 996 | |
| 997 | The :file:`.gdbinit` file contains the following lines: |
| 998 | |
| 999 | .. code-block:: bash |
| 1000 | |
| 1001 | target remote localhost:1234 |
| 1002 | dir ZEPHYR_BASE |
| 1003 | |
| 1004 | .. note:: |
| 1005 | |
| 1006 | Substitute the correct :ref:`ZEPHYR_BASE <important-build-vars>` for your |
| 1007 | system. |
| 1008 | |
| 1009 | Execute the application to debug from the same directory that you chose for |
| 1010 | the :file:`gdbinit` file. The command can include the ``--tui`` option |
| 1011 | to enable the use of a terminal user interface. The following commands |
| 1012 | connects to the GDB server using :file:`gdb`. The command loads the symbol |
| 1013 | table from the elf binary file. In this example, the elf binary file name |
| 1014 | corresponds to :file:`zephyr.elf` file: |
| 1015 | |
| 1016 | .. code-block:: bash |
| 1017 | |
| 1018 | ..../path/to/gdb --tui zephyr.elf |
| 1019 | |
| 1020 | .. note:: |
| 1021 | |
| 1022 | The GDB version on the development system might not support the --tui |
| 1023 | option. Please make sure you use the GDB binary from the SDK which |
| 1024 | corresponds to the toolchain that has been used to build the binary. |
| 1025 | |
| 1026 | If you are not using a .gdbinit file, issue the following command inside GDB to |
| 1027 | connect to the remote GDB server on port 1234: |
| 1028 | |
| 1029 | .. code-block:: bash |
| 1030 | |
| 1031 | (gdb) target remote localhost:1234 |
| 1032 | |
| 1033 | Finally, the command below connects to the GDB server using the Data |
| 1034 | Displayer Debugger (:file:`ddd`). The command loads the symbol table from the |
| 1035 | elf binary file, in this instance, the :file:`zephyr.elf` file. |
| 1036 | |
| 1037 | The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your |
| 1038 | development system by default. Follow your system instructions to install |
| 1039 | it. For example, use ``sudo apt-get install ddd`` on an Ubuntu system. |
| 1040 | |
| 1041 | .. code-block:: bash |
| 1042 | |
| 1043 | ddd --gdb --debugger "gdb zephyr.elf" |
| 1044 | |
| 1045 | |
| 1046 | Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might |
| 1047 | change depending on the toolchain you are using and your cross-development |
| 1048 | tools. |
| 1049 | |
Sebastian Bøe | bdc5c72 | 2018-03-26 09:48:57 +0200 | [diff] [blame] | 1050 | .. _custom_board_definition: |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1051 | |
Peter A. Bigot | b7ce0a2 | 2020-08-21 14:47:44 -0500 | [diff] [blame] | 1052 | Custom Board, Devicetree and SOC Definitions |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1053 | ******************************************** |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1054 | |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1055 | In cases where the board or platform you are developing for is not yet |
Peter A. Bigot | b7ce0a2 | 2020-08-21 14:47:44 -0500 | [diff] [blame] | 1056 | supported by Zephyr, you can add board, Devicetree and SOC definitions |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1057 | to your application without having to add them to the Zephyr tree. |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1058 | |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1059 | The structure needed to support out-of-tree board and SOC development |
| 1060 | is similar to how boards and SOCs are maintained in the Zephyr tree. By using |
| 1061 | this structure, it will be much easier to upstream your platform related work into |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1062 | the Zephyr tree after your initial development is done. |
| 1063 | |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1064 | Add the custom board to your application or a dedicated repository using the |
| 1065 | following structure: |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1066 | |
| 1067 | .. code-block:: console |
| 1068 | |
| 1069 | boards/ |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1070 | soc/ |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1071 | CMakeLists.txt |
| 1072 | prj.conf |
| 1073 | README.rst |
| 1074 | src/ |
| 1075 | |
| 1076 | where the ``boards`` directory hosts the board you are building for: |
| 1077 | |
| 1078 | .. code-block:: console |
| 1079 | |
| 1080 | . |
| 1081 | ├── boards |
David B. Kinder | 7760b94 | 2018-05-31 14:09:46 -0700 | [diff] [blame] | 1082 | │ └── x86 |
| 1083 | │ └── my_custom_board |
| 1084 | │ ├── doc |
| 1085 | │ │ └── img |
| 1086 | │ └── support |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1087 | └── src |
| 1088 | |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1089 | and the ``soc`` directory hosts any SOC code. You can also have boards that are |
| 1090 | supported by a SOC that is available in the Zephyr tree. |
| 1091 | |
| 1092 | Boards |
| 1093 | ====== |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1094 | |
| 1095 | Use the proper architecture folder name (e.g., ``x86``, ``arm``, etc.) |
| 1096 | under ``boards`` for ``my_custom_board``. (See :ref:`boards` for a |
| 1097 | list of board architectures.) |
| 1098 | |
| 1099 | Documentation (under ``doc/``) and support files (under ``support/``) are optional, but |
| 1100 | will be needed when submitting to Zephyr. |
| 1101 | |
| 1102 | The contents of ``my_custom_board`` should follow the same guidelines for any |
| 1103 | Zephyr board, and provide the following files:: |
| 1104 | |
| 1105 | my_custom_board_defconfig |
| 1106 | my_custom_board.dts |
| 1107 | my_custom_board.yaml |
| 1108 | board.cmake |
| 1109 | board.h |
| 1110 | CMakeLists.txt |
| 1111 | doc/ |
Sebastian Bøe | 8eb734c | 2018-10-08 10:55:43 +0200 | [diff] [blame] | 1112 | dts_fixup.h |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1113 | Kconfig.board |
| 1114 | Kconfig.defconfig |
| 1115 | pinmux.c |
| 1116 | support/ |
| 1117 | |
| 1118 | |
| 1119 | Once the board structure is in place, you can build your application |
| 1120 | targeting this board by specifying the location of your custom board |
| 1121 | information with the ``-DBOARD_ROOT`` parameter to the CMake |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1122 | build system: |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1123 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1124 | .. zephyr-app-commands:: |
| 1125 | :tool: all |
| 1126 | :board: <board name> |
| 1127 | :gen-args: -DBOARD_ROOT=<path to boards> |
| 1128 | :goals: build |
| 1129 | :compact: |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1130 | |
| 1131 | This will use your custom board configuration and will generate the |
| 1132 | Zephyr binary into your application directory. |
| 1133 | |
| 1134 | You can also define the ``BOARD_ROOT`` variable in the application |
Martí Bolívar | e2b72a0 | 2020-06-23 16:55:10 -0700 | [diff] [blame] | 1135 | :file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the Zephyr |
| 1136 | boilerplate with ``find_package(Zephyr ...)``. |
Anas Nashif | e172fa3 | 2018-02-11 22:30:57 -0600 | [diff] [blame] | 1137 | |
Torsten Rasmussen | fb16a3d | 2020-09-08 14:07:00 +0200 | [diff] [blame] | 1138 | .. note:: |
| 1139 | |
| 1140 | When specifying ``BOARD_ROOT`` in a CMakeLists.txt, then an absolute path must |
| 1141 | be provided, for example ``list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>``. |
| 1142 | When using ``-DBOARD_ROOT=<board-root>`` both absolute and relative paths can |
| 1143 | be used. Relative paths are treated relatively to the application directory. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1144 | |
| 1145 | SOC Definitions |
| 1146 | =============== |
| 1147 | |
| 1148 | Similar to board support, the structure is similar to how SOCs are maintained in |
| 1149 | the Zephyr tree, for example: |
| 1150 | |
Ulf Magnusson | acc829c | 2019-12-04 12:29:07 +0100 | [diff] [blame] | 1151 | .. code-block:: none |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1152 | |
| 1153 | soc |
| 1154 | └── arm |
| 1155 | └── st_stm32 |
| 1156 | ├── common |
Erwan Gouriou | 7a9f4f6 | 2018-09-13 14:13:32 +0200 | [diff] [blame] | 1157 | └── stm32l0 |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1158 | |
| 1159 | |
| 1160 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1161 | The file :zephyr_file:`soc/Kconfig` will create the top-level |
| 1162 | ``SoC/CPU/Configuration Selection`` menu in Kconfig. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1163 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1164 | Out of tree SoC definitions can be added to this menu using the ``SOC_ROOT`` |
| 1165 | CMake variable. This variable contains a semicolon-separated list of directories |
| 1166 | which contain SoC support files. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1167 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1168 | Following the structure above, the following files can be added to load |
| 1169 | more SoCs into the menu. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1170 | |
Ulf Magnusson | acc829c | 2019-12-04 12:29:07 +0100 | [diff] [blame] | 1171 | .. code-block:: none |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1172 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1173 | soc |
| 1174 | └── arm |
| 1175 | └── st_stm32 |
| 1176 | ├── Kconfig |
| 1177 | ├── Kconfig.soc |
| 1178 | └── Kconfig.defconfig |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1179 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1180 | The Kconfig files above may describe the SoC or load additional SoC Kconfig files. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1181 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1182 | An example of loading ``stm31l0`` specific Kconfig files in this structure: |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1183 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1184 | .. code-block:: none |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1185 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1186 | soc |
| 1187 | └── arm |
| 1188 | └── st_stm32 |
| 1189 | ├── Kconfig.soc |
| 1190 | └── stm32l0 |
| 1191 | └── Kconfig.series |
| 1192 | |
| 1193 | can be done with the following content in ``st_stm32/Kconfig.soc``: |
| 1194 | |
| 1195 | .. code-block:: none |
| 1196 | |
| 1197 | rsource "*/Kconfig.series" |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1198 | |
| 1199 | Once the SOC structure is in place, you can build your application |
| 1200 | targeting this platform by specifying the location of your custom platform |
| 1201 | information with the ``-DSOC_ROOT`` parameter to the CMake |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1202 | build system: |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1203 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1204 | .. zephyr-app-commands:: |
| 1205 | :tool: all |
| 1206 | :board: <board name> |
| 1207 | :gen-args: -DSOC_ROOT=<path to soc> -DBOARD_ROOT=<path to boards> |
| 1208 | :goals: build |
| 1209 | :compact: |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1210 | |
| 1211 | This will use your custom platform configurations and will generate the |
| 1212 | Zephyr binary into your application directory. |
| 1213 | |
Torsten Rasmussen | 650cf3c | 2020-08-07 14:34:13 +0200 | [diff] [blame] | 1214 | See :ref:`modules_build_settings` for information on setting SOC_ROOT in a module's |
| 1215 | :file:`zephyr/module.yml` file. |
| 1216 | |
| 1217 | Or you can define the ``SOC_ROOT`` variable in the application |
Martí Bolívar | e2b72a0 | 2020-06-23 16:55:10 -0700 | [diff] [blame] | 1218 | :file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the |
| 1219 | Zephyr boilerplate with ``find_package(Zephyr ...)``. |
Anas Nashif | 1666130 | 2018-09-12 22:04:17 -0500 | [diff] [blame] | 1220 | |
Torsten Rasmussen | fb16a3d | 2020-09-08 14:07:00 +0200 | [diff] [blame] | 1221 | .. note:: |
| 1222 | |
| 1223 | When specifying ``SOC_ROOT`` in a CMakeLists.txt, then an absolute path must |
| 1224 | be provided, for example ``list(APPEND SOC_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-soc-root>``. |
| 1225 | When using ``-DSOC_ROOT=<soc-root>`` both absolute and relative paths can be |
| 1226 | used. Relative paths are treated relatively to the application directory. |
| 1227 | |
Martí Bolívar | 6e57b42 | 2020-03-10 18:16:25 -0700 | [diff] [blame] | 1228 | .. _dts_root: |
| 1229 | |
Peter A. Bigot | b7ce0a2 | 2020-08-21 14:47:44 -0500 | [diff] [blame] | 1230 | Devicetree Definitions |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1231 | ====================== |
| 1232 | |
Peter A. Bigot | b7ce0a2 | 2020-08-21 14:47:44 -0500 | [diff] [blame] | 1233 | Devicetree directory trees are found in ``APPLICATION_SOURCE_DIR``, |
Peter A. Bigot | 8437ab1 | 2019-07-04 09:48:53 -0500 | [diff] [blame] | 1234 | ``BOARD_DIR``, and ``ZEPHYR_BASE``, but additional trees, or DTS_ROOTs, |
| 1235 | can be added by creating this directory tree:: |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1236 | |
Peter A. Bigot | 8437ab1 | 2019-07-04 09:48:53 -0500 | [diff] [blame] | 1237 | include/ |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1238 | dts/common/ |
| 1239 | dts/arm/ |
Peter A. Bigot | 8437ab1 | 2019-07-04 09:48:53 -0500 | [diff] [blame] | 1240 | dts/ |
| 1241 | dts/bindings/ |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1242 | |
| 1243 | Where 'arm' is changed to the appropriate architecture. Each directory |
| 1244 | is optional. The binding directory contains bindings and the other |
| 1245 | directories contain files that can be included from DT sources. |
| 1246 | |
| 1247 | Once the directory structure is in place, you can use it by specifying |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1248 | its location through the ``DTS_ROOT`` CMake Cache variable: |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1249 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1250 | .. zephyr-app-commands:: |
| 1251 | :tool: all |
| 1252 | :board: <board name> |
| 1253 | :gen-args: -DDTS_ROOT=<path to dts root> |
| 1254 | :goals: build |
| 1255 | :compact: |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1256 | |
Martí Bolívar | e2b72a0 | 2020-06-23 16:55:10 -0700 | [diff] [blame] | 1257 | You can also define the variable in the application :file:`CMakeLists.txt` |
| 1258 | file. Make sure to do so **before** pulling in the Zephyr boilerplate with |
| 1259 | ``find_package(Zephyr ...)``. |
Sebastian Bøe | 397abd4 | 2019-03-14 13:06:40 +0100 | [diff] [blame] | 1260 | |
Torsten Rasmussen | fb16a3d | 2020-09-08 14:07:00 +0200 | [diff] [blame] | 1261 | .. note:: |
| 1262 | |
| 1263 | When specifying ``DTS_ROOT`` in a CMakeLists.txt, then an absolute path must |
| 1264 | be provided, for example ``list(APPEND DTS_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-dts-root>``. |
| 1265 | When using ``-DDTS_ROOT=<dts-root>`` both absolute and relative paths can be |
| 1266 | used. Relative paths are treated relatively to the application directory. |
| 1267 | |
Peter A. Bigot | 0950b25 | 2020-08-21 14:52:15 -0500 | [diff] [blame] | 1268 | Devicetree source are passed through the C preprocessor, so you can |
| 1269 | include files that can be located in a ``DTS_ROOT`` directory. By |
| 1270 | convention devicetree include files have a ``.dtsi`` extension. |
| 1271 | |
| 1272 | You can also use the preprocessor to control the content of a devicetree |
| 1273 | file, by specifying directives through the ``DTS_EXTRA_CPPFLAGS`` CMake |
| 1274 | Cache variable: |
| 1275 | |
| 1276 | .. zephyr-app-commands:: |
| 1277 | :tool: all |
| 1278 | :board: <board name> |
| 1279 | :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE |
| 1280 | :goals: build |
| 1281 | :compact: |
Carles Cufi | 01e0552 | 2019-01-31 19:32:02 +0100 | [diff] [blame] | 1282 | |
Marti Bolivar | 9c85c7f | 2017-11-03 12:34:22 -0400 | [diff] [blame] | 1283 | |
| 1284 | |
Anas Nashif | 5342bc6 | 2021-05-06 09:48:14 -0400 | [diff] [blame] | 1285 | Debug with Eclipse |
| 1286 | ****************** |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1287 | |
| 1288 | Overview |
| 1289 | ======== |
| 1290 | |
| 1291 | CMake supports generating a project description file that can be imported into |
| 1292 | the Eclipse Integrated Development Environment (IDE) and used for graphical |
| 1293 | debugging. |
| 1294 | |
| 1295 | The `GNU MCU Eclipse plug-ins`_ provide a mechanism to debug ARM projects in |
| 1296 | Eclipse with pyOCD, Segger J-Link, and OpenOCD debugging tools. |
| 1297 | |
| 1298 | The following tutorial demonstrates how to debug a Zephyr application in |
| 1299 | Eclipse with pyOCD in Windows. It assumes you have already installed the GCC |
| 1300 | ARM Embedded toolchain and pyOCD. |
| 1301 | |
| 1302 | Set Up the Eclipse Development Environment |
| 1303 | ========================================== |
| 1304 | |
| 1305 | #. Download and install `Eclipse IDE for C/C++ Developers`_. |
| 1306 | |
| 1307 | #. In Eclipse, install the GNU MCU Eclipse plug-ins by opening the menu |
| 1308 | ``Window->Eclipse Marketplace...``, searching for ``GNU MCU Eclipse``, and |
| 1309 | clicking ``Install`` on the matching result. |
| 1310 | |
| 1311 | #. Configure the path to the pyOCD GDB server by opening the menu |
| 1312 | ``Window->Preferences``, navigating to ``MCU``, and setting the ``Global |
| 1313 | pyOCD Path``. |
| 1314 | |
| 1315 | Generate and Import an Eclipse Project |
| 1316 | ====================================== |
| 1317 | |
Marti Bolivar | 5edb6d5 | 2019-05-06 23:36:30 -0600 | [diff] [blame] | 1318 | #. Set up a GNU Arm Embedded toolchain as described in |
| 1319 | :ref:`third_party_x_compilers`. |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1320 | |
| 1321 | #. Navigate to a folder outside of the Zephyr tree to build your application. |
| 1322 | |
| 1323 | .. code-block:: console |
| 1324 | |
| 1325 | # On Windows |
| 1326 | cd %userprofile% |
| 1327 | |
| 1328 | .. note:: |
| 1329 | If the build directory is a subdirectory of the source directory, as is |
| 1330 | usually done in Zephyr, CMake will warn: |
| 1331 | |
| 1332 | "The build directory is a subdirectory of the source directory. |
| 1333 | |
| 1334 | This is not supported well by Eclipse. It is strongly recommended to use |
| 1335 | a build directory which is a sibling of the source directory." |
| 1336 | |
| 1337 | #. Configure your application with CMake and build it with ninja. Note the |
| 1338 | different CMake generator specified by the ``-G"Eclipse CDT4 - Ninja"`` |
| 1339 | argument. This will generate an Eclipse project description file, |
| 1340 | :file:`.project`, in addition to the usual ninja build files. |
| 1341 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1342 | .. zephyr-app-commands:: |
| 1343 | :tool: all |
| 1344 | :app: %ZEPHYR_BASE%\samples\synchronization |
| 1345 | :host-os: win |
| 1346 | :board: frdm_k64f |
| 1347 | :gen-args: -G"Eclipse CDT4 - Ninja" |
| 1348 | :goals: build |
| 1349 | :compact: |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1350 | |
| 1351 | #. In Eclipse, import your generated project by opening the menu |
| 1352 | ``File->Import...`` and selecting the option ``Existing Projects into |
| 1353 | Workspace``. Browse to your application build directory in the choice, |
| 1354 | ``Select root directory:``. Check the box for your project in the list of |
| 1355 | projects found and click the ``Finish`` button. |
| 1356 | |
| 1357 | Create a Debugger Configuration |
| 1358 | =============================== |
| 1359 | |
| 1360 | #. Open the menu ``Run->Debug Configurations...``. |
| 1361 | |
| 1362 | #. Select ``GDB PyOCD Debugging``, click the ``New`` button, and configure the |
| 1363 | following options: |
| 1364 | |
| 1365 | - In the Main tab: |
| 1366 | |
Reto Schneider | 7eabab2 | 2018-10-25 16:54:09 +0200 | [diff] [blame] | 1367 | - Project: my_zephyr_app@build |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1368 | - C/C++ Application: :file:`zephyr/zephyr.elf` |
| 1369 | |
| 1370 | - In the Debugger tab: |
| 1371 | |
| 1372 | - pyOCD Setup |
| 1373 | |
David B. Kinder | 34d02e5 | 2018-03-21 10:10:46 -0700 | [diff] [blame] | 1374 | - Executable path: :file:`${pyocd_path}\\${pyocd_executable}` |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1375 | - Uncheck "Allocate console for semihosting" |
| 1376 | |
| 1377 | - Board Setup |
| 1378 | |
| 1379 | - Bus speed: 8000000 Hz |
| 1380 | - Uncheck "Enable semihosting" |
| 1381 | |
| 1382 | - GDB Client Setup |
| 1383 | |
Marti Bolivar | 5edb6d5 | 2019-05-06 23:36:30 -0600 | [diff] [blame] | 1384 | - Executable path example (use your :envvar:`GNUARMEMB_TOOLCHAIN_PATH`): |
David B. Kinder | 34d02e5 | 2018-03-21 10:10:46 -0700 | [diff] [blame] | 1385 | :file:`C:\\gcc-arm-none-eabi-6_2017-q2-update\\bin\\arm-none-eabi-gdb.exe` |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1386 | |
| 1387 | - In the SVD Path tab: |
| 1388 | |
Martí Bolívar | 2d9baf9 | 2020-05-05 09:45:25 -0700 | [diff] [blame] | 1389 | - File path: :file:`<workspace |
| 1390 | top>\\modules\\hal\\nxp\\mcux\\devices\\MK64F12\\MK64F12.xml` |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1391 | |
| 1392 | .. note:: |
| 1393 | This is optional. It provides the SoC's memory-mapped register |
| 1394 | addresses and bitfields to the debugger. |
| 1395 | |
| 1396 | #. Click the ``Debug`` button to start debugging. |
| 1397 | |
| 1398 | RTOS Awareness |
| 1399 | ============== |
| 1400 | |
Maureen Helm | d7d1090 | 2018-07-26 08:37:31 -0500 | [diff] [blame] | 1401 | Support for Zephyr RTOS awareness is implemented in `pyOCD v0.11.0`_ and later. |
| 1402 | It is compatible with GDB PyOCD Debugging in Eclipse, but you must enable |
Carles Cufi | d2465d6 | 2021-03-11 19:51:35 +0100 | [diff] [blame] | 1403 | CONFIG_DEBUG_THREAD_INFO=y in your application. |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1404 | |
Daniel Thompson | 4d096a4 | 2017-02-17 10:21:20 +0000 | [diff] [blame] | 1405 | |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1406 | |
Carles Cufi | b476643 | 2019-06-13 21:59:12 +0200 | [diff] [blame] | 1407 | .. _CMake: https://www.cmake.org |
| 1408 | .. _CMake introduction: https://cmake.org/cmake/help/latest/manual/cmake.1.html#description |
Maureen Helm | e2d73fb | 2018-03-19 15:27:19 -0500 | [diff] [blame] | 1409 | .. _Eclipse IDE for C/C++ Developers: https://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/oxygen2 |
| 1410 | .. _GNU MCU Eclipse plug-ins: https://gnu-mcu-eclipse.github.io/plugins/install/ |
Maureen Helm | d7d1090 | 2018-07-26 08:37:31 -0500 | [diff] [blame] | 1411 | .. _pyOCD v0.11.0: https://github.com/mbedmicro/pyOCD/releases/tag/v0.11.0 |
Marti Bolivar | 7eca256 | 2019-04-02 13:55:25 -0600 | [diff] [blame] | 1412 | .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists |
| 1413 | .. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html |
Anas Nashif | bf9ceac | 2021-04-15 14:40:00 -0400 | [diff] [blame] | 1414 | .. _using Chocolatey: https://chocolatey.org/packages/RapidEE |
Gerard Marull-Paretas | c1a97ac | 2021-05-26 16:13:39 +0200 | [diff] [blame] | 1415 | .. _Example Application: https://github.com/zephyrproject-rtos/example-application |