XBOOT, an extensible bootloader with a Lua application engine

A bootloader that is also the application runtime

XBOOT describes itself as an extensible bootloader for embedded systems with an application engine, and the tagline is write once, run everywhere. The README makes the double role explicit: it is both an embedded system bootloader and a SoC application software execution engine, working without a complex operating system, with the app executing directly at power up.

The problem it names is a familiar one in embedded work. Driving a GPIO means reading the SoC datasheet carefully, and every time the MCU changes, the work starts over. Building a modern UI with animations is close to impossible on a bare-metal target. Protocol stacks are described as hard to read and harder to write. And porting a virtual machine to your own board is, in the project's words, a long row of difficulties.

The answer XBOOT proposes is to absorb those problems into a reusable platform. The listed capabilities cover file systems, a Lua virtual machine, many protocol stacks, a graphics library with vector fonts, a modern GUI with animations, multi-platform support, bus drivers such as UART, I2C and SPI, and device drivers including GPIO, PWM, IRQ, CLK, LED, BUZZER, VIBRATOR, WATCHDOG, RNG, FRAMEBUFFER and RTC.

The point of the design is that the application layer does not change when the hardware does. Applications are written against a hardware abstraction interface, so a Lua app written for one board is expected to run on another.

Lua as the application layer, with high level hardware APIs

The application engine is the Lua virtual machine. Applications are written in Lua, and the README notes that the Lua support includes high-level APIs that can operate the hardware abstraction interface directly, so a script can reach a device driver without writing C.

That is the load-bearing decision in the whole project. A C-only approach would mean recompiling and reflashing for every behaviour change, and a conventional embedded OS would mean porting and maintaining an operating system before you can ship anything. Lua gives you a scripting layer on top of the abstraction interface, so the script stays the same while the board underneath changes.

The rest of the stack is arranged to support that. File systems are supported, which is what lets an application load data and configuration. A graphics library with vector fonts and a modern GUI with animations are included, which is the piece that makes an embedded product look like a product rather than a serial console. Bus drivers and the long list of device drivers cover the hardware access that scripts and C code share.

The repository carries examples/ directories for games, graphics, hardware and timers, and the README shows a sandbox running the 2048 game under a Linux sandbox build, which is a good indication of what the GUI layer looks like in practice.

Two make variables decide what you are building

Building the source is controlled by exactly two variables that you pass on the make command line. CROSS_COMPILE specifies the cross toolchain, and PLATFORM specifies the hardware platform, which is itself made of two parts, an arch and a mach.

For the Realview platform under the qemu-system-arm emulator, the documented sequence is:

make clean
make CROSS_COMPILE=/path/to/arm-none-linux-gnueabihf- PLATFORM=arm32-realview

The cross toolchain prefix is the whole configuration surface for the compiler, which means the project expects you to have a toolchain that matches the target architecture, and the README links a cross toolchain download hosted on Baidu Pan for that purpose. A separate link points to an Eclipse integrated development environment integration.

The platform naming tells you what is expected of the port layer. arm32-realview is a 32-bit ARM board, and the topics of the repository name SoC families the project supports, including Allwinner, Freescale, MediaTek, Rockchip and Samsung.

This is the part of XBOOT that has real cost attached to it. The value of a portable bootloader is that you can move your application to a new SoC without rewriting it, but the bootloader itself still has to be ported to that SoC, and each port means a platform entry and a matching cross toolchain.

The x64-sandbox lets you try the stack on a desktop

The second documented build target is an x64 sandbox on Linux, and it is the pragmatic way to evaluate the project before touching a board. The sandbox depends on the SDL2 library, so the SDL2 development package has to be installed first. On Ubuntu the README gives:

sudo apt-get install libsdl2-dev

And the build itself sets an empty cross toolchain, because the target is the host:

make clean
make CROSS_COMPILE="" PLATFORM=x64-sandbox

The empty CROSS_COMPILE is the detail to notice. The same two variables drive both builds, and an empty value tells the build system to use the native toolchain. A developer can therefore run the Lua runtime, the graphics library and the GUI on a Linux desktop, write an application, and only then worry about the board.

The Makefile at the top of the repository is thin, since all the real work happens in src/, and the top level also holds an examples/ directory with games, graphics, hardware and timer examples, plus developments/ and docs/ directories and the CREDITS and MAINTAINERS files.

An old tag, a repository that still moves

The release history here is unusual, and anyone evaluating the project needs to know about it. The only listed release is v2.0.1, dated 2017-09-23. The last push to the repository was on 2026-07-07, which is nearly nine years later.

That gap means two things. There is a substantial amount of work in the tree that is not reachable through a tagged release, and anyone installing the project from a release would be taking code from 2017. The practical advice is to build from the default branch, main, and to read the commit history for the platform you care about.

The repository is MIT licensed, which is the permissive choice for a bootloader that vendors want to include in a product image, and the licence field on the repository confirms it. There is also a separate LICENSES/ directory, which in this kind of project is where per-component licence information lives for the code that came from elsewhere.

Documentation is split between the project site at xboot.org and a documentation repository hosted at xboot.github.io/xboot, and the source of truth for a port is in the tree itself rather than in a long wiki. The project also runs a Tencent QQ discussion group, listed in the README with a membership figure of 2000 people, which tells you where the practical knowledge lives for anyone porting XBOOT to a new SoC.

Where a bootloader with a script layer is the wrong answer

XBOOT's appeal depends on a specific profile: a device with a fixed set of peripherals, an interface that benefits from being written in a scripting language, and a team willing to own the board support. Outside that profile it is a lot of work for little return.

The clearest case where it is the wrong tool is anything with demanding networking or real-time requirements. The README lists protocol stacks among the supported features but gives no detail about which ones or what guarantees they carry, and a project that needs a maintained TCP/IP stack, TLS, a filesystem with hard latency bounds or a certified safety story will not find those guarantees in this repository. Building those pieces yourself on top of XBOOT is possible in principle and is a large project in practice.

The second case is the opposite one: a device with a commodity processor, where running Linux or a conventional RTOS costs nothing extra and gives you drivers, a process model and an application ecosystem that XBOOT cannot match. The XBOOT argument, once written, running everywhere, is strongest against that alternative precisely when the hardware is unusual and a standard OS port is unavailable.

The third case is timing. With the newest tag from 2017 and the work living in master, adopting XBOOT means tracking an unfrozen tree, and the platform list in the repository topics suggests how many SoC ports exist in total.

Editorial conclusion

XBOOT suits embedded engineers who want a small, scriptable interface on a specific SoC and who are prepared to own the board bring-up themselves, since it gives you a Lua virtual machine, drivers and a GUI in one image without an operating system underneath. It does not suit teams that need a mature network stack, real-time guarantees or an ecosystem of existing drivers and middleware. Before you commit, build the x64-sandbox target on a desktop to see the stack work, confirm your SoC is one of the supported platforms, and note that the last release tag is v2.0.1 from 2017 while the last push was on 2026-07-07, so you would be tracking master rather than a tagged release.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xboot/xboot on GitHub