Library / SDK
oxidecomputer/hubris avatar
oxidecomputer/hubris

hubris leaves one layout question to judgement and admits images may not match across platforms

A lightweight, memory-protected, message-passing kernel for deeply embedded systems.

3,653 stars243 forksRustMPL-2.0

At a glance

What is it?
Oxide Computer’s microcontroller operating environment, built by a Cargo extension called `xtask` because `cargo build` is considered too inflexible, and developed on Linux and Windows as co-equal first-tier platforms despite linker behaviour that can produce different images from the same source. The root manifest, the tag names and the contributor guide each say something the documentation does not smooth over.
Who is it for?
Hubris is worth reading if you build firmware for Oxide hardware or want to see what a memory-protected message-passing kernel looks like when the parts are named by convention instead of by framework: `drv/SYSTEM-DEVICE`, `sys/kern`, `sys/abi`, `sys/userlib`. Three things to settle first.
Can I use it commercially?
Yes, with conditions. MPL-2.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • oxidecomputer/hubris3,653 ★ · +35
Star history
Repository2026-09-242026-11-15
oxidecomputer/hubris3.6k3.7k

35 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

default-members is empty, which is why cargo build is off the table

The root `Cargo.toml` declares seven member globs, `build/*`, `sys/*`, `lib/*`, `app/*`, `task/*`, `drv/*` and `test/*`, and then sets `default-members = []`. A bare `cargo build` at the root therefore has nothing to select, which is the mechanical counterpart of the README's statement that the project does not use `cargo build` or `cargo run` because they are too inflexible for a complex multi-architecture build. Builds go through `xtask`, a Cargo extension that namespaces the custom commands: `cargo xtask dist TOMLFILE` produces a distribution image, with eight board specific invocations given from the stm32f4-discovery through the Gemini bringup board. Two directories the navigation assigns a job to, `idl/` for Idol interface definitions and `chips/` for peripheral definitions, are not among the seven member globs.

The same source does not produce the same image on every platform

Linux and Windows are both first-tier platforms for building, and the reason given is an inconsistency in linker behavior across platforms. The consequence is stated without hedging: images may not match across platforms, so the README suggests choosing one as your official build platform for producing blessed images. macOS and Illumos are both used as informal build platforms by Oxide employees, though they are not currently tested in CI. Oxide blessed images are produced on Linux. So the project has two supported build hosts, no guarantee that a binary from one matches the other, two more hosts used by its own developers that CI never touches, and a single blessed platform on top of that. Any comparison of Hubris artifacts across machines needs that caveat attached to it.

The task versus driver line is left to judgement

The navigation section is precise about drivers and vague about everything else. The convention is written down: `drv/SYSTEM-DEVICE` is the driver for `DEVICE` on `SYSTEM`, where `SYSTEM` is usually an SoC name, and `drv/SYSTEM-DEVICE-server` is the server binary crate for the same device. `drv/` holds both simple driver library crates and full server crates. Then `task/` holds reusable tasks that are not drivers, and the boundary is given up on: the distinction between things that live in `task` versus `drv/something-server` is fuzzy, and the file says to use your judgement. A naming convention that resolves to a system, a device and a role for drivers, and to nothing at all for tasks, is a real cost when you are looking for the right crate to reuse.

The debugger has to be installed from another directory

The Hubris debugger is Humility, and it is installed with a command that the README asks you to run verbatim from a different directory: `cargo install --git https://github.com/oxidecomputer/humility.git --locked humility-bin`. The reason is given plainly, because `cargo install` interacts strangely with the `rust-toolchain.toml` file in the root of this repository. It also needs `cargo-readme` as a dependency, so there is a second install step. The same friction appears with the editor: the build system will not work with `rust-analyzer` out of the box, and the first of the two strategies offered is a shim, `cargo xtask rust-analyzer`, that pretends to be `rust-analyzer` and intercepts setup messages to apply configuration specific to a `(manifest,task)` tuple. The file stops after that first strategy.

Three ways to get OpenOCD, and one of them is discouraged

Windows has three documented routes to OpenOCD. You can build from source, or install with chocolatey, or install with scoop:

console
> choco install openocd
console
> scoop bucket add extras
> scoop install openocd

A note under them says the scoop install has proven problematic for some users, and to try `choco` or the source route instead. The same section links an ST-Link driver, since the ST-Link programmer needs it, and explains that PuTTY is what you want if your terminal does not support the serial link, with the framing that it is not necessary to build and run Hubris for that. Elsewhere the prerequisites are libusb and libftdi1 from the system package manager, plus `arm-none-eabi-gdb` for debugging, where macOS users are pointed at a cask of the official ARM binaries.

