Skip to content

README.md

Latest commit

 

History

History
153 lines (98 loc) · 4.35 KB

README.md

File metadata and controls

153 lines (98 loc) · 4.35 KB

jello

The compiler IR for linkers.

jello is a deterministic linker driver that turns messy, folklore-heavy linking into a clean, explainable LinkPlan. It normalizes linker invocations, resolves the environment, produces a deterministic plan, and runs the best backend linker.

It does not replace your linker. It makes linking understandable and reliable.

jello ships as three binaries:

  • jellocc / jelloc++ — transparent compiler wrappers. Drop in as CC=jellocc and they passthrough all invocations to the real compiler. Your build system doesn't know they're there.
  • jellod — the intelligent linker driver. This is where the LinkPlan pipeline lives: normalization, resolution, reordering, diagnostics, and backend selection.

Why jello exists

Linking is still one of the most opaque parts of modern development:

  • cryptic errors
  • environment-dependent behavior
  • fragile flag ordering
  • tribal knowledge fixes

jello makes linking deterministic and explainable by introducing a first-class artifact: the LinkPlan.

What jello does

  • Acts as a transparent drop-in: CC=jellocc CXX=jelloc++ — handles compile, link, preprocess, and introspection seamlessly
  • Normalizes chaotic linker invocations into a structured model
  • Resolves target, sysroot, search paths, and libraries
  • Computes a deterministic LinkPlan
  • Selects the best backend (mold → lld → system linker)
  • Executes the backend and emits structured diagnostics

The LinkPlan (the core idea)

A LinkPlan is the compiler IR for linking — a deterministic snapshot of intent.

It includes:

  • target triple
  • ordered inputs
  • resolved library paths
  • chosen backend linker
  • applied fixes and assumptions

jello emits:

  • linkplan.json — machine-readable plan
  • replay.sh — deterministic reproduction

This turns linker behavior from folklore into data.

DX benefits (developer perspective)

  • Fewer "what the hell" linker failures
  • Actionable errors instead of cryptic symbols
  • Reproducible link steps across machines and CI
  • Less cargo-cult flag tweaking

Example:

Instead of:

undefined reference to _ZSt4cout@@GLIBCXX_3.4

jello says:

You're linking C++ objects with a C driver. Use CXX or add the C++ standard library.

DX benefits (technical perspective)

  • Deterministic linking via immutable plans
  • Structured diagnostics with root-cause evidence
  • Environment introspection (target, sysroot, ABI mismatches)
  • Stable artifacts for debugging and caching

jello turns linking into a modeled system instead of a side-effect of toolchains.

Configuration

jello works out of the box with zero config. For per-project customization, drop a .jello.json at your project root:

jello init
{
  "fix_mode": "auto",
  "emit_plan": true,
  "plan_dir": ".jello",
  "silent": true
}

Config hierarchy (highest priority wins):

  1. Environment variables (JELLO_BACKEND, JELLO_FIX_MODE, etc.)
  2. Project config (.jello.json, found by walking up from CWD)
  3. User config (~/.config/jello/config.json)
  4. Defaults

All fields are optional. Missing fields fall through to the next layer. Run jello doctor to see active config and detected environment.

Validated

jello has been tested as a drop-in CC=jellocc across 5 real-world C projects covering Makefile, autotools, and CMake build systems:

Project Files Artifacts Build System
mbedtls 113 3 static libs Makefile
lz4 22 static + shared + CLI Makefile
libsodium 146 9 link targets, static + shared autotools + libtool
zstd 101 static + shared + CLI Makefile
mimalloc 39 static + shared + 4 test binaries CMake

All builds produce identical outputs to native CC=cc. See RESULTS.md for details.

What jello is not

  • Not a new ELF/Mach-O/COFF linker
  • Not a package manager
  • Not a full build system

jello is a semantic linker driver: orchestration, normalization, and diagnostics.

Philosophy

Linking should not require folklore.

If compilers have IRs, linking should too.

jello makes linking legible.