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...
- ...a minimal assembler and libc, in which we implement...
- ...a full-featured assembler for a custom assembly language, in which we implement...
- ...a compiler for a minimal subset of C, in which we implement...
- ...a corresponding preprocessor, linker and libc, in which we implement...
- ...a partial C99 compiler and libc, in which we implement...
- ...a C2x compiler with popular extensions, in which we implement...
- ...a C2x 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. The full bootstrap path is pure source code with no binaries whatsoever.
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 here. 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 doesn't compile much besides itself at the moment. My immediate goal is to support enough of C to compile Doom for command-line.
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.
I welcome bug reports but I am not currently accepting contributions. Feel free to fork this and implement VMs but be aware that the bytecode format will change. (Also, I don't have good VM tests at the moment so you might have a lot of trouble debugging your VM.)
WARNING: The final stage compiler and preprocessor are incomplete and not enabled in the bootstrap process. There is no support for function pointers, initializer lists, function-like macros, #if, float, long long, and much more. The compiler 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.
- 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.
- Setup Guide
- Usage Guide
- Languages:
- Miscellaneous:
Platform-specific:
| Program | Description | Operation |
|---|---|---|
hex |
Hex tool | Converts hexadecimal .ohx to raw bytes |
vm |
Virtual machine | Executes .oe bytecode, bridges filesystem when hosted |
Platform-independent:
| Program | Description | Operation |
|---|---|---|
cc |
Driver | Performs any or all phases of translation |
cpp |
Preprocessor | Preprocesses .c to .i |
cci |
Compiler | Compiles .i to .os |
as |
Assembler | Assembles .os to .oo object file |
ar |
Archiver | Combines .oo object files into .oa library |
ld |
Linker | Links .oo and .oa into .oe executable |
libc |
Standard library | Provides C and POSIX library functions |
sh |
Shell | Runs scripts |
os |
Operating System | Implements a filesystem and syscalls |
| 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 |
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.