1.. _getting_started: 2 3Getting Started Guide 4##################### 5 6Follow this guide to: 7 8- Set up a command-line Zephyr development environment on Ubuntu, macOS, or 9 Windows (instructions for other Linux distributions are discussed in 10 :ref:`installation_linux`) 11- Get the source code 12- Build, flash, and run a sample application 13 14.. _host_setup: 15 16Select and Update OS 17******************** 18 19Click the operating system you are using. 20 21.. tabs:: 22 23 .. group-tab:: Ubuntu 24 25 This guide covers Ubuntu version 22.04 LTS and later. 26 If you are using a different Linux distribution see :ref:`installation_linux`. 27 28 .. code-block:: bash 29 30 sudo apt update 31 sudo apt upgrade 32 33 .. group-tab:: macOS 34 35 On macOS Mojave or later, select *System Preferences* > 36 *Software Update*. Click *Update Now* if necessary. 37 38 On other versions, see `this Apple support topic 39 <https://support.apple.com/en-us/HT201541>`_. 40 41 .. group-tab:: Windows 42 43 Select *Start* > *Settings* > *Update & Security* > *Windows Update*. 44 Click *Check for updates* and install any that are available. 45 46.. _install-required-tools: 47 48Install dependencies 49******************** 50 51Next, you'll install some host dependencies using your package manager. 52 53The current minimum required version for the main dependencies are: 54 55.. list-table:: 56 :header-rows: 1 57 58 * - Tool 59 - Min. Version 60 61 * - `CMake <https://cmake.org/>`_ 62 - 3.20.5 63 64 * - `Python <https://www.python.org/>`_ 65 - 3.10 66 67 * - `Devicetree compiler <https://www.devicetree.org/>`_ 68 - 1.4.6 69 70.. tabs:: 71 72 .. group-tab:: Ubuntu 73 74 .. _install_dependencies_ubuntu: 75 76 #. Use ``apt`` to install the required dependencies: 77 78 .. code-block:: bash 79 80 sudo apt install --no-install-recommends git cmake ninja-build gperf \ 81 ccache dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \ 82 xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 83 84 .. note:: 85 86 Due to the unavailability of ``gcc-multilib`` and ``g++-multilib`` on AArch64 87 (ARM64) systems, you may need to remove them from the list of packages to install. 88 89 #. Verify the versions of the main dependencies installed on your system by entering: 90 91 .. code-block:: bash 92 93 cmake --version 94 python3 --version 95 dtc --version 96 97 Check those against the versions in the table in the beginning of this section. 98 Refer to the :ref:`installation_linux` page for additional information on updating 99 the dependencies manually. 100 101 .. group-tab:: macOS 102 103 .. _install_dependencies_macos: 104 105 #. Install `Homebrew <https://brew.sh/>`_: 106 107 .. code-block:: bash 108 109 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 110 111 #. After the Homebrew installation script completes, follow the on-screen 112 instructions to add the Homebrew installation to the path. 113 114 * On macOS running on Apple Silicon, this is achieved with: 115 116 .. code-block:: bash 117 118 (echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile 119 source ~/.zprofile 120 121 * On macOS running on Intel, use the command for Apple Silicon, but replace ``/opt/homebrew/`` with ``/usr/local/``. 122 123 #. Use ``brew`` to install the required dependencies: 124 125 .. code-block:: bash 126 127 brew install cmake ninja gperf python3 python-tk ccache qemu dtc libmagic wget openocd 128 129 #. Add the Homebrew Python folder to the path, in order to be able to 130 execute ``python`` and ``pip`` as well ``python3`` and ``pip3``. 131 132 .. code-block:: bash 133 134 (echo; echo 'export PATH="'$(brew --prefix)'/opt/python/libexec/bin:$PATH"') >> ~/.zprofile 135 source ~/.zprofile 136 137 .. group-tab:: Windows 138 139 .. note:: 140 141 Due to issues finding executables, the Zephyr Project doesn't 142 currently support application flashing using the `Windows Subsystem 143 for Linux (WSL) 144 <https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`_ 145 (WSL). 146 147 Therefore, we don't recommend using WSL when getting started. 148 149 In modern version of Windows (10 and later) it is recommended to install the Windows Terminal 150 application from the Microsoft Store. Instructions are provided for a ``cmd.exe`` or 151 PowerShell command prompts. 152 153 These instructions rely on Windows' official package manager, `winget`_. 154 If using winget isn't an option, you can install dependencies from their 155 respective websites and ensure the command line tools are on your 156 :envvar:`PATH` :ref:`environment variable <env_vars>`. 157 158 |p| 159 160 .. _install_dependencies_windows: 161 162 #. In modern Windows versions, winget is already pre-installed by default. 163 You can verify that this is the case by typing ``winget`` in a terminal 164 window. If that fails, you can then `install winget`_. 165 166 #. Open a Command Prompt (``cmd.exe``) or PowerShell terminal window. 167 To do so, press the Windows key, type ``cmd.exe`` or PowerShell and 168 click on the result. 169 170 #. Use ``winget`` to install the required dependencies: 171 172 .. code-block:: bat 173 174 winget install Kitware.CMake Ninja-build.Ninja oss-winget.gperf python Git.Git oss-winget.dtc wget 7zip.7zip 175 176 #. Close the terminal window. 177 178 .. note:: 179 180 You may need to add the 7zip installation folder to your ``PATH``. 181 182 183.. _winget: https://learn.microsoft.com/en-us/windows/package-manager/ 184.. _install winget: https://aka.ms/getwinget 185 186.. _get_the_code: 187.. _clone-zephyr: 188.. _install_py_requirements: 189.. _gs_python_deps: 190 191Get Zephyr and install Python dependencies 192****************************************** 193 194Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west 195<west>` workspace. In the following instructions the name :file:`zephyrproject` 196is used for the workspace, however in practice its name and location can be freely 197chosen. You'll also install Zephyr's additional Python dependencies in a 198`Python virtual environment`_. 199 200.. _Python virtual environment: https://docs.python.org/3/library/venv.html 201 202.. tabs:: 203 204 .. group-tab:: Ubuntu 205 206 #. Create a new virtual environment: 207 208 .. code-block:: bash 209 210 python3 -m venv ~/zephyrproject/.venv 211 212 #. Activate the virtual environment: 213 214 .. code-block:: bash 215 216 source ~/zephyrproject/.venv/bin/activate 217 218 Once activated your shell will be prefixed with ``(.venv)``. The 219 virtual environment can be deactivated at any time by running 220 ``deactivate``. 221 222 .. note:: 223 224 Remember to activate the virtual environment every time you 225 start working. 226 227 #. Install west: 228 229 .. code-block:: bash 230 231 pip install west 232 233 #. Get the Zephyr source code: 234 235 .. only:: not release 236 237 .. code-block:: bash 238 239 west init ~/zephyrproject 240 cd ~/zephyrproject 241 west update 242 243 .. only:: release 244 245 .. We need to use a parsed-literal here because substitutions do not work in code 246 blocks. This means users can't copy-paste these lines as easily as other blocks but 247 should be good enough still :) 248 249 .. parsed-literal:: 250 251 west init ~/zephyrproject --mr v |zephyr-version-ltrim| 252 cd ~/zephyrproject 253 west update 254 255 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 256 automatically load boilerplate code required for building Zephyr 257 applications. 258 259 .. code-block:: bash 260 261 west zephyr-export 262 263 #. Install Python dependencies using ``west packages``. 264 265 .. code-block:: bash 266 267 west packages pip --install 268 269 .. group-tab:: macOS 270 271 #. Create a new virtual environment: 272 273 .. code-block:: bash 274 275 python3 -m venv ~/zephyrproject/.venv 276 277 #. Activate the virtual environment: 278 279 .. code-block:: bash 280 281 source ~/zephyrproject/.venv/bin/activate 282 283 Once activated your shell will be prefixed with ``(.venv)``. The 284 virtual environment can be deactivated at any time by running 285 ``deactivate``. 286 287 .. note:: 288 289 Remember to activate the virtual environment every time you 290 start working. 291 292 #. Install west: 293 294 .. code-block:: bash 295 296 pip install west 297 298 #. Get the Zephyr source code: 299 300 .. code-block:: bash 301 302 west init ~/zephyrproject 303 cd ~/zephyrproject 304 west update 305 306 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 307 automatically load boilerplate code required for building Zephyr 308 applications. 309 310 .. code-block:: bash 311 312 west zephyr-export 313 314 #. Install Python dependencies using ``west packages``. 315 316 .. code-block:: bash 317 318 west packages pip --install 319 320 .. group-tab:: Windows 321 322 #. Open a ``cmd.exe`` or PowerShell terminal window **as a regular user** 323 324 #. Create a new virtual environment: 325 326 .. tabs:: 327 328 .. code-tab:: bat 329 330 cd %HOMEPATH% 331 python -m venv zephyrproject\.venv 332 333 .. code-tab:: powershell 334 335 cd $Env:HOMEPATH 336 python -m venv zephyrproject\.venv 337 338 #. Activate the virtual environment: 339 340 .. tabs:: 341 342 .. code-tab:: bat 343 344 zephyrproject\.venv\Scripts\activate.bat 345 346 .. code-tab:: powershell 347 348 zephyrproject\.venv\Scripts\Activate.ps1 349 350 Once activated your shell will be prefixed with ``(.venv)``. The 351 virtual environment can be deactivated at any time by running 352 ``deactivate``. 353 354 .. note:: 355 356 Remember to activate the virtual environment every time you 357 start working. 358 359 #. Install west: 360 361 .. code-block:: bat 362 363 pip install west 364 365 #. Get the Zephyr source code: 366 367 .. code-block:: bat 368 369 west init zephyrproject 370 cd zephyrproject 371 west update 372 373 #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to 374 automatically load boilerplate code required for building Zephyr 375 applications. 376 377 .. code-block:: bat 378 379 west zephyr-export 380 381 #. Install Python dependencies using ``west packages``. 382 383 .. code-block:: bat 384 385 west packages pip --install 386 387Install the Zephyr SDK 388********************** 389 390The :ref:`Zephyr Software Development Kit (SDK) <toolchain_zephyr_sdk>` 391contains toolchains for each of Zephyr's supported architectures, which 392include a compiler, assembler, linker and other programs required to build 393Zephyr applications. 394 395For Linux, it also contains additional host tools, such as custom QEMU and OpenOCD builds 396that are used to emulate, flash and debug Zephyr applications. 397 398 399.. tabs:: 400 401 .. group-tab:: Ubuntu 402 403 Install the Zephyr SDK using the ``west sdk install``. 404 405 .. code-block:: bash 406 407 cd ~/zephyrproject/zephyr 408 west sdk install 409 410 .. tip:: 411 412 Using the command options, you can specify the SDK installation destination 413 and which architecture of toolchains to install. 414 See ``west sdk install --help`` for details. 415 416 .. group-tab:: macOS 417 418 Install the Zephyr SDK using the ``west sdk install``. 419 420 .. code-block:: bash 421 422 cd ~/zephyrproject/zephyr 423 west sdk install 424 425 .. tip:: 426 427 Using the command options, you can specify the SDK installation destination 428 and which architecture of toolchains to install. 429 See ``west sdk install --help`` for details. 430 431 .. group-tab:: Windows 432 433 Install the Zephyr SDK using the ``west sdk install``. 434 435 .. tabs:: 436 437 .. code-tab:: bat 438 439 cd %HOMEPATH%\zephyrproject\zephyr 440 west sdk install 441 442 .. code-tab:: powershell 443 444 cd $Env:HOMEPATH\zephyrproject\zephyr 445 west sdk install 446 447 .. tip:: 448 449 Using the command options, you can specify the SDK installation destination 450 and which architecture of toolchains to install. 451 See ``west sdk install --help`` for details. 452 453.. note:: 454 455 If you want to install Zephyr SDK without using the ``west sdk`` command, 456 please see :ref:`toolchain_zephyr_sdk_install`. 457 458.. _getting_started_run_sample: 459 460Build the Blinky Sample 461*********************** 462 463.. note:: 464 465 :zephyr:code-sample:`blinky` is compatible with most, but not all, :ref:`boards`. If your board 466 does not meet Blinky's :ref:`blinky-sample-requirements`, then 467 :zephyr:code-sample:`hello_world` is a good alternative. 468 469 If you are unsure what name west uses for your board, ``west boards`` 470 can be used to obtain a list of all boards Zephyr supports. 471 472Build the :zephyr:code-sample:`blinky` with :ref:`west build <west-building>`, changing 473``<your-board-name>`` appropriately for your board: 474 475.. tabs:: 476 477 .. group-tab:: Ubuntu 478 479 .. code-block:: bash 480 481 cd ~/zephyrproject/zephyr 482 west build -p always -b <your-board-name> samples/basic/blinky 483 484 .. group-tab:: macOS 485 486 .. code-block:: bash 487 488 cd ~/zephyrproject/zephyr 489 west build -p always -b <your-board-name> samples/basic/blinky 490 491 .. group-tab:: Windows 492 493 .. tabs:: 494 495 .. code-tab:: bat 496 497 cd %HOMEPATH%\zephyrproject\zephyr 498 west build -p always -b <your-board-name> samples\basic\blinky 499 500 .. code-tab:: powershell 501 502 cd $Env:HOMEPATH\zephyrproject\zephyr 503 west build -p always -b <your-board-name> samples\basic\blinky 504 505The ``-p always`` option forces a pristine build, and is recommended for new 506users. Users may also use the ``-p auto`` option, which will use 507heuristics to determine if a pristine build is required, such as when building 508another sample. 509 510.. note:: 511 512 A board may contain one or multiple SoCs, Also, each SoC may contain one or 513 more CPU clusters. 514 When building for such boards it is necessary to specify the SoC or CPU 515 cluster for which the sample must be built. 516 For example to build :zephyr:code-sample:`blinky` for the ``cpuapp`` core on 517 the :zephyr:board:`nrf5340dk` the board must be provided as: 518 ``nrf5340dk/nrf5340/cpuapp``. See also :ref:`board_terminology` for more 519 details. 520 521Flash the Sample 522**************** 523 524Connect your board, usually via USB, and turn it on if there's a power switch. 525If in doubt about what to do, check your board's page in :ref:`boards`. 526 527Then flash the sample using :ref:`west flash <west-flashing>`: 528 529.. code-block:: shell 530 531 west flash 532 533.. note:: 534 535 You may need to install additional :ref:`host tools <flash-debug-host-tools>` 536 required by your board. The ``west flash`` command will print an error if any 537 required dependencies are missing. 538 539.. note:: 540 541 When using Linux, you may need to configure udev rules the first time 542 of using a debug probe. 543 Please also see :ref:`setting-udev-rules`. 544 545If you're using blinky, the LED will start to blink as shown in this figure: 546 547.. figure:: img/ReelBoard-Blinky.png 548 :width: 400px 549 :name: reelboard-blinky 550 551 Phytec :ref:`reel_board <reel_board>` running blinky 552 553Next Steps 554********** 555 556Here are some next steps for exploring Zephyr: 557 558* Try other :zephyr:code-sample-category:`samples` 559* Learn about :ref:`application` and the :ref:`west <west>` tool 560* Find out about west's :ref:`flashing and debugging <west-build-flash-debug>` 561 features, or more about :ref:`flashing_and_debugging` in general 562* Check out :ref:`beyond-GSG` for additional setup alternatives and ideas 563* Discover :ref:`project-resources` for getting help from the Zephyr 564 community 565 566.. _troubleshooting_installation: 567 568Troubleshooting Installation 569**************************** 570 571Here are some tips for fixing some issues related to the installation process. 572 573.. _toolchain_zephyr_sdk_update: 574 575Double Check the Zephyr SDK Variables When Updating 576=================================================== 577 578When updating Zephyr SDK, check whether the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` 579or :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variables are already set. 580See :ref:`gs_toolchain_update` for more information. 581 582For more information about these environment variables in Zephyr, see :ref:`env_vars_important`. 583 584.. _help: 585 586Asking for Help 587*************** 588 589You can ask for help on a mailing list or on Discord. Please send bug reports and 590feature requests to GitHub. 591 592* **Mailing Lists**: users@lists.zephyrproject.org is usually the right list to 593 ask for help. `Search archives and sign up here`_. 594* **Discord**: You can join with this `Discord invite`_. 595* **GitHub**: Use `GitHub issues`_ for bugs and feature requests. 596 597How to Ask 598========== 599 600.. important:: 601 602 Please search this documentation and the mailing list archives first. Your 603 question may have an answer there. 604 605Don't just say "this isn't working" or ask "is this working?". Include as much 606detail as you can about: 607 608#. What you want to do 609#. What you tried (commands you typed, etc.) 610#. What happened (output of each command, etc.) 611 612Use Copy/Paste 613============== 614 615Please **copy/paste text** instead of taking a picture or a screenshot of it. 616Text includes source code, terminal commands, and their output. 617 618Doing this makes it easier for people to help you, and also helps other users 619search the archives. Unnecessary screenshots exclude vision impaired 620developers; some are major Zephyr contributors. `Accessibility`_ has been 621recognized as a basic human right by the United Nations. 622 623When copy/pasting more than 5 lines of computer text into Discord or Github, 624create a snippet using three backticks to delimit the snippet. 625 626.. _Search archives and sign up here: https://lists.zephyrproject.org/g/users 627.. _Discord invite: https://chat.zephyrproject.org 628.. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues 629.. _Accessibility: https://www.w3.org/standards/webdesign/accessibility 630
