rubox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b21effe4e87ff543efe951e8bdc3456466d247675c1d33f03519558bc8517d0
+  data.tar.gz: 6d3dbc24179304e03d74e43e76cbcfdceac06bfe0e24b91f9449ce9b2a46b4a6
+SHA512:
+  metadata.gz: 45eeded1e6e8993ee97f1743ccaa5abf38b4749dd500e9cdba02b44119e3fdd1a11579c5914ddb21060650fbbfb2049b18688f3711fe3c37379219dfa085aa52
+  data.tar.gz: dbf27ce0b7e63225cf8e16fb1308e403972b0a2db1c80c79bb0b731d5b429341e9ef540c40aee076316175803b36c244353e357c93af25b011c5559695e6e478

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hasinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/data/Dockerfile.ruby-build

@@ -0,0 +1,119 @@
+# syntax=docker/dockerfile:1
+#
+# Builds CRuby on Alpine Linux (musl) with system deps statically linked.
+# The binary links against musl libc dynamically (for dlopen support),
+# but we bundle musl's ld.so in the payload so the result works on
+# ANY Linux distro -- glibc, musl, or anything else.
+#
+ARG RUBY_VERSION=4.0.0
+ARG JOBS=4
+
+FROM alpine:3.21 AS builder
+
+ARG RUBY_VERSION
+ARG JOBS
+
+# Build deps - both shared and static
+RUN apk add --no-cache \
+    build-base \
+    linux-headers \
+    openssl-dev openssl-libs-static \
+    zlib-dev zlib-static \
+    yaml-dev yaml-static \
+    libffi-dev \
+    readline-dev readline-static \
+    ncurses-dev ncurses-static \
+    gdbm-dev \
+    curl \
+    autoconf \
+    bison
+
+# Rust is needed for YJIT but may not be available on all architectures
+# (e.g. cross-compiling x86_64 on arm64 via qemu). Optional.
+RUN apk add --no-cache rust cargo || true
+
+# Extra native extension deps (static where available)
+RUN apk add --no-cache \
+    libxml2-dev libxml2-static \
+    libxslt-dev \
+    postgresql16-dev \
+    mariadb-connector-c-dev \
+    sqlite-dev sqlite-static \
+    || true
+
+WORKDIR /build
+
+RUN set -ex && \
+    MAJOR_MINOR=$(echo "$RUBY_VERSION" | sed 's/\.[^.]*$//') && \
+    curl -fSL "https://cache.ruby-lang.org/pub/ruby/${MAJOR_MINOR}/ruby-${RUBY_VERSION}.tar.gz" \
+        -o ruby.tar.gz && \
+    tar xzf ruby.tar.gz && \
+    rm ruby.tar.gz
+
+# Create staging dir with ONLY .a files for third-party libs we want static.
+# IMPORTANT: We specifically exclude libc.a, libdl.a, libpthread.a, libm.a etc.
+# because statically linking those disables dlopen, which we need for gem extensions.
+RUN mkdir -p /build/static-libs && \
+    # NOTE: libffi excluded -- its .a is not compiled with -fPIC on x86_64,
+    # which breaks fiddle.so linking. fiddle uses libffi dynamically instead.
+    for lib in libssl libcrypto libyaml libz libreadline libhistory libncursesw \
+               libgdbm libxml2 libxslt libsqlite3; do \
+        [ -f "/usr/lib/${lib}.a" ] && ln -sf "/usr/lib/${lib}.a" /build/static-libs/; \
+    done && \
+    echo "Staged static libs:" && ls /build/static-libs/
+
+WORKDIR /build/ruby-${RUBY_VERSION}
+
+# Configure:
+# - --disable-shared + --with-static-linked-ext: Ruby extensions linked into binary
+# - -L/build/static-libs: linker finds .a only (no .so), forcing static linkage
+#   of openssl, zlib, yaml, readline, etc.
+# - We do NOT use LDFLAGS="-static" because that disables dlopen entirely,
+#   which is needed for loading gem native extensions (.so files).
+RUN YJIT_FLAG="--disable-yjit" && \
+    if command -v rustc >/dev/null 2>&1; then YJIT_FLAG="--enable-yjit"; fi && \
+    echo "YJIT: $YJIT_FLAG" && \
+    ./configure \
+    --prefix=/opt/ruby \
+    --disable-shared \
+    --enable-static \
+    --disable-install-doc \
+    --disable-install-rdoc \
+    --disable-install-capi \
+    --with-static-linked-ext \
+    --without-gmp \
+    $YJIT_FLAG \
+    LDFLAGS="-L/build/static-libs" \
+    CFLAGS="-O2 -fPIC"
+
+RUN make -j${JOBS}
+RUN make install
+RUN strip /opt/ruby/bin/ruby
+
+# Bundle the musl dynamic linker and libgcc_s into the Ruby installation's lib/.
+# These are the only dynamic deps the Ruby binary needs.
+# The stub will invoke Ruby through this bundled ld-musl loader,
+# making the binary portable to ANY Linux distro.
+RUN echo "=== Bundling runtime libraries ===" && \
+    for lib in $(ldd /opt/ruby/bin/ruby 2>/dev/null | grep '=>' | awk '{print $3}'); do \
+        bn=$(basename "$lib"); \
+        echo "  Bundling: $bn"; \
+        cp "$lib" "/opt/ruby/lib/$bn"; \
+    done && \
+    # Also bundle the musl dynamic linker itself
+    INTERP=$(readelf -l /opt/ruby/bin/ruby | grep 'interpreter' | sed 's/.*: \(.*\)]/\1/') && \
+    echo "  Bundling loader: $INTERP" && \
+    cp "$INTERP" "/opt/ruby/lib/$(basename $INTERP)" && \
+    chmod +x "/opt/ruby/lib/$(basename $INTERP)"
+
+# Verify
+RUN echo "=== Dynamic deps ===" && \
+    ldd /opt/ruby/bin/ruby 2>&1 && \
+    echo "=== Bundled libs ===" && \
+    ls -la /opt/ruby/lib/ld-musl-* /opt/ruby/lib/lib*.so* 2>/dev/null && \
+    echo "=== Ruby ===" && \
+    /opt/ruby/bin/ruby --version && \
+    /opt/ruby/bin/ruby -e 'puts "dlopen: #{defined?(Fiddle) ? "yes" : "yes (via dl)"}"'
+
+FROM scratch AS output
+COPY --from=builder /opt/ruby /

