Getting Started Guide¶
Follow this guide to set up a Zephyr development environment, then build and run a sample application.
Need help with something? See Asking for Help.
Install Host Dependencies¶
Python and pip¶
Python 3 and its package manager, pip, are used extensively by Zephyr to install and run scripts that are required to compile and run Zephyr applications.
Depending on your operating system, you may or may not need to provide the
--user flag to the
pip3 command when installing new packages. This is
documented throughout the instructions.
See Installing Packages in the Python Packaging User Guide for more
information about pip, including this information on --user.
- On Linux, make sure
~/.local/binis on your
PATHenvironment variable, or programs installed with
--userwon’t be found.
- On macOS, Homebrew disables --user.
- On Windows, see the Installing Packages information on
--userif you require using this option.
On all operating systems, the
-U flag installs or updates the package if the
package is already installed locally but a more recent version is available. It
is good practice to use this flag if the latest version of a package is
Get the source code¶
# Linux pip3 install --user -U west # macOS (Terminal) and Windows (cmd.exe) pip3 install -U west
See Installing west for additional details on installing west.
Clone the Zephyr Repositories¶
Clone all of Zephyr’s repositories in a new
west init zephyrproject cd zephyrproject west update
You can replace
zephyrproject with another directory name. West creates
the directory if it doesn’t exist. See Multiple Repository Management for more details.
Don’t clone into 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¶
Install Python packages required by Zephyr. From the
folder that you cloned Zephyr into:
# Linux pip3 install --user -r zephyr/scripts/requirements.txt # macOS and Windows pip3 install -r zephyr/scripts/requirements.txt
Set Up a Toolchain¶
Zephyr binaries are compiled and linked by a toolchain. You now need to install and configure a toolchain. Toolchains are installed in the usual ways you get programs: with installer programs or system package managers, by downloading and extracting a zip archive, etc.
You configure the toolchain to use by setting environment variables. You need to set
ZEPHYR_TOOLCHAIN_VARIANT to a supported
value, along with additional variable(s) specific to the toolchain variant.
The following choices are available. If you’re not sure what to use, check your board-level documentation. If you’re targeting an Arm Cortex-M, GNU ARM Embedded is a safe bet. On Linux, you can skip this step if you set up the Zephyr SDK toolchains or if you want to Run a Sample Application natively (POSIX OS).
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.
You can build applications by either running
cmake directly or using the
west build convenience wrapper.
A Brief Note on the Zephyr Build System¶
Unix Makefiles: Supported on UNIX-like platforms (Linux, macOS).
Ninja: Supported on all platforms.
You can use any supported generator when running
cmake directly or using
Build Hello World¶
Let’s build the Hello World sample application.
Zephyr applications are built to run on specific hardware, which is
called a “board”. We’ll use the reel_board here, but you can change
reel_board to another value if you
have a different board. See Supported Boards or run
west boards from anywhere
zephyrproject directory for a list of supported boards.
Go to the zephyr repository:
Set up your build environment:
# Linux and macOS source zephyr-env.sh # Windows zephyr-env.cmd
Build the Hello World sample for the
west build -b reel_board samples/hello_world
Using CMake and ninja:
# Use cmake to configure a Ninja-based buildsystem: cmake -B build -GNinja -DBOARD=reel_board samples/hello_world # Now run ninja on the generated build system: ninja -C build
On Linux and macOS, you can also build with
- to use
makejust once, add
-- -G"Unix Makefiles"to the west build command line; see the west build documentation for an example.
- to use
makeby default from now on, run
west config build.generator "Unix Makefiles".
Using CMake directly:
# Use cmake to configure a Make-based buildsystem: cmake -B build -DBOARD=reel_board samples/hello_world # Now run ninja on the generated build system: make -C build
- to use
Either way, the main build products will be in
build/zephyr/zephyr.elf is the Hello World application binary in ELF
format. Other binary formats, disassembly, and map files may be present
depending on your board.
The other sample applications in samples are documented in
Samples and Demos. If you want to re-use an existing build directory for
another board or application, you need to run the
pristine build system
target or pass
Run the Application by Flashing to a Board¶
Most “real hardware” boards supported by Zephyr can be flashed by running
west flash, or by running
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
# From the root of the zephyr repository west build -b qemu_x86 samples/hello_world west build -t run
Using CMake and ninja:
# From the root of the zephyr repository # Use cmake to configure a Ninja-based buildsystem: cmake -B build -GNinja -DBOARD=qemu_x86 samples/hello_world # Now run ninja on the generated build system: ninja -C build ninja -C build run
To exit, type Ctrl-a, then x.
qemu_cortex_m3 to target an emulated Arm Cortex-M3 instead.
Run a Sample Application natively (POSIX OS)¶
Finally, it is also possible to compile some samples to run as host processes on a POSIX OS. This is currently only tested on Linux hosts. See Native POSIX execution (native_posix) for more information. On 64 bit host operating systems, you need to install a 32 bit C library; see Host system dependencies for details.
First, build Hello World for
# From the root of the zephyr repository west build -b native_posix samples/hello_world
Using CMake and ninja:
# From the root of the zephyr repository # Use cmake to configure a Ninja-based buildsystem: cmake -B build -GNinja -DBOARD=native_posix samples/hello_world # Now run ninja on the generated build system: ninja -C build
Next, run the application.
# With west: west build -t run # With ninja: ninja -Cbuild run # or just run zephyr.exe directly: ./build/zephyr/zephyr.exe
Press Ctrl-C to exit.
You can run
./build/zephyr/zephyr.exe --help to get a list of available
This executable can be instrumented using standard tools, such as gdb or valgrind.
|||(1, 2) |
pip is Python’s package installer. Its
The package versions requested by Zephyr’s
|||Installing with |
|||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.|
|||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.|