Getting Started Guide

Use this guide to get started with your Zephyr development.

Checking Out the Source Code Anonymously

The Zephyr source code is hosted in a GitHub repo that supports anonymous cloning via git. There are scripts and such in this repo that you’ll need to set up your development environment, and we’ll be using Git to get this repo. (If you don’t have Git installed, see the beginning of the OS-specific instructions below for help.)

We’ll begin by using Git to clone the repository anonymously. Enter:

# On Linux/macOS
cd ~
# On Windows
cd %userprofile%

git clone https://github.com/zephyrproject-rtos/zephyr.git

You have successfully checked out a copy of the source code to your local machine in the ~/zephyr folder.

A brief note on the Zephyr build system

The Zephyr project uses CMake as a tool for managing the building of the project. CMake is able to generate build files in different formats (also known as “generators”), and the following ones are currently supported by Zephyr:

• make: Supported on UNIX-like platforms (Linux, macOS).
• ninja: Supported on all platforms.

Most of the examples in the Zephyr documentation use ninja as a build tool but you should be able to use any generator on any of the examples listed.

Set Up the Development Environment

The Zephyr project supports these operating systems:

• Linux
• macOS
• Microsoft Windows

Use the following procedures to create a new development environment.

• Development Environment Setup on Linux
• Development Environment Setup on macOS
• Development Environment Setup on Windows

Building and Running an Application

Using the ‘Hello World’ sample application as a base model, the following section will describe the pieces necessary for creating a Zephyr application.

The processes to build and run a Zephyr application are the same across operating systems. Nevertheless, the commands needed do differ from one OS to the next. The following sections contain the commands used in a Linux development environment. If you are using macOS please use the appropriate commands for your OS.

Building a Sample Application

To build an example application follow these steps:

1. Make sure your environment is setup by exporting the following environment variables. When using the Zephyr SDK on Linux for example, type:

   # On Linux/macOS
   export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
   export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
   # On Windows
   set ZEPHYR_TOOLCHAIN_VARIANT=zephyr
   set ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
   

   Note

   In previous releases of Zephyr, the ZEPHYR_TOOLCHAIN_VARIANT variable was called ZEPHYR_GCC_VARIANT.

2. Navigate to the main project directory:

   cd zephyr
   

3. Set the project environment variables:

   # On Linux/macOS
   source zephyr-env.sh
   # On Windows
   zephyr-env.cmd
   

4. Build the Hello World example for the arduino_101 board, enter:

   # On Linux/macOS
   cd $ZEPHYR_BASE/samples/hello_world
   mkdir -p build/arduino_101 && cd build/arduino_101
   
   # On Windows
   cd %ZEPHYR_BASE%\samples\hello_world
   mkdir build\arduino_101 & cd build\arduino_101
   
   # Use cmake to configure a Ninja-based build system:
   cmake -GNinja -DBOARD=arduino_101 ../..
   
   # Now run ninja on the generated build system:
   ninja
   

   On Linux/macOS you can also build with make instead of ninja:

   cd $ZEPHYR_BASE/samples/hello_world
   mkdir -p build/arduino_101 && cd build/arduino_101
   
   # Use cmake to configure a Make-based build system:
   cmake -DBOARD=arduino_101 ../..
   
   # Now run make on the generated build system:
   make
   

You can build for a different board by defining the variable BOARD with another of the supported boards, for example:

# On Linux/macOS
cd $ZEPHYR_BASE/samples/hello_world
mkdir -p build/arduino_due && cd build/arduino_due

# On Windows
cd %ZEPHYR_BASE%\samples\hello_world
mkdir build\arduino_due & cd build\arduino_due

# Use cmake to configure a Ninja-based build system:
cmake -GNinja -DBOARD=arduino_due ../..

# Now run ninja on the generated build system:
ninja

For further information on the supported boards go see here. Alternatively, run the following command to obtain a list of the supported boards:

ninja usage

Sample projects for different features of the project are available at at ZEPHYR_BASE/samples. After building an application successfully, the results can be found in the directory where cmake was invoked.

