The latest development version of this page may be more current than this released 2.0.0 version.

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

Python and pip

Python 3 and its package manager, pip[1], 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[1], including this information on --user.

• On Linux, make sure ~/.local/bin is on your PATH environment variable, or programs installed with --user 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.

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

Install the required tools

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

• Linux
• macOS
• Windows

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

Install west

First, install west using pip3:

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

Important

You need to run west update any time zephyr/west.yml changes. This command keeps Modules (External projects) in the zephyrproject folder in sync with the code in the zephyr repository, so they work correctly together.

Some examples when west update is needed are: whenever you pull the zephyr repository, switch branches in it, or perform a git bisect inside of it.

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. From the zephyrproject 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[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).

• 3rd Party Toolchains
  • GNU ARM Embedded
  • Crosstool-NG
• Other Cross Compilers
• Host Toolchains
• Custom CMake Toolchains

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. Additional information about building applications can be found in the Building an Application section.

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:

   west build -b reel_board samples/hello_world
   

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

# From the root of the zephyr repository
west build -b qemu_x86 samples/hello_world
west build -t 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.

# From the root of the zephyr repository
west build -b native_posix samples/hello_world

Next, run the application.

west build -t 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]

(1, 2) 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.