erXos: An Operating System in ErlangAppendix DDependencies and Licenses
Contents
  1. 1Operating Systems from the Ground Up
  2. 2Microkernels and Capabilities
  3. 3Erlang and OTP
  4. 4History and Goals
  5. 5Design Overview of erXos
  6. 6Correct by Construction
  7. 7One Source for Every Fact
  8. 8The Kernel Interface and Fiasco
  9. 9Processes, Runtimes and Two-Level Scheduling
  10. 10Domains: A Wall Around Some Processes
  11. 11Authority and Security
  12. 12Memory and Budgets
  13. 13Native Programs, Pipes and POSIX-lite
  14. 14Files, Namespaces and Service Trees
  15. 15Devices and Drivers
  16. 16Storage and Updates
  17. 17The Network Stack
  18. 18WiFi
  19. 19Bluetooth
  20. 20The Command Shell and the UNIX Surface
  21. 21The Live Machine
  22. 22Displays, Windows and the Web
  23. 23Apps and Packages
  24. 24Startup, Configuration and Shutdown
  25. 25Checking the System
  26. AGlossary
  27. BReading the Design Documents
  28. CBuilding and Booting erXos
  29. DDependencies and Licenses
    1. D.1What a dependency must pay
    2. D.2Two ways in
    3. D.3The components
    4. D.4How licenses and notices travel
    5. Summary
    6. Where to read next
  30. ELineage

Appendix DDependencies and Licenses

erXos is a small amount of new code standing on a large amount of old code. Its Erlang runs on OTP, its native programs link musl, its kernel is Fiasco, its file system on /data is littlefs, and its widgets come from LVGL. Every image it packs carries files written by many people under many licenses, and each license asks something: keep this notice, mark that change, offer the source. A system that ships images has to answer those requests for every file, every time, without anyone keeping a list.

Code erXos changes lives in its tree, each directory keeping its license and copyright notices. Two things make the answer mechanical: a record of every imported file’s hash, so a changed file cannot hide, and a packer that refuses to put into an image any file whose origin and license it cannot name.

This appendix covers the rules a dependency must meet (D.1), the two ways outside code enters the build (D.2), the components and why each pays for itself (D.3), and how licenses and notices travel with every image (D.4). The authority is the dependency table of design.md, Dependencies.

D.1What a dependency must pay

A component erXos takes from outside must pay for itself: it saves more work, or buys more correctness, than it costs in size, review and license obligations. The project prefers mature, maintained components with a C or Erlang interface under a permissive license: ISC, BSD, MIT or Apache-2.0. A copyleft dependency needs explicit agreement; the Pi 4’s device tree is the one accepted (D.3.2). OFL-1.1 is allowed for font data only.

Tools and test data never enter an image the system ships.

D.2Two ways in

Outside code enters the build in one of two ways, and which one depends on whether erXos changes it.

Code erXos changes lives in the tree. OTP’s source in otp/, musl in musl/, the Fiasco parts in fiasco/, OpenSSL, littlefs, Monocypher, ctaes, the BLAKE3, ChaCha20 and SHA-256 cores and libmemdraw, among others, are ordinary directories of the repository, changed by ordinary commits. Upstream is not merged: erXos owns their fixes, and Fiasco’s upstream is reviewed each month for security fixes to backport. Beside each sits an ORIGIN.md, the import’s origin record: the repository, the release or commit, the archive’s SHA-256 and, for every file, its original hash and license (design-build.md, Sources and imports). LVGL is the one part of the system that is a git submodule instead, of erXos’s own fork, pinned by its gitlink, with its ORIGIN.md at display/lvgl/ORIGIN.md.

Code erXos uses unchanged is fetched. Everything else (the test oracles, the firmware, the device trees, LLVM’s runtime libraries) is pinned in deps.lock by URL, version and SHA-256, with its license, fetched by make fetch alone and built out of tree (Appendix C). The web client’s npm packages are pinned the same way, by the integrity hashes of web/pnpm-lock.yaml, with install scripts off.

Why two ways? A pristine copy in the tree is bytes nobody reads, and a fetched component with patches kept elsewhere hides the patches. Each way puts the bytes where the work on them happens.

D.3The components

The table has about sixty rows, in a few groups.

D.3.1The runtime and its libraries

ComponentLicenseWhy it pays
Erlang/OTP: ERTS and the shipped applications, with asmjit, PCRE2, zlib, zstd and Ryu insideApache-2.0; the parts inside under Zlib, BSD-3-Clause (PCRE2’s with its exception) and Apache-2.0The language, its runtime and decades of supervision, distribution and libraries; erXos is built around it (chapter 3). asmjit, the JIT’s assembler, is never in the system domain’s image.
muslMITA small, readable C library for every runtime and native program, whose seam under ERTS erXos owns (chapter 9).
OpenSSL 3.5Apache-2.0OTP’s crypto, ssl and ssh, and the vault’s key derivation and encryption; a long-term-support series. It never enters the system domain’s image.
LLVM libc++, libc++abi and compiler-rt builtinsApache-2.0 with the LLVM exceptionBeamAsm’s C++ runtime, and the compiler’s helper routines.

