1.. _beyond-gsg: 2 3Beyond the Getting Started Guide 4################################ 5 6The :ref:`getting_started` gives a straight-forward path to set up 7your Linux, macOS, or Windows environment for Zephyr development. In 8this document, we delve deeper into Zephyr development setup 9issues and alternatives. 10 11.. _python-pip: 12 13Python and pip 14************** 15 16Python 3 and its package manager, pip\ [#pip]_, are used extensively by Zephyr 17to install and run scripts required to compile and run Zephyr 18applications, set up and maintain the Zephyr development environment, 19and build project documentation. 20 21Depending on your operating system, you may need to provide the 22``--user`` flag to the ``pip3`` command when installing new packages. This is 23documented throughout the instructions. 24See `Installing Packages`_ in the Python Packaging User Guide for more 25information about pip\ [#pip]_, including `information on -\\-user`_. 26 27- On Linux, make sure ``~/.local/bin`` is at the front of your :envvar:`PATH` 28 :ref:`environment variable <env_vars>`, or programs installed with ``--user`` 29 won't be found. Installing with ``--user`` avoids conflicts between pip 30 and the system package manager, and is the default on Debian-based 31 distributions. 32 33- On macOS, `Homebrew disables -\\-user`_. 34 35- On Windows, see the `Installing Packages`_ information on ``--user`` if you 36 require using this option. 37 38On all operating systems, pip's ``-U`` flag installs or updates the package if the 39package is already installed locally but a more recent version is available. It 40is good practice to use this flag if the latest version of a package is 41required. (Check the :zephyr_file:`scripts/requirements.txt` file to 42see if a specific Python package version is expected.) 43 44Advanced Platform Setup 45*********************** 46 47Here are some alternative instructions for more advanced platform setup 48configurations for supported development platforms: 49 50.. toctree:: 51 :maxdepth: 1 52 53 Linux setup alternatives <getting_started/installation_linux.rst> 54 macOS setup alternatives <getting_started/installation_mac.rst> 55 Windows setup alternatives <getting_started/installation_win.rst> 56 57.. _gs_toolchain: 58 59Install a Toolchain 60******************* 61 62Zephyr binaries are compiled and linked by a *toolchain* comprised of 63a cross-compiler and related tools which are different from the compiler 64and tools used for developing software that runs natively on your host 65operating system. 66 67You can install the :ref:`Zephyr SDK <toolchain_zephyr_sdk>` to get toolchains for all 68supported architectures, or install an :ref:`alternate toolchain <toolchains>` 69recommended by the SoC vendor or a specific board (check your specific 70:ref:`board-level documentation <boards>`). 71 72You can configure the Zephyr build system to use a specific toolchain by 73setting :ref:`environment variables <env_vars>` such as 74:envvar:`ZEPHYR_TOOLCHAIN_VARIANT <{TOOLCHAIN}_TOOLCHAIN_PATH>` to a supported 75value, along with additional variable(s) specific to the toolchain variant. 76 77.. _gs_toolchain_update: 78 79Updating the Zephyr SDK toolchain 80********************************* 81 82When updating Zephyr SDK, check whether the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` 83or :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variables are already set. 84 85* If the variables are not set, the latest compatible version of Zephyr SDK will be selected 86 by default. Proceed to next step without making any changes. 87 88* If :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` is set, the corresponding toolchain will be selected 89 at build time. Zephyr SDK is identified by the value ``zephyr``. 90 If the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` environment variable is not ``zephyr``, then either 91 unset it or change its value to ``zephyr`` to make sure Zephyr SDK is selected. 92 93* If the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable is set, it will override 94 the default lookup location for Zephyr SDK. If you install Zephyr SDK to one 95 of the :ref:`recommended locations <toolchain_zephyr_sdk_bundle_variables>`, 96 you can unset this variable. Otherwise, set it to your chosen install location. 97 98For more information about these environment variables in Zephyr, see :ref:`env_vars_important`. 99 100Cloning the Zephyr Repositories 101******************************* 102 103The Zephyr project source is maintained in the `GitHub zephyr repo 104<https://github.com/zephyrproject-rtos/zephyr>`_. External modules used 105by Zephyr are found in the parent `GitHub Zephyr project 106<https://github.com/zephyrproject-rtos/>`_. Because of these 107dependencies, it's convenient to use the Zephyr-created :ref:`west 108<west>` tool to fetch and manage the Zephyr and external module source 109code. See :ref:`west-basics` for more details. 110 111Once your development tools are installed, use :ref:`west` to create, 112initialize, and download sources from the zephyr and external module 113repos. We'll use the name ``zephyrproject``, but you can choose any 114name that does not contain a space anywhere in the path. 115 116.. code-block:: console 117 118 west init zephyrproject 119 cd zephyrproject 120 west update 121 122The ``west update`` command fetches and keeps :ref:`modules` in the 123:file:`zephyrproject` folder in sync with the code in the local zephyr 124repo. 125 126.. warning:: 127 128 You must run ``west update`` any time the :file:`zephyr/west.yml` 129 changes, caused, for example, when you pull the :file:`zephyr` 130 repository, switch branches in it, or perform a ``git bisect`` inside of 131 it. 132 133Keeping Zephyr updated 134====================== 135 136To update the Zephyr project source code, you need to get the latest 137changes via ``git``. Afterwards, run ``west update`` as mentioned in 138the previous paragraph. 139 140.. code-block:: console 141 142 # replace zephyrproject with the path you gave west init 143 cd zephyrproject/zephyr 144 git pull 145 west update 146 147Export Zephyr CMake package 148*************************** 149 150The :ref:`cmake_pkg` can be exported to CMake's user package registry if it has 151not already been done as part of :ref:`getting_started`. 152 153.. _gs-board-aliases: 154 155Board Aliases 156************* 157 158Developers who work with multiple boards may find explicit board names 159cumbersome and want to use aliases for common targets. This is 160supported by a CMake file with content like this: 161 162.. code-block:: cmake 163 164 # Variable foo_BOARD_ALIAS=bar replaces BOARD=foo with BOARD=bar and 165 # sets BOARD_ALIAS=foo in the CMake cache. 166 set(pca10028_BOARD_ALIAS nrf51dk/nrf51822) 167 set(pca10056_BOARD_ALIAS nrf52840dk/nrf52840) 168 set(k64f_BOARD_ALIAS frdm_k64f) 169 set(sltb004a_BOARD_ALIAS efr32mg_sltb004a) 170 171and specifying its location in :envvar:`ZEPHYR_BOARD_ALIASES`. This 172enables use of aliases ``pca10028`` in contexts like 173``cmake -DBOARD=pca10028`` and ``west -b pca10028``. 174 175Build and Run an Application 176**************************** 177 178You can build, flash, and run Zephyr applications on real 179hardware using a supported host system. Depending on your operating system, 180you can also run it in emulation with QEMU, or as a native application with 181:ref:`native_sim <native_sim>`. 182Additional information about building applications can be found in the 183:ref:`build_an_application` section. 184 185Build Blinky 186============ 187 188Let's build the :zephyr:code-sample:`blinky` sample application. 189 190Zephyr applications are built to run on specific hardware, called a 191"board"\ [#board_misnomer]_. We'll use the Phytec :ref:`reel_board 192<reel_board>` here, but you can change the ``reel_board`` build target 193to another value if you have a different board. See :ref:`boards` or run 194``west boards`` from anywhere inside the ``zephyrproject`` directory for 195a list of supported boards. 196 197#. Go to the zephyr repository: 198 199 .. code-block:: console 200 201 cd zephyrproject/zephyr 202 203#. Build the blinky sample for the ``reel_board``: 204 205 .. zephyr-app-commands:: 206 :zephyr-app: samples/basic/blinky 207 :board: reel_board 208 :goals: build 209 210The main build products will be in :file:`build/zephyr`; 211:file:`build/zephyr/zephyr.elf` is the blinky application binary in ELF 212format. Other binary formats, disassembly, and map files may be present 213depending on your board. 214 215The other sample applications in the :zephyr_file:`samples` folder are 216documented in :zephyr:code-sample-category:`samples`. 217 218.. note:: If you want to reuse an 219 existing build directory for another board or application, you need to 220 add the parameter ``-p=auto`` to ``west build`` to clean out settings 221 and artifacts from the previous build. 222 223Run the Application by Flashing to a Board 224========================================== 225 226Most hardware boards supported by Zephyr can be flashed by running 227``west flash``. This may require board-specific tool installation and 228configuration to work properly. 229 230See :ref:`application_run` and your specific board's documentation in 231:ref:`boards` for additional details. 232 233.. _setting-udev-rules: 234 235Setting udev rules 236=================== 237 238Flashing a board requires permission to directly access the board 239hardware, usually managed by installation of the flashing tools. On 240Linux systems, if the ``west flash`` command fails, you likely need to 241define udev rules to grant the needed access permission. 242 243Udev is a device manager for the Linux kernel and the udev daemon 244handles all user space events raised when a hardware device is added (or 245removed) from the system. We can add a rules file to grant access 246permission by non-root users to certain USB-connected devices. 247 248The OpenOCD (On-Chip Debugger) project conveniently provides a rules 249file that defined board-specific rules for most Zephyr-supported 250arm-based boards, so we recommend installing this rules 251file by downloading it from their sourceforge repo, or if you've 252installed the Zephyr SDK there is a copy of this rules file in the SDK 253folder: 254 255* Either download the OpenOCD rules file and copy it to the right 256 location:: 257 258 wget -O 60-openocd.rules https://sf.net/p/openocd/code/ci/master/tree/contrib/60-openocd.rules?format=raw 259 sudo cp 60-openocd.rules /etc/udev/rules.d 260 261* or copy the rules file from the Zephyr SDK folder:: 262 263 sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d 264 265Then, in either case, ask the udev daemon to reload these rules:: 266 267 sudo udevadm control --reload 268 269Unplug and plug in the USB connection to your board, and you should have 270permission to access the board hardware for flashing. Check your 271board-specific documentation (:ref:`boards`) for further information if 272needed. 273 274Run the Application in QEMU 275=========================== 276 277On Linux and macOS, you can run Zephyr applications via emulation on your host 278system using `QEMU <https://www.qemu.org/>`_ when targeting either 279the x86 or ARM Cortex-M3 architectures. (QEMU is included with the Zephyr 280SDK installation.) 281 282On Windows, you need to install QEMU manually from 283`Download QEMU <https://www.qemu.org/download/#windows>`_. After installation, 284add path to QEMU installation folder to PATH environment variable. 285To enable QEMU in Test Runner (Twister) on Windows, 286:ref:`set the environment variable <env_vars>` 287``QEMU_BIN_PATH`` to the path of QEMU installation folder. 288 289For example, you can build and run the :zephyr:code-sample:`hello_world` sample using 290the x86 emulation board configuration (``qemu_x86``), with: 291 292.. zephyr-app-commands:: 293 :zephyr-app: samples/hello_world 294 :host-os: unix 295 :board: qemu_x86 296 :goals: build run 297 298To exit QEMU, type :kbd:`Ctrl-a`, then :kbd:`x`. 299 300Use ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 sample. 301 302.. _gs_native: 303 304Run a Sample Application natively (Linux) 305========================================= 306 307You can compile some samples to run as host programs 308on Linux. See :ref:`native_sim` for more information. On 64-bit host operating systems, you 309need to install a 32-bit C library, or build targeting :ref:`native_sim/native/64<native_sim32_64>`. 310 311First, build Hello World for ``native_sim``. 312 313.. zephyr-app-commands:: 314 :zephyr-app: samples/hello_world 315 :host-os: unix 316 :board: native_sim 317 :goals: build 318 319Next, run the application. 320 321.. code-block:: console 322 323 west build -t run 324 # or just run zephyr.exe directly: 325 ./build/zephyr/zephyr.exe 326 327Press :kbd:`Ctrl-C` to exit. 328 329You can run ``./build/zephyr/zephyr.exe --help`` to get a list of available 330options. 331 332This executable can be instrumented using standard tools, such as gdb or 333valgrind. 334 335.. rubric:: Footnotes 336 337.. [#pip] 338 339 pip is Python's package installer. Its ``install`` command first tries to 340 reuse packages and package dependencies already installed on your computer. 341 If that is not possible, ``pip install`` downloads them from the Python 342 Package Index (PyPI) on the Internet. 343 344 The package versions requested by Zephyr's :file:`requirements.txt` may 345 conflict with other requirements on your system, in which case you may 346 want to set up a virtualenv for Zephyr development. 347 348.. [#board_misnomer] 349 350 This has become something of a misnomer over time. While the target can be, 351 and often is, a microprocessor running on its own dedicated hardware 352 board, Zephyr also supports using QEMU to run targets built for other 353 architectures in emulation, targets which produce native host system 354 binaries that implement Zephyr's driver interfaces with POSIX APIs, and even 355 running different Zephyr-based binaries on CPU cores of differing 356 architectures on the same physical chip. Each of these hardware 357 configurations is called a "board," even though that doesn't always make 358 perfect sense in context. 359 360.. _information on -\\-user: 361 https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site 362.. _Homebrew disables -\\-user: 363 https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user 364.. _Installing Packages: 365 https://packaging.python.org/tutorials/installing-packages/ 366