data/data/ext/stub.c

@@ -0,0 +1,489 @@
+/*
+ * rubox stub
+ *
+ * Self-extracting loader with content-addressed caching.
+ *
+ * At runtime:
+ *   1. Opens its own executable (via /proc/self/exe or argv[0])
+ *   2. Reads the 24-byte footer to find the payload offset and size
+ *   3. Derives a cache key from offset+size (unique per build)
+ *   4. Checks ~/.cache/rubox/<key>/ for existing extraction
+ *   5. If not cached, extracts payload there
+ *   6. Execs the bundled Ruby interpreter with the entry script
+ *
+ * On Linux, Ruby is exec'd through the bundled musl dynamic linker
+ * (lib/ld-musl-*.so.1) so the binary works on ANY Linux distro
+ * regardless of the host's libc (glibc, musl, etc).
+ *
+ * Footer layout (last 24 bytes of the binary):
+ *   [8 bytes] payload offset (little-endian uint64)
+ *   [8 bytes] payload size   (little-endian uint64)
+ *   [8 bytes] magic          "CRUBY\x00\x01\x00"
+ *
+ * Env vars:
+ *   RUBOX_CACHE    Override cache directory
+ *   RUBOX_NO_CACHE Set to 1 to extract to tmpdir with cleanup
+ *   RUBOX_VERBOSE  Set to 1 for debug messages
+ */
+
+#define _GNU_SOURCE
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <sys/file.h>
+#include <errno.h>
+#include <limits.h>
+#include <fcntl.h>
+#include <dirent.h>
+#include <glob.h>
+
+#ifdef __linux__
+#include <sys/syscall.h>
+#endif
+
+#ifdef __APPLE__
+#include <mach-o/dyld.h>
+#endif
+
+#define FOOTER_SIZE 24
+#define MAGIC "CRUBY\x00\x01\x00"
+#define MAGIC_SIZE 8
+
+static const char PAYLOAD_MAGIC[MAGIC_SIZE] = MAGIC;
+static int verbose = 0;
+
+#define LOG(...) do { if (verbose) fprintf(stderr, "rubox: " __VA_ARGS__); } while(0)
+
+static int self_exe_path(char *buf, size_t bufsize) {
+#ifdef __linux__
+    ssize_t len = readlink("/proc/self/exe", buf, bufsize - 1);
+    if (len > 0) {
+        buf[len] = '\0';
+        return 0;
+    }
+#endif
+#ifdef __APPLE__
+    uint32_t size = (uint32_t)bufsize;
+    if (_NSGetExecutablePath(buf, &size) == 0) {
+        char resolved[PATH_MAX];
+        if (realpath(buf, resolved)) {
+            strncpy(buf, resolved, bufsize - 1);
+            buf[bufsize - 1] = '\0';
+        }
+        return 0;
+    }
+#endif
+    return -1;
+}
+
+static int mkdirp(const char *path, mode_t mode) {
+    char tmp[PATH_MAX];
+    char *p = NULL;
+    size_t len;
+
+    snprintf(tmp, sizeof(tmp), "%s", path);
+    len = strlen(tmp);
+    if (tmp[len - 1] == '/') tmp[len - 1] = '\0';
+
+    for (p = tmp + 1; *p; p++) {
+        if (*p == '/') {
+            *p = '\0';
+            mkdir(tmp, mode);
+            *p = '/';
+        }
+    }
+    return mkdir(tmp, mode);
+}
+
+static int make_tmpdir(char *buf, size_t bufsize) {
+    const char *tmpdir = getenv("TMPDIR");
+    if (!tmpdir) tmpdir = getenv("TMP");
+    if (!tmpdir) tmpdir = "/tmp";
+
+    snprintf(buf, bufsize, "%s/rubox.XXXXXX", tmpdir);
+    if (mkdtemp(buf) == NULL) {
+        perror("mkdtemp");
+        return -1;
+    }
+    return 0;
+}
+
+static void cleanup_dir(const char *path) {
+    char cmd[PATH_MAX + 16];
+    snprintf(cmd, sizeof(cmd), "rm -rf '%s'", path);
+    (void)system(cmd);
+}
+
+static void build_cache_path(char *buf, size_t bufsize, const char *cache_key) {
+    const char *override = getenv("RUBOX_CACHE");
+    if (override && override[0]) {
+        snprintf(buf, bufsize, "%s", override);
+        return;
+    }
+
+#ifdef __linux__
+    /*
+     * On Linux, prefer /dev/shm (tmpfs / shared memory) for the cache.
+     * This is RAM-backed on virtually all Linux systems, so extraction
+     * and subsequent loads happen entirely in memory with no disk I/O.
+     * Skip if /dev/shm is mounted noexec (common in Docker) since we
+     * need to exec the loader and mmap Ruby's binary with PROT_EXEC.
+     */
+    struct stat shm_st;
+    if (stat("/dev/shm", &shm_st) == 0 && S_ISDIR(shm_st.st_mode) &&
+        access("/dev/shm", W_OK) == 0) {
+        /* Check for noexec by trying to create and exec a tiny script */
+        int shm_exec_ok = 0;
+        char test_path[] = "/dev/shm/.rubox-exec-test";
+        int tfd = open(test_path, O_CREAT | O_WRONLY | O_TRUNC, 0755);
+        if (tfd >= 0) {
+            const char *script = "#!/bin/sh\nexit 0\n";
+            if (write(tfd, script, strlen(script)) > 0) {
+                close(tfd);
+                char test_cmd[PATH_MAX + 32];
+                snprintf(test_cmd, sizeof(test_cmd), "%s 2>/dev/null", test_path);
+                shm_exec_ok = (system(test_cmd) == 0);
+            } else {
+                close(tfd);
+            }
+            unlink(test_path);
+        }
+        if (shm_exec_ok) {
+            snprintf(buf, bufsize, "/dev/shm/rubox/%s", cache_key);
+            LOG("/dev/shm supports exec, using RAM cache\n");
+            return;
+        } else {
+            LOG("/dev/shm is noexec, using disk cache\n");
+        }
+    }
+#endif
+
+    const char *xdg = getenv("XDG_CACHE_HOME");
+    if (xdg && xdg[0]) {
+        snprintf(buf, bufsize, "%s/rubox/%s", xdg, cache_key);
+    } else {
+        const char *home = getenv("HOME");
+        if (!home) home = "/tmp";
+        snprintf(buf, bufsize, "%s/.cache/rubox/%s", home, cache_key);
+    }
+}
+
+static int verify_extraction(const char *dest_dir) {
+    char path[PATH_MAX];
+    snprintf(path, sizeof(path), "%s/bin/ruby", dest_dir);
+    /* Use R_OK not X_OK: /dev/shm is mounted noexec on many systems,
+     * but we exec through the bundled musl loader, not directly. */
+    return access(path, R_OK);
+}
+
+static int extract_payload(const char *exe_path, off_t offset, off_t size,
+                           const char *dest_dir) {
+    char cmd[PATH_MAX * 2 + 256];
+
+    /*
+     * Payload is gzip-compressed tar. Extract with:
+     *   tail -c +<offset+1> <file> | head -c <size> | gzip -d | tar x
+     *
+     * tail/head is fast on all platforms (no bs=1 byte-at-a-time reads).
+     * tail -c +N starts output at byte N (1-indexed).
+     */
+    snprintf(cmd, sizeof(cmd),
+        "tail -c +%lld '%s' | head -c %lld | gzip -d -c | tar xf - -C '%s' 2>/dev/null",
+        (long long)(offset + 1), exe_path, (long long)size, dest_dir);
+    LOG("extracting: tail+head+gzip\n");
+    (void)system(cmd);
+    if (verify_extraction(dest_dir) == 0) return 0;
+
+    /* Fallback: GNU dd (for systems where tail -c doesn't work) */
+    snprintf(cmd, sizeof(cmd),
+        "dd if='%s' iflag=skip_bytes,count_bytes bs=65536 skip=%lld count=%lld 2>/dev/null | "
+        "gzip -d -c | tar xf - -C '%s' 2>/dev/null",
+        exe_path, (long long)offset, (long long)size, dest_dir);
+    LOG("fallback: dd+gzip\n");
+    (void)system(cmd);
+    return verify_extraction(dest_dir);
+}
+
+static uint64_t read_le64(const unsigned char *p) {
+    return (uint64_t)p[0]
+         | (uint64_t)p[1] << 8
+         | (uint64_t)p[2] << 16
+         | (uint64_t)p[3] << 24
+         | (uint64_t)p[4] << 32
+         | (uint64_t)p[5] << 40
+         | (uint64_t)p[6] << 48
+         | (uint64_t)p[7] << 56;
+}
+
+#ifdef __linux__
+/*
+ * Find the bundled musl dynamic linker.
+ * It's at <cache_dir>/lib/ld-musl-<arch>.so.1
+ * Returns 0 on success and fills loader_path.
+ */
+static int find_musl_loader(const char *cache_dir, char *loader_path, size_t bufsize) {
+    char pattern[PATH_MAX];
+    snprintf(pattern, sizeof(pattern), "%s/lib/ld-musl-*.so.1", cache_dir);
+
+    glob_t g;
+    int ret = glob(pattern, 0, NULL, &g);
+    if (ret == 0 && g.gl_pathc > 0) {
+        snprintf(loader_path, bufsize, "%s", g.gl_pathv[0]);
+        globfree(&g);
+        return 0;
+    }
+    if (ret != GLOB_NOMATCH) globfree(&g);
+    return -1;
+}
+#endif
+
+int main(int argc, char **argv) {
+    char exe_path[PATH_MAX];
+    char cache_dir[PATH_MAX];
+    char ruby_bin[PATH_MAX];
+    char entry_script[PATH_MAX];
+    char lock_path[PATH_MAX];
+    unsigned char footer[FOOTER_SIZE];
+
+    verbose = (getenv("RUBOX_VERBOSE") != NULL);
+    int no_cache = 0;
+    const char *nc = getenv("RUBOX_NO_CACHE");
+    if (nc && nc[0] == '1') no_cache = 1;
+
+    /* Find our own executable */
+    if (self_exe_path(exe_path, sizeof(exe_path)) != 0) {
+        if (argv[0] && realpath(argv[0], exe_path) == NULL) {
+            fprintf(stderr, "rubox: cannot determine executable path\n");
+            return 1;
+        }
+    }
+    LOG("exe: %s\n", exe_path);
+
+    /* Read the footer */
+    FILE *fp = fopen(exe_path, "rb");
+    if (!fp) {
+        fprintf(stderr, "rubox: cannot open %s: %s\n",
+                exe_path, strerror(errno));
+        return 1;
+    }
+
+    if (fseek(fp, -FOOTER_SIZE, SEEK_END) != 0) {
+        fprintf(stderr, "rubox: cannot seek to footer\n");
+        fclose(fp);
+        return 1;
+    }
+
+    if (fread(footer, 1, FOOTER_SIZE, fp) != FOOTER_SIZE) {
+        fprintf(stderr, "rubox: cannot read footer\n");
+        fclose(fp);
+        return 1;
+    }
+    fclose(fp);
+
+    /* Verify magic */
+    if (memcmp(footer + 16, PAYLOAD_MAGIC, MAGIC_SIZE) != 0) {
+        fprintf(stderr, "rubox: no payload found (bad magic)\n");
+        return 1;
+    }
+
+    uint64_t payload_offset = read_le64(footer);
+    uint64_t payload_size = read_le64(footer + 8);
+
+    char cache_key[33];
+    snprintf(cache_key, sizeof(cache_key), "%08llx%08llx",
+             (unsigned long long)payload_offset,
+             (unsigned long long)payload_size);
+
+    LOG("payload: offset=%llu size=%llu key=%s\n",
+        (unsigned long long)payload_offset,
+        (unsigned long long)payload_size, cache_key);
+
+    int needs_extract = 1;
+    int is_tmpdir = 0;
+
+    if (no_cache) {
+        if (make_tmpdir(cache_dir, sizeof(cache_dir)) != 0) return 1;
+        is_tmpdir = 1;
+        LOG("no-cache mode, extracting to %s\n", cache_dir);
+    } else {
+        build_cache_path(cache_dir, sizeof(cache_dir), cache_key);
+        snprintf(ruby_bin, sizeof(ruby_bin), "%s/bin/ruby", cache_dir);
+
+        if (access(ruby_bin, R_OK) == 0) {
+            needs_extract = 0;
+            LOG("cache hit: %s\n", cache_dir);
+        } else {
+            LOG("cache miss, extracting to %s\n", cache_dir);
+            mkdirp(cache_dir, 0755);
+        }
+    }
+
+    if (needs_extract) {
+        snprintf(lock_path, sizeof(lock_path), "%s.lock", cache_dir);
+        int lock_fd = open(lock_path, O_CREAT | O_WRONLY, 0644);
+        if (lock_fd >= 0) {
+            if (flock(lock_fd, LOCK_EX) == 0) {
+                snprintf(ruby_bin, sizeof(ruby_bin), "%s/bin/ruby", cache_dir);
+                if (access(ruby_bin, R_OK) == 0) {
+                    needs_extract = 0;
+                    LOG("cache populated by another process\n");
+                }
+            }
+        }
+
+        if (needs_extract) {
+            int extract_ok = (extract_payload(exe_path, (off_t)payload_offset,
+                               (off_t)payload_size, cache_dir) == 0);
+
+#ifdef __linux__
+            /* If extraction to /dev/shm failed (e.g. size limit), fall back
+             * to ~/.cache on disk. */
+            if (!extract_ok && strncmp(cache_dir, "/dev/shm/", 9) == 0) {
+                LOG("shm extraction failed, falling back to disk cache\n");
+                cleanup_dir(cache_dir);
+                if (lock_fd >= 0) { unlink(lock_path); close(lock_fd); lock_fd = -1; }
+
+                /* Rebuild path without /dev/shm preference */
+                const char *home = getenv("HOME");
+                if (!home) home = "/tmp";
+                snprintf(cache_dir, sizeof(cache_dir),
+                         "%s/.cache/rubox/%s", home, cache_key);
+                mkdirp(cache_dir, 0755);
+
+                snprintf(lock_path, sizeof(lock_path), "%s.lock", cache_dir);
+                lock_fd = open(lock_path, O_CREAT | O_WRONLY, 0644);
+                if (lock_fd >= 0) flock(lock_fd, LOCK_EX);
+
+                LOG("retrying extraction to %s\n", cache_dir);
+                extract_ok = (extract_payload(exe_path, (off_t)payload_offset,
+                                             (off_t)payload_size, cache_dir) == 0);
+            }
+#endif
+
+            if (!extract_ok) {
+                fprintf(stderr, "rubox: extraction failed\n");
+                fprintf(stderr, "\n");
+                fprintf(stderr, "Troubleshooting:\n");
+                fprintf(stderr, "  - Check disk space: df -h %s\n", cache_dir);
+                fprintf(stderr, "  - Ensure gzip is installed: which gzip\n");
+                fprintf(stderr, "  - Try verbose mode: RUBOX_VERBOSE=1 %s\n",
+                        exe_path);
+                fprintf(stderr, "  - Try without cache: RUBOX_NO_CACHE=1 %s\n",
+                        exe_path);
+                fprintf(stderr, "\n");
+                if (is_tmpdir) cleanup_dir(cache_dir);
+                if (lock_fd >= 0) { unlink(lock_path); close(lock_fd); }
+                return 1;
+            }
+            LOG("extraction complete\n");
+        }
+
+        if (lock_fd >= 0) {
+            flock(lock_fd, LOCK_UN);
+            unlink(lock_path);
+            close(lock_fd);
+        }
+    }
+
+    /* Build paths */
+    snprintf(ruby_bin, sizeof(ruby_bin), "%s/bin/ruby", cache_dir);
+    snprintf(entry_script, sizeof(entry_script), "%s/entry.rb", cache_dir);
+
+    if (access(ruby_bin, R_OK) != 0) {
+        fprintf(stderr, "rubox: ruby not found at %s\n", ruby_bin);
+        fprintf(stderr, "The cache may be corrupt. Try: rm -rf %s\n", cache_dir);
+        if (is_tmpdir) cleanup_dir(cache_dir);
+        return 1;
+    }
+
+    if (access(entry_script, R_OK) != 0) {
+        fprintf(stderr, "rubox: entry.rb not found at %s\n", entry_script);
+        fprintf(stderr, "The binary may have been packaged incorrectly.\n");
+        if (is_tmpdir) cleanup_dir(cache_dir);
+        return 1;
+    }
+
+    /* Set environment */
+    char root_env[PATH_MAX + 32];
+    snprintf(root_env, sizeof(root_env), "RUBOX_ROOT=%s", cache_dir);
+    putenv(root_env);
+
+    putenv("BUNDLE_GEMFILE=");
+
+    if (is_tmpdir) {
+        char cleanup_env[PATH_MAX + 32];
+        snprintf(cleanup_env, sizeof(cleanup_env),
+                 "RUBOX_CLEANUP=%s", cache_dir);
+        putenv(cleanup_env);
+    }
+
+    /*
+     * On Linux we exec Ruby through the bundled musl dynamic linker.
+     * This makes the binary work on ANY Linux distro (glibc, musl, etc.)
+     * because we carry our own libc.
+     *
+     * The invocation is:
+     *   /path/to/ld-musl-<arch>.so.1 --library-path /path/to/lib \
+     *       /path/to/ruby entry.rb [args...]
+     *
+     * On macOS we exec Ruby directly (system dyld handles everything).
+     */
+
+#ifdef __linux__
+    char loader_path[PATH_MAX];
+    char lib_path[PATH_MAX];
+
+    if (find_musl_loader(cache_dir, loader_path, sizeof(loader_path)) == 0) {
+        snprintf(lib_path, sizeof(lib_path), "%s/lib", cache_dir);
+        LOG("using bundled loader: %s\n", loader_path);
+
+        /* argv: loader --library-path <lib> ruby entry.rb [user args...] */
+        char *exec_loader = loader_path;
+        int new_argc = argc + 5;
+        char **new_argv = malloc(sizeof(char *) * (new_argc + 1));
+        if (!new_argv) { perror("malloc"); return 1; }
+
+        new_argv[0] = exec_loader;
+        new_argv[1] = "--library-path";
+        new_argv[2] = lib_path;
+        new_argv[3] = ruby_bin;
+        new_argv[4] = entry_script;
+        for (int i = 1; i < argc; i++) {
+            new_argv[i + 4] = argv[i];
+        }
+        new_argv[argc + 4] = NULL;
+
+        execv(exec_loader, new_argv);
+        fprintf(stderr, "rubox: exec loader failed: %s\n", strerror(errno));
+        free(new_argv);
+        /* Fall through to direct exec as fallback */
+    } else {
+        LOG("no bundled loader found, exec'ing ruby directly\n");
+    }
+#endif
+
+    /* Direct exec (macOS, or Linux fallback if no bundled loader) */
+    char **new_argv = malloc(sizeof(char *) * (argc + 2));
+    if (!new_argv) {
+        perror("malloc");
+        if (is_tmpdir) cleanup_dir(cache_dir);
+        return 1;
+    }
+
+    new_argv[0] = ruby_bin;
+    new_argv[1] = entry_script;
+    for (int i = 1; i < argc; i++) {
+        new_argv[i + 1] = argv[i];
+    }
+    new_argv[argc + 1] = NULL;
+
+    execv(ruby_bin, new_argv);
+
+    fprintf(stderr, "rubox: exec failed: %s\n", strerror(errno));
+    if (is_tmpdir) cleanup_dir(cache_dir);
+    free(new_argv);
+    return 1;
+}

data/data/ext/write-footer.c

@@ -0,0 +1,38 @@
+/*
+ * write-footer: append the 24-byte rubox footer to a file.
+ * Usage: write-footer <file> <payload_offset> <payload_size>
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include <string.h>
+
+static void write_le64(FILE *fp, uint64_t v) {
+    for (int i = 0; i < 8; i++) {
+        fputc((int)(v & 0xff), fp);
+        v >>= 8;
+    }
+}
+
+int main(int argc, char **argv) {
+    if (argc != 4) {
+        fprintf(stderr, "Usage: %s <file> <payload_offset> <payload_size>\n", argv[0]);
+        return 1;
+    }
+
+    const char *path = argv[1];
+    uint64_t offset = (uint64_t)strtoull(argv[2], NULL, 10);
+    uint64_t size = (uint64_t)strtoull(argv[3], NULL, 10);
+
+    FILE *fp = fopen(path, "ab");
+    if (!fp) {
+        perror("fopen");
+        return 1;
+    }
+
+    write_le64(fp, offset);
+    write_le64(fp, size);
+    fwrite("CRUBY\x00\x01\x00", 1, 8, fp);
+    fclose(fp);
+    return 0;
+}