portable_mruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19d331ca17ea2863151576372cf313359d5387517051f939d63493725c67a8ab
+  data.tar.gz: fbbaf32d29d7d1029fbb7c8c6dc25f3f62b24d737228b6630b658a3bc89cae1a
+SHA512:
+  metadata.gz: 04a0bc4997bbd9a9cbd4c2bf6b51388f85cac64e0aa50934a7c4e7c0e95e94b04d9cce372e1edc264436d1f08f4256f15b239a9828376c9f3a48e3d350031452
+  data.tar.gz: b87405af2e6281d25a5f6ef51ea007f07fae6d37ea45f8361edbcf8f87544aa81dc633a81be30d3a714d0a12bb9061a412031e4c16f2928195f1335d528c7546

data/README.md

@@ -0,0 +1,195 @@
+# portable_mruby
+
+Build truly portable Ruby executables that run on Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD from a single binary.
+
+## Quick Start
+
+```bash
+# Install
+gem install portable_mruby
+
+# Create a Ruby program
+echo 'puts "Hello from #{RUBY_ENGINE}!"' > hello.rb
+
+# Build portable executable
+portable-mruby build -e hello.rb -o hello.com
+
+# Run it (works on Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD)
+./hello.com
+```
+
+## How it Works
+
+portable_mruby uses [mruby](https://mruby.org/) (embedded Ruby) compiled with [Cosmopolitan Libc](https://github.com/jart/cosmopolitan) to create "Actually Portable Executables" (APE). These are single binaries that run natively on multiple operating systems and CPU architectures without any dependencies.
+
+## Supported Platforms
+
+A single binary runs on:
+- Linux (x86_64, ARM64)
+- macOS (x86_64, ARM64)
+- Windows (x86_64)
+- FreeBSD (x86_64)
+- OpenBSD (x86_64)
+- NetBSD (x86_64)
+
+## Installation
+
+```bash
+gem install portable_mruby
+```
+
+On first build, the Cosmopolitan toolchain (~60MB) will be automatically downloaded to `~/.portable-mruby/cosmocc/`.
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Build all .rb files in current directory
+portable-mruby build -o myapp.com
+
+# Build all .rb files in a directory
+portable-mruby build -d src/ -o myapp.com
+
+# Run on any supported platform
+./myapp.com
+```
+
+### With Entry Point
+
+```bash
+# Specify an entry file (runs last, after all other files)
+portable-mruby build -e main.rb -d src/ -o myapp.com
+```
+
+All `.rb` files are compiled and executed in sorted order. If `--entry` is specified, that file runs last.
+
+### Options
+
+```
+Usage: portable-mruby build [options]
+
+Options:
+    -e, --entry FILE        Entry point Ruby file (runs last)
+    -d, --dir DIR           Source directory (default: .)
+    -o, --output FILE       Output binary name (default: app.com)
+    --mruby-source DIR      Build mruby from custom source directory
+    -v, --verbose           Verbose output
+    -h, --help              Show help
+
+Environment Variables:
+    COSMO_ROOT              Path to cosmocc toolchain (auto-downloaded if not set)
+```
+
+### Using Custom mruby
+
+If you need custom mruby gems or configuration, you can build from source:
+
+```bash
+# Clone mruby with your customizations
+git clone https://github.com/mruby/mruby.git ~/mruby
+
+# Build using your custom mruby
+portable-mruby build -e main.rb --mruby-source ~/mruby -o myapp.com
+```
+
+## Example
+
+Create a simple Ruby program:
+
+```ruby
+# main.rb
+name = ARGV[0] || 'World'
+puts "Hello, #{name}!"
+puts "Running on: #{RUBY_ENGINE} #{RUBY_VERSION}"
+puts "Time: #{Time.now}"
+```
+
+Build it:
+
+```bash
+portable-mruby build --entry main.rb --output hello.com
+```
+
+Run it anywhere:
+
+```bash
+$ ./hello.com Alice
+Hello, Alice!
+Running on: mruby 3.4
+Time: 2025-12-09 12:00:00 +0000
+```
+
+## Multi-file Example
+
+```
+myapp/
+  lib/
+    greeter.rb
+  main.rb
+```
+
+```ruby
+# lib/greeter.rb
+class Greeter
+  def initialize(name)
+    @name = name
+  end
+
+  def greet
+    "Hello, #{@name}!"
+  end
+end
+```
+
+```ruby
+# main.rb
+greeter = Greeter.new(ARGV[0] || 'World')
+puts greeter.greet
+```
+
+```bash
+portable-mruby build -e main.rb -d myapp/ -o greeter.com
+./greeter.com Ruby  # => Hello, Ruby!
+```
+
+## Build Process
+
+1. Ruby source files are compiled to mruby bytecode using `mrbc`
+2. Bytecode is embedded in a C source file as byte arrays
+3. A minimal C runtime initializes mruby and loads the bytecode
+4. Everything is compiled with Cosmopolitan's `cosmocc` compiler
+5. The result is an APE binary - a polyglot that runs on all platforms
+
+## Troubleshooting
+
+### "Bundled mrbc not found"
+
+The gem installation may be corrupted. Reinstall:
+
+```bash
+gem uninstall portable_mruby
+gem install portable_mruby
+```
+
+### Build fails with cosmocc errors
+
+Ensure you have enough disk space (~300MB for cosmocc). You can also manually install cosmocc:
+
+```bash
+mkdir -p ~/.portable-mruby/cosmocc
+cd ~/.portable-mruby/cosmocc
+wget https://cosmo.zip/pub/cosmocc/cosmocc.zip
+unzip cosmocc.zip
+```
+
+### Using a pre-installed cosmocc
+
+```bash
+export COSMO_ROOT=/path/to/cosmocc
+portable-mruby build -e main.rb -o app.com
+```
+
+## License
+
+MIT License

data/exe/portable-mruby

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "portable_mruby"
+
+PortableMruby::CLI.run

data/lib/portable_mruby/binary_manager.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open-uri"
+
+module PortableMruby
+  class BinaryManager
+    COSMOCC_URL = "https://cosmo.zip/pub/cosmocc/cosmocc.zip"
+
+    class << self
+      def ensure_available(mruby_source: nil)
+        ensure_cosmocc
+        if mruby_source
+          build_mruby_from_source(mruby_source)
+        else
+          ensure_bundled_mruby
+        end
+      end
+
+      def mrbc_path
+        @mrbc_path || bundled_mrbc_path
+      end
+
+      def cosmocc_path
+        File.join(cosmocc_dir, "bin", "cosmocc")
+      end
+
+      def libmruby_path
+        @libmruby_path || bundled_libmruby_path
+      end
+
+      def include_path
+        @include_path || bundled_include_path
+      end
+
+      def lib_path
+        @lib_path || bundled_lib_path
+      end
+
+      def cosmocc_dir
+        ENV["COSMO_ROOT"] || default_cosmocc_dir
+      end
+
+      def reset_paths!
+        @mrbc_path = nil
+        @libmruby_path = nil
+        @include_path = nil
+        @lib_path = nil
+      end
+
+      private
+
+      def bundled_dir
+        File.expand_path("../../vendor/mruby", __dir__)
+      end
+
+      def bundled_mrbc_path
+        File.join(bundled_dir, "bin", "mrbc.com")
+      end
+
+      def bundled_libmruby_path
+        File.join(bundled_dir, "lib", "libmruby.a")
+      end
+
+      def bundled_include_path
+        File.join(bundled_dir, "include")
+      end
+
+      def bundled_lib_path
+        File.join(bundled_dir, "lib")
+      end
+
+      def default_cosmocc_dir
+        File.join(ENV.fetch("HOME"), ".portable-mruby", "cosmocc")
+      end
+
+      def cache_dir
+        File.join(ENV.fetch("HOME"), ".portable-mruby", "cache")
+      end
+
+      def ensure_bundled_mruby
+        unless File.exist?(bundled_mrbc_path)
+          raise BuildError, "Bundled mrbc not found at #{bundled_mrbc_path}. Gem may be corrupted."
+        end
+
+        unless File.exist?(bundled_libmruby_path)
+          raise BuildError, "Bundled libmruby.a not found at #{bundled_libmruby_path}. Gem may be corrupted."
+        end
+
+        unless File.exist?(File.join(bundled_include_path, "mruby.h"))
+          raise BuildError, "Bundled mruby headers not found. Gem may be corrupted."
+        end
+      end
+
+      def ensure_cosmocc
+        return if File.exist?(cosmocc_path)
+
+        if ENV["COSMO_ROOT"]
+          raise BuildError, "COSMO_ROOT is set but cosmocc not found at #{cosmocc_path}"
+        end
+
+        puts "Cosmopolitan toolchain not found."
+        puts "Downloading cosmocc (~60MB)..."
+
+        download_cosmocc
+      end
+
+      def download_cosmocc
+        FileUtils.mkdir_p(default_cosmocc_dir)
+        zip_path = File.join(default_cosmocc_dir, "cosmocc.zip")
+
+        download_with_progress(COSMOCC_URL, zip_path)
+
+        puts "Extracting cosmocc..."
+        Dir.chdir(default_cosmocc_dir) do
+          system("unzip", "-q", "cosmocc.zip") or raise BuildError, "Failed to extract cosmocc"
+        end
+
+        FileUtils.rm(zip_path)
+        puts "cosmocc installed to #{default_cosmocc_dir}"
+      end
+
+      def build_mruby_from_source(source_path)
+        source_path = File.expand_path(source_path)
+
+        unless File.directory?(source_path)
+          raise BuildError, "mruby source directory not found: #{source_path}"
+        end
+
+        unless File.exist?(File.join(source_path, "Rakefile"))
+          raise BuildError, "Invalid mruby source directory (no Rakefile): #{source_path}"
+        end
+
+        puts "Building mruby from source: #{source_path}"
+
+        build_config_path = File.join(source_path, "build_config", "portable_mruby.rb")
+        File.write(build_config_path, generate_build_config)
+
+        Dir.chdir(source_path) do
+          env = { "COSMO_ROOT" => cosmocc_dir }
+
+          unless system(env, "rake", "deep_clean", exception: false)
+            system(env, "rake", "clean")
+          end
+
+          system(env, "rake", "MRUBY_CONFIG=portable_mruby") or
+            raise BuildError, "Failed to build mruby"
+        end
+
+        build_dir = File.join(source_path, "build", "host")
+        @mrbc_path = File.join(build_dir, "bin", "mrbc.com")
+        @libmruby_path = File.join(build_dir, "lib", "libmruby.a")
+        @lib_path = File.join(build_dir, "lib")
+
+        combined_include = File.join(cache_dir, "include")
+        FileUtils.rm_rf(combined_include)
+        FileUtils.mkdir_p(combined_include)
+        FileUtils.cp_r(File.join(source_path, "include", "."), combined_include)
+        FileUtils.cp_r(File.join(build_dir, "include", "."), combined_include)
+        @include_path = combined_include
+
+        puts "mruby built successfully from #{source_path}"
+      end
+
+      def generate_build_config
+        <<~RUBY
+          COSMO_ROOT = ENV['COSMO_ROOT']
+
+          unless COSMO_ROOT && File.directory?(COSMO_ROOT)
+            raise "COSMO_ROOT environment variable must point to cosmocc directory"
+          end
+
+          MRuby::Build.new do |conf|
+            conf.cc do |cc|
+              cc.command = "\#{COSMO_ROOT}/bin/cosmocc"
+              cc.flags = %w[-Os -fno-omit-frame-pointer]
+            end
+
+            conf.cxx do |cxx|
+              cxx.command = "\#{COSMO_ROOT}/bin/cosmoc++"
+              cxx.flags = conf.cc.flags.dup
+            end
+
+            conf.linker do |linker|
+              linker.command = "\#{COSMO_ROOT}/bin/cosmocc"
+              linker.flags = %w[-static]
+            end
+
+            conf.archiver do |archiver|
+              archiver.command = "\#{COSMO_ROOT}/bin/cosmoar"
+            end
+
+            conf.exts.executable = '.com'
+
+            conf.gem core: 'hal-posix-io'
+            conf.gem core: 'hal-posix-socket'
+            conf.gem core: 'hal-posix-dir'
+
+            conf.gembox 'stdlib'
+            conf.gembox 'stdlib-ext'
+            conf.gembox 'stdlib-io'
+            conf.gembox 'math'
+            conf.gembox 'metaprog'
+
+            conf.gem core: 'mruby-bin-mrbc'
+          end
+        RUBY
+      end
+
+      def download_with_progress(url, dest)
+        URI.open(url, # rubocop:disable Security/Open
+                 content_length_proc: ->(total) { @total_size = total },
+                 progress_proc: lambda { |size|
+                   if @total_size
+                     percent = (size.to_f / @total_size * 100).round(1)
+                     print "\rDownloading: #{percent}% (#{size / 1024 / 1024}MB / #{@total_size / 1024 / 1024}MB)"
+                   end
+                 }) do |remote|
+          File.open(dest, "wb") { |f| f.write(remote.read) }
+        end
+        puts
+      end
+    end
+  end
+end

data/lib/portable_mruby/builder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+
+module PortableMruby
+  class Builder
+    attr_reader :entry_file, :source_dir, :output, :verbose, :mruby_source
+
+    def initialize(entry_file: nil, source_dir: ".", output: "app.com", verbose: false, mruby_source: nil)
+      @entry_file = entry_file
+      @source_dir = File.expand_path(source_dir)
+      @output = output
+      @verbose = verbose
+      @mruby_source = mruby_source
+      @temp_dir = nil
+    end
+
+    def build
+      BinaryManager.ensure_available(mruby_source: @mruby_source)
+
+      @temp_dir = Dir.mktmpdir("portable-mruby")
+
+      ruby_files = collect_ruby_files
+      log "Found #{ruby_files.size} Ruby file(s)"
+
+      bytecode_files = compile_to_bytecode(ruby_files)
+      log "Compiled #{bytecode_files.size} bytecode file(s)"
+
+      c_source = CGenerator.new(bytecode_files).generate
+      c_file = File.join(@temp_dir, "app.c")
+      File.write(c_file, c_source)
+      log "Generated C source (#{c_source.size} bytes)"
+
+      compile_binary(c_file)
+      log "Built: #{@output}"
+
+      @output
+    ensure
+      FileUtils.rm_rf(@temp_dir) if @temp_dir
+      BinaryManager.reset_paths!
+    end
+
+    private
+
+    def log(message)
+      puts message if @verbose
+    end
+
+    def collect_ruby_files
+      pattern = File.join(@source_dir, "**", "*.rb")
+      files = Dir.glob(pattern).sort
+
+      raise BuildError, "No Ruby files found in #{@source_dir}" if files.empty?
+
+      if @entry_file
+        entry_path = File.absolute_path?(@entry_file) ? @entry_file : File.join(@source_dir, @entry_file)
+        raise BuildError, "Entry file not found: #{entry_path}" unless File.exist?(entry_path)
+
+        files.delete(entry_path)
+        files << entry_path
+      end
+
+      files
+    end
+
+    def compile_to_bytecode(ruby_files)
+      compiler = BytecodeCompiler.new
+
+      ruby_files.map do |rb_file|
+        relative_path = rb_file.sub("#{@source_dir}/", "")
+        mrb_name = relative_path.gsub("/", "_").sub(/\.rb$/, ".mrb")
+        mrb_path = File.join(@temp_dir, mrb_name)
+
+        compiler.compile(rb_file, mrb_path)
+
+        { mrb_path: mrb_path, name: relative_path }
+      end
+    end
+
+    def compile_binary(c_file)
+      cmd = [
+        BinaryManager.cosmocc_path,
+        "-Os", "-static",
+        "-o", @output,
+        c_file,
+        "-I#{BinaryManager.include_path}",
+        "-L#{BinaryManager.lib_path}",
+        "-lmruby", "-lm"
+      ]
+
+      log "Running: #{cmd.join(' ')}"
+
+      raise BuildError, "Failed to compile binary" unless system(*cmd)
+    end
+  end
+end

data/lib/portable_mruby/bytecode_compiler.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PortableMruby
+  class BytecodeCompiler
+    def initialize(mrbc_path: nil)
+      @mrbc_path = mrbc_path || BinaryManager.mrbc_path
+    end
+
+    def compile(input_rb, output_mrb = nil)
+      output_mrb ||= input_rb.sub(/\.rb$/, ".mrb")
+
+      unless system(@mrbc_path, "-o", output_mrb, input_rb)
+        raise CompileError, "Failed to compile #{input_rb}"
+      end
+
+      output_mrb
+    end
+  end
+end

data/lib/portable_mruby/c_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module PortableMruby
+  class CGenerator
+    RUNTIME_TEMPLATE = <<~'C'
+      #include <mruby.h>
+      #include <mruby/array.h>
+      #include <mruby/compile.h>
+      #include <mruby/irep.h>
+      #include <mruby/string.h>
+      #include <mruby/variable.h>
+      #include <stdio.h>
+      #include <stdlib.h>
+
+      {{BYTECODE_ARRAYS}}
+
+      static const struct {
+          const uint8_t *data;
+          size_t size;
+          const char *name;
+      } bytecode_files[] = {
+      {{BYTECODE_ENTRIES}}
+          {NULL, 0, NULL}
+      };
+
+      int main(int argc, char **argv) {
+          mrb_state *mrb;
+          mrb_value ARGV_val;
+          int i;
+          int return_value = 0;
+
+          mrb = mrb_open();
+          if (!mrb) {
+              fprintf(stderr, "Error: Failed to initialize mruby\n");
+              return 1;
+          }
+
+          ARGV_val = mrb_ary_new_capa(mrb, argc > 1 ? argc - 1 : 0);
+          for (i = 1; i < argc; i++) {
+              mrb_ary_push(mrb, ARGV_val, mrb_str_new_cstr(mrb, argv[i]));
+          }
+          mrb_define_global_const(mrb, "ARGV", ARGV_val);
+          mrb_gv_set(mrb, mrb_intern_lit(mrb, "$0"), mrb_str_new_cstr(mrb, argv[0]));
+
+          for (i = 0; bytecode_files[i].data != NULL; i++) {
+              mrb_load_irep(mrb, bytecode_files[i].data);
+
+              if (mrb->exc) {
+                  mrb_print_error(mrb);
+                  return_value = 1;
+                  break;
+              }
+          }
+
+          mrb_close(mrb);
+          return return_value;
+      }
+    C
+
+    def initialize(bytecode_files)
+      @bytecode_files = bytecode_files
+    end
+
+    def generate
+      RUNTIME_TEMPLATE
+        .gsub("{{BYTECODE_ARRAYS}}", generate_bytecode_arrays)
+        .gsub("{{BYTECODE_ENTRIES}}", generate_bytecode_entries)
+    end
+
+    private
+
+    def generate_bytecode_arrays
+      @bytecode_files.each_with_index.map do |file_info, idx|
+        bytes = File.binread(file_info[:mrb_path]).bytes
+        byte_lines = bytes.each_slice(16).map do |slice|
+          "    " + slice.map { |b| format("0x%02x", b) }.join(", ")
+        end
+
+        <<~C
+          static const uint8_t bytecode_#{idx}[] = {
+          #{byte_lines.join(",\n")}
+          };
+        C
+      end.join("\n")
+    end
+
+    def generate_bytecode_entries
+      @bytecode_files.each_with_index.map do |file_info, idx|
+        size = File.size(file_info[:mrb_path])
+        %(    {bytecode_#{idx}, #{size}, "#{file_info[:name]}"},)
+      end.join("\n")
+    end
+  end
+end