Embox wants to run Qt on an STM32, and configuration is a make target

The achievements list is the argument for the whole idea

Embox is described as a configurable RTOS designed for resource constrained and embedded systems, and its main idea is stated as one sentence: use Linux software without Linux.

The proof is offered as a list rather than a claim, and the list is the reason to look at this project. A VoIP phone on an STM32F7Discovery board based on the PJSIP project. Qt running on STM32F7Discovery. OpenCV on an STM32F769i board. Mesa3d. Quake3. SSHD based on the Dropbear project. zeromq and qpid.

A programming language list follows: Python, Lisp, Java through phoneme, TCL, Ruby, Lua, JS and Scheme.

Quake3 on a microcontroller is the item that makes people read the rest, and it is also the item that needs context. These are ported and constrained, not comfortable. The value claim is not that Qt is pleasant on an STM32, it is that a codebase written against Qt, POSIX sockets and Dropbear style SSH can be rebuilt on hardware it was never written for, without rewriting the application.

The feature list that supports this is a POSIX-compliant system with C++ support, file systems including FAT and ext2/3/4, TCP/IP with BSD sockets over UDP, HTTP, ARP, NTP and ICMP, Unix-like shell utilities such as ls, cat and mount, and cross platform support across ARM, MIPS, x86, RISC-V, Microblaze, SPARC, PowerPC and E2K, with STM32, i.MX6 and Raspberry Pi named as popular platforms.

So this is not a bare metal kernel. It is a POSIX userspace on a microcontroller, which is a different product from FreeRTOS or Zephyr and closer to what uClinux did.

Two ways to select a template, and they differ in rebuild cost

Because Embox is highly configurable, the README says it is necessary to specify modules to be built and params for them, and offers two ways to set up a current config.

The first is a make target:

$ make confload-x86/qemu

The second is a script:

$ ./confset x86/qemu

The difference is where files go, and the README explains both. With `make confload-<template>`, files from the template's folder are copied into a `./conf` folder, and you can modify them there.

With `./confset <template>`, files are copied into `./work/<template>/conf` and a link `./conf` is created pointing at it. The stated benefit is that this suits quick switching between templates because full rebuilds are avoided, and that working conf settings are retained when you switch between, for example, a real target and qemu and back again. The stated cost is more SSD or HDD usage, dependent on the number of parallel projects.

That is the whole configuration story and it is worth internalising before you start. `confload` is copy in, so your edits are in a single shared `./conf` and switching templates means overwriting them. `confset` is link to a per template directory, so each template keeps its own configuration and switching is a relink.

If you are developing one target, use `confload`. If you are bouncing between a board and an emulator, use `confset`, and accept the disk usage.

To see what is available, `make confload` with no template lists them. The README suggests starting with a qemu template, `x86/qemu` for x86, and notes that there is no autocomplete when you type only part of the name.

The repository layout explains the module system: a `templates/` directory holds the configurations, `mk/` holds the build machinery, `platform/` the architecture and board support, `src/` the OS source, `third-party/` the ported software, `board_config/`, `project/` and `scripts/` for the QEMU and Docker helpers.

Getting to an embox prompt in QEMU

The environment requirements are modest: `gcc` and `make`, plus a cross compiler for the target platform if you are not on x86.

Per distribution install lines are given, and the Debian one is the one most people will use:

$ sudo apt-get install build-essential gcc-multilib curl libmpc-dev python3 python-is-python3

Arch uses `sudo pacman -S make gcc-multilib cpio qemu` plus `yay -S python2-bin`, Fedora uses `sudo dnf install make gcc cpio qemu patch curl python`, and macOS needs Homebrew with `brew install i686-elf-binutils i686-elf-gcc awk cpio qemu python`, plus a separate `brew install --cask gcc-arm-embedded` on Intel Macs.

Note the `python-is-python3` package on Debian and `python2-bin` on Arch. Those are compatibility shims, and their presence tells you the build scripts call a bare `python` and have not been fully modernised.

There is a Docker route for any system with Docker, via a script pair:

$ ./scripts/docker/docker_start.sh
$ . ./scripts/docker/docker_rc.sh

Build steps are clone, configure, make:

$ git clone https://github.com/embox/embox.git embox
$ cd embox
$ make