The ELF binaries generated by the build system are named by default zephyr.elf. This value can be overridden in the application configuration The build system generates different names for different use cases depending on the hardware and boards used.

Building without the Zephyr SDK

The Zephyr SDK is provided for convenience and ease of use. It provides cross-compilers for all ports supported by the Zephyr OS and does not require any extra flags when building applications or running tests.

In addition to cross-compilers, the Zephyr SDK also provides prebuilt host tools. To use the SDK host tools alongside a custom or 3rd party cross-compiler, keep the ZEPHYR_SDK_INSTALL_DIR environment variable set to the Zephyr SDK installation directory.

To build without the Zephyr SDK’s prebuilt host tools, the ZEPHYR_SDK_INSTALL_DIR environment variable must be unset, the host tools must be built and added to path, and a 3rd party cross-compiler must be installed.

1. Follow the steps below to build without the Zephyr SDK:

   # On Linux/macOS
   unset ZEPHYR_TOOLCHAIN_VARIANT
   unset ZEPHYR_SDK_INSTALL_DIR
   cd <zephyr git clone location>
   source zephyr-env.sh
   # On Windows
   set ZEPHYR_TOOLCHAIN_VARIANT=
   set ZEPHYR_SDK_INSTALL_DIR=
   cd <zephyr git clone location>
   zephyr-env.cmd
   

2. On UNIX platforms, Build Kconfig in $ZEPHYR_BASE/build and add it to path

   cd $ZEPHYR_BASE
   mkdir build && cd build
   cmake $ZEPHYR_BASE/scripts
   make
   echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
   source $ZEPHYR_BASE/zephyr-env.sh
   

   Note

   You only need to do this once after cloning the git repository.

Now that the host tools are installed, a 3rd party cross compiler must be installed. See Using Custom and 3rd Party Cross Compilers for details.

Using Custom and 3rd Party Cross Compilers

To use a 3rd party cross compiler that is not provided by the Zephyr SDK, follow the steps below. It is possible to use a 3rd party cross compiler and still use the Zephyr SDK’s host tools. See Building without the Zephyr SDK for details.

1. We will use the GCC ARM Embedded compiler for this example, download the package suitable for your operating system from the GCC ARM Embedded website and extract it on your file system. This example assumes the compiler was extracted to: <user folder>/gcc-arm-none-eabi-5_3-2016q1/.

2. Build the example Hello World project, enter:

   # On Linux/macOS
   export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
   export ZEPHYR_TOOLCHAIN_VARIANT=gccarmemb
   # On Windows
   set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\"
   set ZEPHYR_TOOLCHAIN_VARIANT=gccarmemb
   

   # On Linux/macOS
   cd $ZEPHYR_BASE/samples/hello_world
   mkdir build && cd build
   
   # On Windows
   cd %ZEPHYR_BASE%\samples\hello_world
   mkdir build & cd build
   
   # Use cmake to configure a Ninja-based build system:
   cmake -GNinja -DBOARD=arduino_due ..
   
   # Now run ninja on the generated build system:
   ninja
   

Running a Sample Application in QEMU

To perform rapid testing of an application in the development environment you can use the QEMU emulation board configuration available for both X86 and ARM Cortex-M3 architectures. This can be easily accomplished by calling a special target when building an application that invokes QEMU once the build process is completed.

To run an application using the x86 emulation board configuration (qemu_x86), type:

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 the qemu emulator, press Ctrl-a, followed by x.

Use the qemu_cortex_m3 board configuration to test the ARM build.

QEMU is not supported on all boards and SoCs. When developing for a specific hardware target you should always test on the actual hardware and should not rely on testing in the QEMU emulation environment only.

Running a Sample Application natively (POSIX OS)

It is also possible to compile some of the sample and test applications to run as native process on a POSIX OS (e.g. Linux). To be able to do this, remember to have installed the 32 bit libC if your OS is natively 64bit.

To compile and run an application in this way, type:

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

and then:

ninja run
# or just:
zephyr/zephyr.exe
# Press Ctrl+C to exit

This executable can be instrumented like any other Linux process. For ex. with gdb or valgrind. Note that the native port is currently only tested in Linux.