Getting Started Guide¶
Follow this guide to set up a Zephyr development environment on your system, and then build and run a sample application.
Need help with something? See Asking for Help.
Set Up a Development System¶
Follow one of the following guides for your host operating system.
Get the source code¶
Zephyr’s multi-purpose West (Zephyr’s meta-tool) tool lets you easily get the Zephyr project source code, instead of manually cloning the Zephyr repos along with west itself.
It’s possible to use Zephyr without installing west, but you have to really know what you are doing.
First, install the
west binary and bootstrapper:
# Linux pip3 install --user west # macOS and Windows pip3 install west
See Install Python Dependencies for additional clarfication on using the
Clone the Zephyr Repositories¶
If you have run
source zephyr-env.sh (on Linux or macOS) or
zephyr-env.cmd (on Windows) on a clone of zephyr that predates the
introduction of west, then the copy of west included in the clone will
override the bootstrapper installed with
pip. In that case close the
shell and open a new one in order to remove it from the
can check which
west is being executed by running:
You should see
West bootstrapper version: v0.5.0 (or higher).
Next, clone the Zephyr source code repositories from GitHub using the
west tool you just installed:
west init zephyrproject cd zephyrproject west update
You can replace
zephyrproject with the folder name of your choice.
West will create the named folder if it doesn’t already exist.
If no folder name is specified, west initializes the current
If you had previously cloned the zephyr repository manually using Git,
create an empty enclosing folder (for example
and move the cloned repository into it. From the enclosing folder run:
west init -l zephyr/ west update
-l <path to zephyr> parameter instructs
west to use an existing
local copy instead of cloning a remote repository. This will create a full
Zephyr installation (see below).
west init will clone west itself into
initialize a local installation. Running
west update will pull all the
projects referenced by the manifest file (
zephyr/west.yml) into the
folders specified in it. See Multiple Repository Management for additional details, a
list of the folders and files that west will create as part of the process,
and more on how
west helps manage multiple repositories.
Don’t clone Zephyr to a directory with spaces anywhere in the path.
For example, on Windows,
C:\Users\Your Name\zephyrproject will cause cryptic
errors when you try to build an application.
Install Python Dependencies¶
Next, install additional Python packages required by Zephyr in a shell or
# Linux pip3 install --user -r zephyr/scripts/requirements.txt # macOS and Windows pip3 install -r zephyr/scripts/requirements.txt
Some notes on pip’s
- Installing with
--useris the default behavior on Debian-based distributions and is generally recommended on Linux to avoid conflicts with Python packages installed using the system package manager.
- On Linux, verify the Python user install directory
~/.local/binis at the front of your PATH environment variable, otherwise installed packages won’t be found.
- On macOS, Homebrew disables the
- On Windows using
cmd.exe, although it’s possible to use the
--userflag, it makes it harder for the command prompt to find executables installed by pip.
Set Up a Toolchain¶
On Linux, you can skip this step if you installed the Zephyr SDK, which includes toolchains for all supported Zephyr architectures.
In some specific configurations like non-MCU x86 targets on Linux,
you may be able to re-use the native development tools provided by
your operating system instead of an SDK by setting
If you want, you can use the SDK host tools (such as OpenOCD) with a
different toolchain by keeping the
environment variable set to the Zephyr SDK installation directory, while
ZEPHYR_TOOLCHAIN_VARIANT appropriately for a non-SDK
Zephyr binaries are compiled using software called a toolchain. You need to install and configure a toolchain to develop Zephyr applications.
Toolchains can be installed in different ways, including using installer
programs, system package managers, or simply downloading a zip file or other
archive and extracting the files somewhere on your computer. You configure
the toolchain by setting the environment variable
ZEPHYR_TOOLCHAIN_VARIANT to a recognized value, along with some
additional variable(s) specific to that toolchain (usually, this is just one
more variable which contains the path where you installed the toolchain on your
In previous releases of Zephyr, the
The following toolchain installation options are available. The right choice for you depends on where you want to run Zephyr and any other requirements you may have. Check your board-level documentation if you are unsure about what choice to use.
To use the same toolchain in new sessions in the future you can make sure the variables are set persistently.
On macOS and Linux, you can set the variables by putting the
setting environment variables in a file
~/.zephyrrc. On Windows, you
can put the
set lines in
%userprofile%\zephyrrc.cmd. These files
are used to modify your environment when you run
zephyr-env.cmd (Windows), which you will learn about in the next
Build and Run an Application¶
Next, build a sample Zephyr application. You can then flash and run it on real hardware using any supported host system. Depending on your operating system, you can also run it in emulation with QEMU or as a native POSIX application.
A Brief Note on the Zephyr Build System¶
Unix Makefiles: Supported on UNIX-like platforms (Linux, macOS).
Ninja: Supported on all platforms.
This documentation and Zephyr’s continuous integration system mainly use
Ninja, but you should be able to use any supported generator to build
Zephyr applications, both when using
cmake directly or
Build the Application¶
Follow these steps to build the Hello World sample application provided with Zephyr.
As mentioned earlier, Zephyr’s build system is based on
CMake. You can build an application either by using
cmake directly or by using west, Zephyr’s meta-tool that is
also used to manage the repositories. You can find
additional information about west’s build capabilities in
Building, Flashing and Debugging.
Zephyr applications have to be configured and built to run on some hardware
configuration, which is called a “board”. These steps show
how to build the Hello World application for the reel board board. You
can build for a different board by changing
reel_board to another
supported value. See Supported Boards for more information, or use the
build target from an initialized build directory to get a list.
If you want to re-use your existing build directory to build for another
board, you must delete that directory’s contents first by using the
pristine build target.
Navigate to the main project directory:
Set up your build environment:
# On Linux/macOS source zephyr-env.sh # On Windows zephyr-env.cmd
Build the Hello World sample for the
west build -b reel_board samples/hello_world
Using CMake and ninja:
# On Linux/macOS cd samples/hello_world mkdir build && cd build # On Windows cd samples\hello_world mkdir build & cd build # Use cmake to configure a Ninja-based build system: cmake -GNinja -DBOARD=reel_board .. # Now run ninja on the generated build system: ninja
On Linux/macOS you can also use
cmaketo build with
cd samples/hello_world mkdir build && cd build # Use cmake to configure a Make-based build system: cmake -DBOARD=reel_board .. # Now run make on the generated build system: make
The main build products are in
The final application binary in ELF format is named
default. Other binary formats and byproducts such as disassembly and map files
will be present depending on the target and build system configuration.
Run the Application by Flashing to a Board¶
Most “real hardware” boards supported by Zephyr can be flashed by running
west flash or
ninja flash from the build directory. However, this may
require board-specific tool installation and configuration to work properly.
Run the Application in QEMU¶
On Linux and macOS, you can run Zephyr applications in emulation on your host system using QEMU when targeting either the X86 or ARM Cortex-M3 architectures.
To build and run Hello World using the x86 emulation board configuration
west build -b qemu_x86 samples/hello_world west build -t run
Using CMake and ninja:
cd $ZEPHYR_BASE/samples/hello_world mkdir build && cd build # Use cmake to configure a Ninja-based build system: cmake -GNinja -DBOARD=qemu_x86 .. # Now run ninja on the generated build system: ninja ninja run
To exit, type Ctrl-a, then x.
qemu_cortex_m3 board configuration to run on an emulated Arm
Run a Sample Application natively (POSIX OS)¶
Finally, it is also possible to compile some samples to run as native processes on a POSIX OS. This is currently only tested on Linux hosts.
On 64 bit host operating systems, you will also need a 32 bit C library installed. See the Native POSIX execution (native_posix) section on host dependencies for more information.
To compile and run Hello World in this way, type:
west build -b native_posix samples/hello_world
Using CMake and ninja:
cd $ZEPHYR_BASE/samples/hello_world mkdir build && cd build # Use cmake to configure a Ninja-based build system: cmake -GNinja -DBOARD=native_posix .. # Now run ninja on the generated build system: ninja
# With west west build -t run # With ninja ninja run # or just: zephyr/zephyr.exe # Press Ctrl+C to exit
You can run
zephyr/zephyr.exe --help to get a list of available
options. See the Native POSIX execution (native_posix) document for more information.
This executable can be instrumented using standard tools, such as gdb or valgrind.
|||For details, see https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install—user.|
Usually, the toolchain is a cross-compiler and related tools which are different than the host compilers and other programs available for developing software to run natively on your operating system.
One exception is when building Zephyr as a host binary to run on a POSIX operating system. In this case, you still need to set up a toolchain, but it will provide host compilers instead of cross compilers. For details on this option, see Native POSIX execution (native_posix).
|||This has become something of a misnomer over time. While the target can be, and often is, a microprocessor running on its own dedicated hardware board, Zephyr also supports using QEMU to run targets built for other architectures in emulation, targets which produce native host system binaries that implement Zephyr’s driver interfaces with POSIX APIs, and even running different Zephyr-based binaries on CPU cores of differing architectures on the same physical chip. Each of these hardware configurations is called a “board,” even though that doesn’t always make perfect sense in context.|