Follow this guide to set up a Zephyr <introducing_zephyr>
development environment on your system, and then build and run a sample application.
Tip
Need help with something? See help
.
Follow one of the following guides for your host operating system.
Linux <installation_linux.rst> macOS <installation_mac.rst> Windows <installation_win.rst>
Zephyr's multi-purpose west
tool lets you easily get the Zephyr project source code, instead of manually cloning the Zephyr repos along with west itself.
Warning
It's possible to use Zephyr without installing west, but you have to really know what you are doing <no-west>
.
First, install the west
binary and bootstrapper:
# Linux
pip3 install --user west
# macOS and Windows
pip3 install west
Note
See gs_python_deps
for additional clarfication on using the --user
switch.
Warning
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 PATH
. You can check which west
is being executed by running:
west --version
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
Note
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 working directory.
Note
If you had previously cloned the zephyr repository manually using Git, create an empty enclosing folder (for example zephyrproject/
), and move the cloned repository into it. From the enclosing folder run:
west init -l zephyr/ west update
The
-l <path to zephyr>
parameter instructswest
to use an existing local copy instead of cloning a remote repository. This will create a full Zephyr installation (see below).
Running west init
will clone west itself into ./.west/west
and 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 west-multi-repo
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.
Warning
Don't clone Zephyr to 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.
Next, install additional Python packages required by Zephyr in a shell or cmd.exe
prompt:
# Linux
pip3 install --user -r zephyr/scripts/requirements.txt
# macOS and Windows
pip3 install -r zephyr/scripts/requirements.txt
Some notes on pip's --user
option:
- Installing with
--user
is 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/bin
is at the front of your PATH environment variable, otherwise installed packages won't be found. - On macOS, Homebrew disables the
--user
flag1. - On Windows using
cmd.exe
, although it's possible to use the--user
flag, it makes it harder for the command prompt to find executables installed by pip.
Note
On Linux, you can skip this step if you installed the Zephyr SDK
<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 ZEPHYR_TOOLCHAIN_VARIANT=host
for gcc or ZEPHYR_TOOLCHAIN_VARIANT=llvm
for clang.
If you want, you can use the SDK host tools (such as OpenOCD) with a different toolchain by keeping the ZEPHYR_SDK_INSTALL_DIR
environment variable set to the Zephyr SDK installation directory, while setting ZEPHYR_TOOLCHAIN_VARIANT
appropriately for a non-SDK toolchain.
Zephyr binaries are compiled using software called a toolchain. You need to install and configure a toolchain to develop Zephyr applications2.
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 file system).
Note
In previous releases of Zephyr, the ZEPHYR_TOOLCHAIN_VARIANT
variable was called ZEPHYR_GCC_VARIANT
.
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 <boards>
if you are unsure about what choice to use.
toolchain_3rd_party_x_compilers.rst toolchain_other_x_compilers.rst toolchain_custom_cmake.rst
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 export
lines 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.sh
(Linux, macOS) and zephyr-env.cmd
(Windows), which you will learn about in the next step.
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.
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.
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 west
.
Follow these steps to build the hello_world
sample application provided with Zephyr.
As mentioned earlier, Zephyr's build system is based on CMake <application>
. You can build an application either by using cmake
directly or by using west <west>
, Zephyr's meta-tool that is also used to manage the repositories <west-multi-repo>
. You can find additional information about west's build capabilities in west-build-flash-debug
.
Zephyr applications have to be configured and built to run on some hardware configuration, which is called a "board"3. 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 boards
for more information, or use the usage
build target from an initialized build directory to get a list.
Note
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:
cd zephyrproject/zephyr
Set up your build environment:
# On Linux/macOS source zephyr-env.sh # On Windows zephyr-env.cmd
Build the Hello World sample for the
reel_board
:On Linux/macOS you can also use
cmake
to build withmake
instead ofninja
:
The main build products are in samples/hello_world/build/zephyr
. The final application binary in ELF format is named zephyr.elf
by default. Other binary formats and byproducts such as disassembly and map files will be present depending on the target and build system configuration.
Other sample projects demonstrating Zephyr's features are located in :zephyr_file:`samples and are documented in :ref:`samples-and-demos.
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.
See application_run
in the Application Development Primer and the documentation provided with your board at boards
for additional details if you get an error.
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:
To exit, type Ctrl-a
, then x
.
Use the qemu_cortex_m3
board configuration to run on an emulated Arm Cortex-M3.
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
section on host dependencies for more information.
To compile and run Hello World in this way, type:
and then:
# 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
document for more information.
This executable can be instrumented using standard tools, such as gdb or valgrind.
Footnotes
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
.↩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.↩