Onramp is a virtualized implementation of C that can be bootstrapped from scratch on arbitrary hardware.
Starting in machine code, we implement...
- ...a tool to convert hexadecimal with comments to raw bytes, in which we implement...
- ...a virtual machine to run a simple bytecode, in which we implement...
- ...a minimal linker to resolve labels, in which we implement...
- ...an assembler for a custom assembly language, in which we implement...
- ...a compiler and preprocessor for a minimal subset of C, in which we implement...
- ...a partial C99 compiler and libc, in which we implement...
- ...a C17 compiler, preprocessor, assembler, linker, libc and related tools.
The resulting toolchain can (soon) bootstrap a native C compiler (e.g. TinyCC), which can bootstrap GCC, which can compile an entire system.
Only the first two steps are platform-specific. The entire rest of the process operates on a platform-independent bytecode. Onramp bytecode is simple to implement, simple to hand-write, and simple to compile to, making the entire bootstrap process as simple and portable as possible.
The platform independence of Onramp makes present-day C trivially compilable by future archaeologists, alien civilizations, collapse recovery efforts and more. The goal of Onramp is to maintain a timeless and universal bootstrapping path to C.
Most compilers are self-hosting: they are written in the language they compile. C compilers tend to be written in C, so to compile a C compiler, you need to already have a C compiler. This is a chicken-and-egg problem.
Onramp is instead self-bootstrapping: it can compile itself from scratch. Onramp is written in stages and broken up into small discrete tools. Each stage of each tool can be compiled by the stages before it. All stages are plain text, human-readable and heavily documented to make the entire process auditable.
All you need to compile and use Onramp are the initial stages: the hex tool and virtual machine. These can easily be implemented by anyone in anything. Onramp includes implementations in handwritten machine code as well as in high-level languages like Python and C.
Once you have a VM, Onramp bootstraps itself. Read the full bootstrapping path for details. Onramp follows in the footsteps of the bcompiler and stage-0 bootstrapping projects; see the inspiration page for more.
Onramp is not yet complete. It can compile Doom, but not much else at the moment. It is missing floating point support and most libc functionality.
A near-term goal is to compile native compilers and tools: TinyCC, cproc+QBE, chibicc/Kefir+binutils, etc. A medium-term goal is to be able to boot a computer directly into a freestanding Onramp VM in order to bootstrap a modern OS kernel from source.
Onramp is an experiment in implementing C completely from scratch on a custom architecture, retaining all bootstrap stages in between. It is essentially three compilers, three preprocessors/assemblers/linkers, a multi-stage libc, a custom instruction set, several virtual machines, a debugger... It will take a long time to complete and there are many directions it can take in the future.
See the Implementation Status document for a breakdown of implemented and missing features.
WARNING: The libc is incomplete and there is no support for floating point math. Onramp is not yet ready for real world use.
On POSIX systems, run the build script and put the results on your PATH.
scripts/posix/build.sh
export PATH=$PWD/build/posix/bin:$PATHThat's it! You can now compile C programs with onrampcc.
You'll need this PATH to run programs since they depend on onrampvm. If you'd like to install Onramp in ~/.local/bin instead, run this:
scripts/posix/install.shSince Onramp is self-bootstrapping, this works even on a system that does not have a C compiler, binutils, make or any other build tools. Try it on a barebones x86_64 Linux with nothing but coreutils.
See the Setup Guide for more information on how to build Onramp and the Usage Guide for how to use it.
Contributions are welcome! I am especially looking for bug reports, general feedback, bug fixes and libc improvements. You can also support the project financially via GitHub Sponsors.
The primary Onramp repository is hosted here on GitHub but you don't have to use GitHub if you don't want to. Feel free to host a fork or mirror anywhere. Code contributions can be done by GitHub pull request, by sending me links to your external fork over email or IRC, or simply by emailing me patches.
Authors retain copyright over their code contributions, but all code in this repository must be MIT licensed. By contributing to Onramp you agree to license your contributions under the MIT license and you assert that you have the right to do so.
- core/ - Source code of the platform-independent parts of Onramp. Contains the compiler, linker, driver, libc, etc.
- platform/ - Source code implementations of the platform-specific components of Onramp for various platforms.
- scripts/ - Scripts for building and installing Onramp on various platforms.
- docs/ - Specifications of Onramp's languages and other documentation. Defines the Onramp subsets of C, Onramp Assembly, etc.
- test/ - Test cases and scripts for testing the various Onramp components.
Onramp documentation (including this README.md) is written in GitHub-Flavored Markdown. Onramp is heavily documented; specifications are written for all of Onramp's tools and languages.
The following documentation pages are available:
- Setup Guide
- Usage Guide
- Tools
- Core Tools
- Platform-specific Tools
- Specifications
- Miscellaneous
In addition, each tool, and each stage of each tool has a README.md describing the implementation. Look for the README.md in any directory for a description of its contents.
| Extension | Description |
|---|---|
.ohx |
Onramp Hexadecimal, plain-text hexadecimal with comments |
.oe |
Onramp Executable, an Onramp bytecode program in binary |
.oo |
Onramp Object File, plain-text bytecode with labels |
.oa |
Onramp Archive, a static library of .oo files |
.os |
Onramp Assembly, our custom assembly language |
.i |
Preprocessed C source code (no comments, no preprocessor directives) |
.c |
C source code, an Onramp Subset (omC or opC) or a standard version |
.sh |
Onramp Shell, our subset of POSIX shell |
.od |
Onramp Debug Info, the debug symbols for an Onramp executable |
Security: Compiler binaries can contain malware and backdoors that insert viruses into programs they compile. Malicious code in a compiler can even recognize its own source code and propagate itself. Recompiling a compiler with itself therefore does not eliminate the threat. The only compiler that can truly be trusted is one that you've bootstrapped from scratch.
Preservation: We have a duty to preserve information and media about our culture, our history, and our world for future generations. We need to make it possible for contemporary codecs and compression algorithms to run on hardware we can't even concieve of. The best way to do that is to preserve the code, along with the tools to compile it on anything.
Education: Bootstrapping demonstrates the entire stack from machine code to a high-level language. Students can observe how every step of the process works, and in the case of Onramp, on a simplified machine with simplified tools and languages.
Fun: Modern languages and frameworks have little connection to how hardware really works. Layers of complexity and waste continue to build upon one another, and goals of simplicity and efficiency have been abandoned by the industry. Bootstrapping is a respite from this. Working with the bare metal, writing low-level code, understanding every part of the machine and the toolchain can reignite our passion for software and bring much needed joy back into programming.
The Onramp C compiler targets a simple virtual machine with its own runtime environment and libc. This means it can't link against native libraries, and it can't do graphics, sound, networking, etc.
Onramp is not intended to be a general-purpose native compiler. It is intended (among other things) to bootstrap such a compiler.
The virtual machine therefore implements only those features that would be useful to a compilation environment. These features should nevertheless be sufficient to emulate much of a POSIX-like system, to support some basic coreutils and to run configure scripts and build tools and so on. A goal of Onramp is to be able to compile an entire native system including a kernel from a freestanding Onramp VM.
