Getting Started Guide

Follow this guide to set up a Zephyr development environment, then build and run a sample application.

Tip

Need help with something? See Asking for Help.

Install Host Dependencies

Follow an operating system specific guide, then come back to this page.

Get the source code

Zephyr’s multi-purpose west tool lets you easily get the Zephyr project repositories. (While it’s easiest to develop with Zephyr using west, we also have documentation for doing without it.)

Bootstrap west

First, install the west binary and bootstrapper using pip3:

# Linux
pip3 install --user west

# macOS (Terminal) and Windows (cmd.exe)
pip3 install west

See Installing west for additional details on installing west. See Installing Packages in the Python Packaging User Guide for more information about pip[1], including this information on --user.

  • On Linux, make sure ~/.local/bin is on your PATH environment variable, or programs installed with --user – like west – won’t be found[2].
  • On macOS, Homebrew disables --user.
  • On Windows, see the Installing Packages information on --user if you require using this option.

Clone the Zephyr Repositories

Clone all of Zephyr’s repositories in a new zephyrproject directory:

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.

Warning

Don’t clone into a directory with spaces anywhere in the path. For example, on Windows, C:\Users\YourName\zephyrproject will work, but 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:

# 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[3]. 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

The Zephyr build system uses CMake. CMake creates build systems in different formats, called generators. Zephyr supports the following generators:

  • 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 west build.

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”[4]. 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 inside the zephyrproject directory for a list of supported boards.

  1. Go to the zephyr repository:

    cd zephyrproject/zephyr
    
  2. Set up your build environment:

    # Linux and macOS
    source zephyr-env.sh
    
    # Windows
    zephyr-env.cmd
    
  3. Build the Hello World sample for the reel_board:

    Using west:

    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 make instead of ninja.

    Using west:

    • to use make just once, add -- -G"Unix Makefiles" to the west build command line; see the west build documentation for an example.
    • to use make by 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
    

Either way, the main build products will be in build/zephyr; 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 -p=auto to west build.

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.

See Run an Application in the Application Development Primer and your board’s documentation in Supported Boards for additional details.

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 (qemu_x86), type:

Using west:

# 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.

Use 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 native_posix.

Using west:

# 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 options.

This executable can be instrumented using standard tools, such as gdb or valgrind.

Footnotes

[1]

pip is Python’s package installer. Its install command first tries to re-use packages and package dependencies already installed on your computer. If that is not possible, pip install downloads them from the Python Package Index (PyPI) on the Internet.

The package versions requested by Zephyr’s requirements.txt may conflict with other requirements on your system, in which case you may want to set up a virtualenv for Zephyr development.

[2]Installing with --user avoids conflicts between pip and the system package manager, and is the default on Debian-based distributions.
[3]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.
[4]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.