D.3.2The kernel and the boot

ComponentLicenseWhy it pays
Fiasco, with bootstrap, sigma0, l4sys and mkMIT, with exceptions belowThe kernel, an L4 microkernel with decades of use, behind erXos’s interface liberx (chapter 8).
stdarg.h, stdbool.h, stddef.h of the cross GCCGPL-3.0-or-later with the GCC Runtime Library ExceptionMacros and types Fiasco’s build includes; no GCC library is linked.
drivers-frst, its PL011 UART partMITbootstrap’s console while Fiasco starts.
libfdtBSD-2-Clause (dual GPL-2.0-or-later)Reading the device tree, the board’s description.
TF-A’s BL31 for the Pi 4BSD-3-ClauseThe firmware calls that start CPUs and end the machine.
Raspberry Pi firmwareBroadcom’s binary licenseStarts the board and loads the kernel.
The boards’ device trees, from LinuxPi 4 GPL-2.0; Pi 5 GPL-2.0 OR MITDescribe each board. The Pi 4’s is the one copyleft dependency the system accepts, shipped as a file of its own beside its edited source and Linux’s GPL-2.0 text.

What the system builds from Fiasco is MIT, with two files to note. Fiasco’s own kobject_rpc.h is GPL-2.0, and the tree holds instead erXos’s MIT replacement, written from a description by someone who never read the original. The kernel debugger’s jdb_object.cpp is GPL-2.0 too. Only a kernel built with the debugger compiles it, and the license rule takes it only in development builds. The images the website offers carry it and go out with a link to their source.

Fiasco’s imported tree does hold other GPL and LGPL files: about 150 in its kernel, bootstrap and build-system directories, and, beside sigma0 in l4re-core, one LGPL file and some 9,000 files of GCC’s C++ library, libstdc++, under GPL-3.0 with the GCC exception. No build compiles them. A build check fails if any file compiled or linked into the kernel, bootstrap or sigma0, headers included, has a license that is not permissive, apart from the three GCC headers and, in a kernel with the debugger, jdb_object.cpp.

D.3.3Storage, cryptography and small cores

ComponentLicenseWhy it pays
littlefsBSD-3-ClauseA small file system that survives a power cut, for /data and the vault, run as a NIF in the storage domain (chapter 16).
BLAKE3, the official C implementationApache-2.0 with the LLVM exceptionThe boot image’s hashes and the entropy generator’s mixing.
FreeBSD’s SHA-256 and ChaCha20BSD-2-Clause; public domainThe entropy generator and the C SHA-256 primitive.
Monocypher’s Ed25519BSD-2-ClauseA small verifier of update and package signatures, without OpenSSL in the system domain.
ctaesMITConstant-time AES, also without OpenSSL in the system domain.
Root certificatesnone needed: facts, not a creative workThe trust store of every HTTPS client.

Monocypher and ctaes show the cost side of the rule: OpenSSL would do their jobs, but in the trusted base a small library is cheaper to review.

D.3.4Display and type

ComponentLicenseWhy it pays
LVGL 9MIT; its fonts Inter’s, OFL-1.1The widget renderer, a program in the app’s own session (chapter 22).
Plan 9’s libmemdraw, from 9frontMITThe per-byte pixel primitives behind erx_memdraw, from the system whose draw protocol erXos speaks.
plan9port’s fixed fontspublic domainThe terminal’s glyphs.
InterOFL-1.1, font data onlyThe desktop theme’s type; the glyph files generated from it carry OFL-1.1, their generators BSD-2-Clause.
FreeTypethe FreeType License, chosen over its GPL-2.0 optionThe glyph step of the host program that rasterizes the theme’s type; it binds no image.

D.3.5The browser client, and rows for designed parts

React, under MIT, renders the browser client that tools/erx web serves, which is built; TypeScript and esbuild check and bundle it on the host. Other rows name a dependency for a part that is designed and not built. toybox, under 0BSD, with wak as its awk, is designed to provide the UNIX commands not written in Erlang (chapter 13). cowboy, cowlib and ranch, under ISC, are designed as the HTTP, WebSocket and TLS server of the web’s network front end. The Pi 4’s WiFi and Bluetooth chips run Cypress’s firmware, under binary licenses that allow only unmodified object code for Cypress chips; driving either radio on the board is designed (chapter 18, chapter 19).

D.3.6References that are translated, never linked

FreeBSD’s netinet, netinet6, net and cc are the source of the decisions erXos’s TCP/IP stack makes, redesigned as Erlang (chapter 17). None of their C is compiled into an image; the translation is erXos’s code and keeps the BSD notices of every file it derives from, per Erlang module and in erlang/apps/erx_net/NOTICE-freebsd. Two FreeBSD files are never translated: netinet/in_cksum.c, whose four-clause license keeps the advertising clause, and tcp_stacks/tailq_hash.c, which carries no license at all.

D.3.7Tools, oracles and a demo

Most rows never reach an image. They build the system or check it:

  • Host tools: LLVM, GNU make, QEMU, dtc, Ruby, Perl, Node.js and pnpm, a host OTP of the same release, fsimg (which writes the EROFS images), the TLA+ tools, CBMC and herdtools7’s herd7.
  • Oracles: stock OTP in an offline Linux container, musl’s libc-test, plan9port’s rc, libvterm and vttest for the terminal, 9front’s libdraw for the display, a FreeBSD guest for the commands that share FreeBSD’s names, and a FreeBSD test host for the network stack. Some are GPL, such as the Linux guests that test erXos’s F2FS; they run only as black boxes in a guest and are never linked.
  • A demo program, never part of the system: doomgeneric under GPL-2.0-or-later with Freedoom’s data file under BSD-3-Clause, as /bin/doom on the images the website offers. Its source is erXos’s fork, a submodule that no file of erXos’s tree comes from.
  • The website: v64 and xterm.js, the in-browser console.

An oracle pays for itself differently: it saves no code, but catches code that is wrong.

D.4How licenses and notices travel

Two mechanisms carry the conditions of every third-party license into what erXos ships, and neither depends on anyone keeping a list (design.md, Licenses and notices).

D.4.1Changed files say so

Apache-2.0, the license of OTP, and the Zlib license require a changed file to say it was changed. The origin record holds the hash of every file as imported, so make check compares each file under a directory with an ORIGIN.md against its row. A file that differs must carry erXos’s change notice in its header comment. A file added to an import must carry erXos’s own notice. A file the record lists cannot vanish unless the record names it as removed, with a reason. A changed file that cannot hold a comment, such as a regenerated .beam, is named in its ORIGIN.md instead.

Suppose a fix changes a C file of musl. Its hash no longer matches its row in musl/ORIGIN.md, so make check fails, naming the file, until its header carries the change notice. The rule covers every import whatever its license.

D.4.2Every image carries the notices of what it holds

Every file the packer puts into an image has a recorded origin and license. A file erXos wrote carries SPDX-License-Identifier: BSD-2-Clause. A file of an import is in its ORIGIN.md. A fetched artifact has its deps.lock entry. A generated file takes the origin of the inputs its build rule records. The packer learns what an image holds from three sources: the linker’s map of what each program links, the compiler’s dependency files, and its own list of the rest, such as BEAM files, data and the contents of each EROFS image. It fails on any file it cannot place.

From that closure it writes NOTICES, the file of every license and copyright notice an image holds, as system/NOTICES in the system image. Each distinct header comment once, under the files that carry it, with their license; then each license text once. A license that thousands of files share costs one copy. The design also puts the same NOTICES, with the firmware’s and device trees’ licenses, beside the boot image in each slot’s boot partition; that copy is designed and not built.

D.4.3One rule for which licenses a build takes

A permissive license enters every build. A license that is not permissive enters only through one closed table, LicenseCheck::TABLE in tools/lib/erx/license_check.rb, whose every row names one input: its exact license, where the build reads it and which kinds of build take it. The table has three rows:

  1. the three GCC headers Fiasco includes, in every build, since the GCC Runtime Library Exception lets code compiled with them go out under any terms;
  2. Doom’s archive, a demo program that is never part of the system, in development builds only;
  3. Fiasco’s jdb_object.cpp, in development builds only.

The design admits a few more files by name and place, outside every program and EROFS image: the Pi 4’s device tree, with its source beside it; the Raspberry Pi firmware in a board’s boot partition; and Cypress’s firmware files as data. Test images, never distributed, get an allowlist of their own for their test tools.

So a copyleft file that comes back into any other image fails the build, naming the file and its license. The only images that leave the project carrying copyleft code are the ones the website offers, served with a link to the source they were built from.

Summary

erXos takes outside code when it pays for itself, prefers permissive licenses, and records each component, with what it does and its license, in one table. Code it changes lives in the tree with an ORIGIN.md that records every file’s hash and license; code it uses unchanged is pinned in deps.lock. Small libraries such as Monocypher and ctaes keep OpenSSL out of the trusted base. A changed import file without a change notice fails make check. The packer refuses a file of unknown origin, writes NOTICES from the linker’s own maps, and admits a license that is not permissive only through one closed table of three rows.