To run under QEMU, the README gives one script:

$ sudo ./scripts/qemu/auto_qemu

`sudo` is required because a TUN/TAP device has to be set up to emulate networking. That is why the Debian and Arch package lists both include qemu, and why the ping address in the example is `10.0.2.16`, the standard QEMU user network guest address. You land at an `embox>` prompt, `help` lists commands, and you can connect over telnet. To exit, Ctrl+A then X.

Running QEMU needs root on your machine every time, which is the sharpest operational edge in the whole getting started path.

Debugging attaches gdb through the same script

The same script accepts QEMU flags, which is how debugging is set up:

$ sudo ./scripts/qemu/auto_qemu -s -S -machine accel=tcg

`-s` opens the gdb server port, `-S` halts the CPU at startup so the image does not run away before a debugger attaches, and `accel=tcg` selects software CPU emulation rather than hardware acceleration, which is what you want when you are stepping through kernel code.

Then in a second terminal:

$ gdb ./build/base/bin/embox
...
(gdb) target extended-remote :1234
(gdb) continue

The binary path is worth noting, since it tells you where artefacts land: `build/base/bin/embox`.

Once connected, Ctrl+C interrupts whatever is running and shows the current thread's stack through `backtrace`, and you can set breakpoints by function name or by `file:line`.

For other architectures the README says a cross compiler is needed, then the same three commands with the architecture substituted:

make confload-<arch>/qemu
make
sudo ./scripts/qemu/auto_qemu

The supported list here is x86, ARM, Microblaze, SPARC, PPC and MIPS, which is narrower than the cross platform line in the key features, where RISC-V, PowerPC and E2K also appear. The narrower list is the one tied to QEMU templates specifically, so treat the two lists as different scopes.

Networking under QEMU is stated as supported on x86, ARM, MIPS and Microblaze, which is a narrower set again.

The Makefile guards GNU make assumptions and forces serial builds

The root Makefile is short and mostly about constraints, which is worth reading before you debug a build problem.

It states its own purpose: it just has to set up proper make flags and invoke `mk/main.mk`, which performs the real work.

The first thing it does is refuse to work on old Make. It requires GNU Make 3.81 or above, because `.FEATURES` was introduced in exactly that version, and the check uses `$(origin.FEATURES)` to see whether the variable came from Make itself rather than from the environment.

Then it turns on strictness. `--no-builtin-rules` and `--no-builtin-variables` disable Make's implicit rules and built in variables, and `--warn-undefined-variables` reports uses of undefined ones. Those flags are why the build fails loudly on a typo instead of silently expanding to nothing.

Two workarounds are commented in the source. It exports an empty `GNUMAKEFLAGS` to avoid warnings that GNU Make 4.4 would produce alongside `--no-builtin-variables`, and it exports an empty `PS1` so that dollar signs in your shell prompt do not trigger bogus undefined variable warnings.

Stack size is raised to 65536 with `ulimit -s` before recursing, with a separate branch for Darwin because macOS caps the stack limit differently. That is a build time workaround for a host limitation, and it explains the `ulimit` line on any system where your shell has a lower default.

Finally `.NOTPARALLEL` is set with the comment that it forces multiple targets listed on the command line to run independently even under `-j`, so that `make -j clean all` behaves. In other words, Make serializes these goals by default, which is worth knowing before you try to speed up the build.

Licence is BSD-2-Clause with a COPYRIGHT file. The repository is not archived, the last push was on 2026-10-13, and releases are v0.7.2 on 2026-09-01, v0.7.1 on 2026-04-20 and v0.7.0 on 2025-10-23, so it is pre 1.0 and still moving.

Editorial conclusion

Adopt Embox if you are bringing POSIX application code onto a microcontroller with real memory constraints and want a Linux shaped API without a Linux kernel, and if you are prepared to configure the system by selecting modules rather than writing a board support package from scratch. Do not adopt it if you need a commercially supported RTOS with a defined support contract, since this is a research and community project maintained through mailing lists, Telegram and a wiki. Verify first that a template exists for your architecture and board, and read the confload versus confset choice before you start, because it determines whether switching targets costs a full rebuild.

Frequently asked questions

Official sources

1. embox/embox on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases