Getting Started Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Zephyr Project is a scalable real-time operating system (RTOS) designed for resource-constrained devices, supporting multiple hardware architectures including ARM, Intel x86, RISC-V, and more. It is built with a focus on security and optimization for IoT applications ranging from simple sensors to sophisticated gateways.
Sources: README.rst:17-26
The purpose of this guide is to provide a standardized path for developers to set up a command-line development environment, retrieve the source code, and execute their first application on supported hardware or emulation. This process establishes the foundational toolchain and workspace management necessary for Application Development.
Sources: doc/develop/getting_started/index.rst:3-10
Development Environment Setup
Zephyr supports development on Ubuntu (22.04 LTS or later), macOS (Mojave or later), and Windows (10 or later). The environment relies on a set of core host dependencies to manage the build system and hardware descriptions.
Sources: doc/develop/getting_started/index.rst:15-45
Core Dependencies
Before initializing the workspace, specific minimum versions of software tools must be installed on the host system.
| Tool | Minimum Version | Description |
|---|---|---|
| CMake | 3.20.5 | Build system generator |
| Python | 3.10 | Scripting and package management |
| Devicetree Compiler (dtc) | 1.4.6 | Processes hardware descriptions |
Sources: doc/develop/getting_started/index.rst:58-75
Host Configuration Flow
The following diagram illustrates the sequence of operations required to prepare the host machine for Zephyr development.
This flowchart defines the prerequisite steps for both physical hardware and emulation targets.
Sources: doc/develop/getting_started/index.rst:133-318
Workspace and Source Management
Zephyr uses a meta-tool called west to manage its multi-repo structure. A Zephyr workspace (often named zephyrproject) contains the main Zephyr repository and various external modules (HALs, file systems, etc.).
Sources: doc/develop/beyond-GSG.rst:75-85
Initialization Process
- Initialize:
west init ~/zephyrprojectcreates the workspace. - Update:
west updatesynchronizes modules defined inwest.yml. - Export:
west zephyr-exportregisters the Zephyr CMake package for the current user. - Python Requirements:
west packages pip --installensures all script dependencies are met within the virtual environment.
Sources: doc/develop/getting_started/index.rst:167-216
Toolchain: Zephyr SDK
The Zephyr Software Development Kit (SDK) is a comprehensive bundle containing cross-compilers for all supported architectures (ARM, x86, RISC-V, etc.). On Linux, it additionally provides host tools like QEMU and OpenOCD for emulation and debugging.
Sources: doc/develop/getting_started/index.rst:303-312
Toolchain Integration Logic
The build system identifies the toolchain through environment variables.
This diagram shows how the Zephyr build system selects the appropriate compiler based on environment configuration.
Sources: doc/develop/beyond-GSG.rst:50-68, doc/develop/getting_started/index.rst:446-454
Building and Flashing Applications
The standard workflow for running an application involves selecting a target "board" and using west to compile and transfer the binary.
Sources: doc/develop/beyond-GSG.rst:124-135
The Build Workflow
Applications are typically built from the samples directory. The "Blinky" sample serves as the primary verification tool for new setups.
Sources: doc/develop/getting_started/index.rst:384-394
- Build Command:
west build -p always -b <board_name> <sample_path>-p always: Forces a "pristine" build, clearing previous artifacts.-b: Specifies the target hardware or emulation board.
- Flash Command:
west flash- Requires board-specific drivers or udev rules on Linux to access the debug probe.
Sources: doc/develop/getting_started/index.rst:390-428
Emulation with QEMU
For developers without physical hardware, Zephyr supports emulation for x86 and ARM Cortex-M3 via QEMU.
# Building and running for x86 emulation
west build -b qemu_x86 samples/hello_world
west build -t run
Sources: doc/develop/beyond-GSG.rst:196-210
Advanced Configuration
Beyond basic setup, developers can optimize their workflow using aliases and specialized Linux rules.
Sources: doc/develop/beyond-GSG.rst:104
- Board Aliases: Developers can map complex board strings to short names (e.g.,
pca10056fornrf52840dk/nrf52840) using a CMake file referenced byZEPHYR_BOARD_ALIASES.
Sources: doc/develop/beyond-GSG.rst:105-120 - udev Rules: On Linux, permission to access USB debug probes is granted by installing OpenOCD rules (e.g.,
60-openocd.rules) to/etc/udev/rules.d.
Sources: doc/develop/beyond-GSG.rst:160-185
Summary
The Getting Started Guide ensures a consistent entry point into the Zephyr ecosystem by mandating specific tool versions and a structured workspace managed by west. By following the sequence of OS updates, dependency installation, and SDK configuration, developers can quickly move from source code acquisition to application execution on both physical and emulated hardware.
Sources: doc/develop/getting_started/index.rst:436-444