Repository navigation
Architecture and Compiler Pipeline
Hakan Batuhan Kaba edited this page Nov 13, 2026
·
1 revision
Traditional Ruby gem builds (bundle exec rake build) load Bundler, Rake, task prerequisites, shell out to git ls-files, stat files repeatedly on disk, and rebuild identical tarballs from scratch on every invocation.
RubyToFaster replaces that stack with a streamlined, deterministic compiler pipeline inspired by Vite, Next.js (Turbopack), and Angular Architect.
-
Lifecycle
before_resolveExecutes registered plugins and inlinepkg.before_resolvehooks. -
Specification & File Resolution (
RubyToFaster::FileResolver) Loads either a.gemspecfile or an inlinepkg.spec { |s| ... }block. Prunes excluded caches (node_modules/,.next/cache/,.angular/cache/,.rtf-cache/), enforces path-traversal and symlink containment, and rejects accidental secret files (.env*,*.pem,*.key). -
Frontend Resource Staging (
RubyToFaster::Resources) Collects production bundles from Vite, Next.js, and Angular into virtualPackageEntrystructs—meaning staged files and generated manifests (public/rtf-manifest.jsonand optional Ruby helper modules) are streamed directly into the.gemwithout dirtying your Git working directory (unlesspkg.write_staged_assets = trueis enabled). -
Lifecycle
generate_bundleAllows plugins to inspect or add virtual entries to theentriesmap before hashing. -
SHA-256 Merkle Cache Lookup (
RubyToFaster::Cache) Computes a single deterministic SHA-256 root digest over:- Ruby & RubyToFaster versions
- Reproducibility settings (
SOURCE_DATE_EPOCH) - Normalized
Gem::Specificationmetadata & dependencies - Sorted relative entry paths, POSIX modes (
0644/0755), and SHA-256 content digests If.rtf-cache/artifacts/<merkle_key>.gemexists and passes SHA-256 integrity verification, the artifact is restored in ~4ms.
-
Parallel Native Extension Verification (
RubyToFaster::ExtensionBuilder) On cache miss, anyext/**/extconf.rbextensions are compiled concurrently in isolated temporary directories acrossEtc.nprocessorsworker threads usingmake -jN. -
Deterministic In-Memory Packaging (
RubyToFaster::Packager) Streamsmetadata.gz,data.tar.gz(running inlinepkg.transformhooks on bytes in flight), andchecksums.yaml.gz(containing bothSHA256andSHA512digests) directly intoGem::Package::TarWriterwithZlib::BEST_COMPRESSION. -
Budget Governance (
RubyToFaster::BudgetEvaluator) Evaluates compressed.gemKB, unpacked payload KB, and per-entry KB against configured budgets. -
Build Trace Persistence &
after_packageWrites.rtf-cache/last-build-trace.jsonand invokesafter_packagehooks.
RubyToFaster — Minimalist script-first Ruby gem build system by HNM Labs · MIT License · Security Policy