The newest releases are two branches deep, and the patch landed last

The three newest releases are all SP releases and all carry the same `all-sp-` prefix: 1.81.0, 1.80.0 and 1.79.1. Their dates are out of order. 1.80.0 was published on 2026-09-17 at 22:26. 1.81.0 followed on 2026-09-18 at 16:57. 1.79.1, the patch on the older line, was published last, on 2026-09-18 at 21:17, about four hours after 1.81.0. So the recent history is not a straight march upward: a maintenance release from the previous line went out after the newer feature line, and the last push to `master` is dated 2026-10-03. Anyone tracking Hubris by version needs to decide which line they are on before assuming a tag order means anything.

The readme is a template, and boards/ never appears in the navigation

The repository root holds `README.mkdn` and `FAQ.mkdn` rather than a rendered `README.md`, alongside `.licenserc.yaml`, `.rustfmt.toml`, `rust-toolchain.toml`, `CODEOWNERS`, `CONTRIBUTING.md`, `brussels.toml` and `LICENSE.txt`. The navigation section accounts for twelve directories, and one in the tree is not among them: `boards/` is never explained. The license situation is unremarkable, MPL-2.0 in the metadata and `LICENSE.txt` in the root. The release profile is where the hardware shows up: `opt-level = "z"`, `codegen-units = 1`, `lto = true`, and `debug = 2`, kept because symbols are nice and they don't increase the size on Flash. The dev profile takes `opt-level = 1`, since no optimizations was just too painful in terms of flash size.

Editorial conclusion

Hubris is worth reading if you build firmware for Oxide hardware or want to see what a memory-protected message-passing kernel looks like when the parts are named by convention instead of by framework: `drv/SYSTEM-DEVICE`, `sys/kern`, `sys/abi`, `sys/userlib`. Three things to settle first. The same source can produce different images on Linux and Windows because of linker behaviour, so choose one build platform and stick to it, and remember that macOS and Illumos are not covered by CI. The debugger cannot be installed from inside the repository, because `rust-toolchain.toml` interferes with `cargo install`. And the newest releases are two branches deep, so pin a tag deliberately: the patch release of the older line was published after both newer ones. The project is MPL-2.0 licensed and its documentation is Asciidoc rendered through GitHub pages.

Frequently asked questions

Why does hubris not use cargo build?

The README says `cargo build` and `cargo run` are too inflexible for a complex multi-architecture build, and the root Cargo.toml sets `default-members = []`, so the seven member globs covering `build/*`, `sys/*`, `lib/*`, `app/*`, `task/*`, `drv/*` and `test/*` have to be selected explicitly. Builds go through a Cargo extension called `xtask`.

How do I build a hubris image?

With `cargo xtask dist TOMLFILE`, which builds a distribution image for the application described by the TOML file. Eight examples are given, from `cargo xtask dist app/demo-stm32f4-discovery/app.toml` for the stm32f4-discovery board through `cargo xtask dist app/gemini-bu/app.toml` for the Gemini bringup board. To build a single task while iterating, use `cargo xtask build` instead.

Which platforms does hubris support for building?

Linux and Windows are the first-tier platforms. Because of an inconsistency in linker behavior across platforms, images may not match between them, so the README suggests choosing one as the official build platform for blessed images. macOS and Illumos are used informally and are not tested in CI, and Oxide blessed images are produced on Linux.

How is the hubris debugger installed?

Humility is installed with `cargo install --git https://github.com/oxidecomputer/humility.git --locked humility-bin`, which requires `cargo install cargo-readme` as a dependency. The README warns that `cargo install` interacts strangely with the `rust-toolchain.toml` in the repository root, so that command must be run verbatim from a different directory.

How do I install OpenOCD on Windows for hubris?

Three routes are offered: from source via openocd.org, with `choco install openocd`, or with `scoop bucket add extras` followed by `scoop install openocd`. The file notes that the scoop install has proven problematic for some users and suggests choco or source instead, and it links an ST-Link driver for the ST-Link programmer.

Official sources

  1. Issues
  2. License: MPL-2.0
  3. oxidecomputer/hubris on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/oxidecomputer-hubris.svg)](https://hysenlabs.com/projects/oxidecomputer-hubris)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/oxidecomputer-hubris.svg)](https://hysenlabs.com/projects/oxidecomputer-hubris)

Was this useful?