Creating an application

Your first Zephyr application

Create a directory in your git working directory. Create the following two files.

In CMakeLists.txt:

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr)
project(my_zephyr_app)

target_sources(app PRIVATE src/main.c)

In src/main.c:

#include <stdio.h>

int main() {
    printf("Hello, world\n");
    return 0;
}

You also need to create a configuration file prj.conf. In our case, we do not want to configure anything, so it can be empty:

$ touch prj.conf

We will now build the application for our target. In this case, we will generate code for a PC using an Intel CPU in bare-board mode and emulate the PC using the QEMU emulator.

Provided that west is in your $PATH and that $ZEPHYR_BASE is properly set if needed, you should be able to build your application for the board qemu_x86:

$ west build -b qemu_x86

(if you do not use west, you can use the equivalent cmake -B build -DBOARD=qemu_x86 -GNinja && ninja -C build zephyr/zephyr.elf)

This builds zephyr/zephyr.elf into the build directory. You should ignore this directory in your .gitignore as its content should never be added to the git repository.

You can now run the application. You do not need to give the board again as it is remembered.

$ west build -t run
-- west build: running target run
[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: qemu32,+nx,+pae
SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
Booting from ROM..
*** Booting Zephyr OS build v3.2.0-rc2-37-gd9f327fb8434  ***
Hello, world

(without west: ninja -C build run)

Congratulations: you just ran your first Zephyr application. You can quit qemu with ctrl-a x (control key + a, then x), or simply kill the qemu process with ctrl-c.

Adding a shell

Zephyr comes with an interactive shell. We want to add it to our project.

Run west build -t menuconfig (or ninja -C build menuconfig) and look for the SHELL option. You can find it under "Sub Systems and OS Services / Shell". Activate the shell by pressing the space key (the box will be ticked). Also, activate the UART shell backend, so that the shell presents itself on the serial port.

You may want to disable the QEMU_ICOUNT option found in "Board Options" as it won't work nice with the shell. You do not need to change any other option. Leave menuconfig by pressing Q and saving the file.

You can now run the application again and use the interactive shell:

$ west build -t run
[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: qemu32,+nx,+pae
SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
Booting from ROM..
*** Booting Zephyr OS build v3.2.0-rc2-37-gd9f327fb8434  ***
Hello, world

uart:~$

You can now enter commands such as "help" at the prompt ("uart:~$ " by default). For the time being, only the "help" command is available, but we will add more commands.

Making the change persistent

The changes we made with menuconfig are stored in build/zephyr/.config using the Kconfig format. As soon as we remove the build directory, we will lose them.

Make the change persistent by putting some content into the prj.conf file at the top-level of your application:

CONFIG_SHELL=y
CONFIG_SHELL_PROMPT_UART="(zephyr) "

We have also changed the prompt. Let's rebuild the application from scratch:

$ rm -rf build
$ west build -t run -b qemu_x86
[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: qemu32,+nx,+pae
SeaBIOS (version zephyr-v1.0.0-0-g31d4e0e-dirty-20200714_234759-fv-az50-zephyr)
Booting from ROM..
*** Booting Zephyr OS build v3.2.0-rc2-37-gd9f327fb8434  ***
Hello, world

(Zephyr)

Do not forget to add prj.conf to git. Commit, then push.