ocran 1.4.6 → 1.5.0

data/lib/ocran/spinel_builder.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+require "open3"
+require "pathname"
+require_relative "command_output" unless defined?(Ocran::CommandOutput)
+require_relative "aot_toolchain"
+require_relative "spinel_compatibility"
+
+module Ocran
+  # Builds --spinel output: the script compiled ahead of time by Spinel
+  # (https://github.com/matz/spinel) into a native executable, instead of
+  # being packaged together with a Ruby interpreter.
+  #
+  # Spinel compiles a subset of Ruby, so whether this works depends on the
+  # program. When it does, the result is one small binary that needs
+  # nothing but libc. When it does not - or when Spinel is not installed -
+  # the user gets a report of what in their code and in which gems stands
+  # in the way, from SpinelCompatibility.
+  class SpinelBuilder
+    include CommandOutput
+
+    # How much of the compiler's output is shown when it fails. The tail is
+    # what names the error; a C compiler failure can run to thousands of
+    # lines before it.
+    MAX_OUTPUT_LINES = 60
+
+    def initialize(option)
+      @option = option
+      @script = option.script
+      @output = option.output_executable
+    end
+
+    def build
+      spinel = AotToolchain.find(:spinel)
+      analysis = SpinelCompatibility.new(@script, packages_dir: packages_dir(spinel),
+                                                  project_dirs: project_dirs).analyze
+
+      unless spinel
+        error "--spinel needs the Spinel compiler, which was not found."
+        STDERR.puts
+        STDERR.puts AotToolchain.install_instructions([:spinel])
+        STDERR.puts
+        print_report(analysis, "Meanwhile, a static check of whether #{display(@script)} is likely to compile with Spinel:")
+        raise "Spinel is not installed"
+      end
+
+      verbose "Using Spinel at #{spinel} (#{AotToolchain.version(spinel) || "version unknown"})"
+      warn_about_uncompiled_files(analysis)
+
+      flags = analysis.include_dirs.flat_map { |dir| ["-I", dir] }
+      flags << "-g" if @option.enable_debug_mode?
+      flags.concat(@option.spinel_options)
+      command = [spinel, *flags, @script.to_s, "-o", @output.to_s]
+
+      say "Compiling #{display(@script)} with Spinel"
+      verbose command.join(" ")
+      output, status = Open3.capture2e(*command)
+
+      if status.success?
+        STDERR.print output if !output.strip.empty? && @option.warning?
+        report_success(analysis)
+      else
+        report_failure(spinel, flags, output, status, analysis)
+      end
+    end
+
+    private
+
+    def report_success(analysis)
+      unless analysis.findings.empty?
+        warning "Spinel compiled the program, but the static check flagged #{analysis.findings.size} " \
+                "construct(s) that may behave differently than under CRuby#{@option.verbose? ? ":" : " (--verbose lists them)"}"
+        verbose analysis.report
+      end
+      say "Finished building #{@output} (#{File.size(@output)} bytes)"
+      say "This is a native executable for this platform; it does not need Ruby to run."
+    end
+
+    def report_failure(spinel, flags, output, status, analysis)
+      lines = output.lines
+      STDERR.puts "Spinel could not compile #{display(@script)} (exit status #{status.exitstatus.inspect}):"
+      STDERR.puts "  ... (#{lines.size - MAX_OUTPUT_LINES} earlier lines omitted)" if lines.size > MAX_OUTPUT_LINES
+      STDERR.puts lines.last(MAX_OUTPUT_LINES).map { |l| "  #{l}" }.join
+      STDERR.puts
+
+      if analysis.clean?
+        STDERR.puts "The static check found nothing Spinel is known to reject in #{analysis.files.size} file(s),"
+        STDERR.puts "so the cause is likely a limit of Spinel's type inference rather than a missing feature."
+      else
+        print_report(analysis, "What may stand in the way:")
+      end
+      print_doctor(spinel, flags)
+
+      STDERR.puts
+      STDERR.puts "Things to try:"
+      STDERR.puts "  - Spinel's supported subset: #{AotToolchain::SPINEL_URL}/blob/master/docs/limitations.md"
+      STDERR.puts "  - --spinel-opt --defer-refusals builds anyway; refused methods then raise NotImplementedError when called"
+      STDERR.puts "  - --spinel-opt --warn-widen shows where inference gave up on a type"
+      unless analysis.problem_gems.empty?
+        names = analysis.problem_gems.map(&:name).join(", ")
+        STDERR.puts "  - replace or drop the gems Spinel cannot compile (#{names}), or leave out --spinel to package them with Ruby"
+      end
+      raise "Spinel could not compile #{display(@script)}"
+    end
+
+    # spinel-doctor, installed beside the compiler, adds what the compile
+    # error alone does not say: calls that degrade to nil, methods whose
+    # types inference gave up on, requires it treats as no-ops. Its build
+    # leg repeats the compiler output shown already, and its behavior leg
+    # runs the program under CRuby, so both are left out.
+    def print_doctor(spinel, flags)
+      doctor = doctor_path(spinel) or return
+
+      verbose "Running #{doctor}"
+      env = { "SPINEL" => spinel }
+      command = [doctor, "--skip", "build,behavior", @script.to_s]
+      command.concat(["--", *flags]) unless flags.empty?
+      output, = Open3.capture2e(env, *command)
+      return if output.strip.empty?
+
+      STDERR.puts
+      STDERR.puts "spinel-doctor's report:"
+      STDERR.puts output.lines.last(MAX_OUTPUT_LINES).map { |l| "  #{l}" }.join
+    rescue SystemCallError => e
+      verbose "spinel-doctor could not be run: #{e.message}"
+    end
+
+    def doctor_path(spinel)
+      candidates = [File.dirname(spinel)]
+      real = File.realpath(spinel)
+      candidates += [File.dirname(real), File.join(File.dirname(File.dirname(real)), "bin")]
+      candidates.uniq.map { |dir| File.join(dir, "spinel-doctor") }.find { |path| AotToolchain.executable?(path) }
+    rescue SystemCallError
+      nil
+    end
+
+    def print_report(analysis, heading)
+      STDERR.puts heading
+      STDERR.puts
+      STDERR.puts analysis.report.gsub(/^(?=.)/, "  ")
+    end
+
+    # Files given on the command line besides the script, which Spinel
+    # compiles in only when the program requires them. Anything else -
+    # data files, assets - is not part of the binary.
+    def warn_about_uncompiled_files(analysis)
+      compiled = analysis.files.map(&:to_s)
+      extra = @option.source_files.drop(1).reject { |f| compiled.include?(f.to_s) }
+      return if extra.empty?
+
+      shown = extra.first(5).map { |f| display(f) }.join(", ")
+      shown += ", ..." if extra.size > 5
+      warning "Spinel compiles code only; #{extra.size} file(s) given on the command line are not " \
+              "part of the executable and have to be shipped beside it: #{shown}"
+    end
+
+    # Directories whose files are the program's own rather than a gem's.
+    def project_dirs
+      [@script.dirname, *@option.source_files.map(&:dirname)].uniq
+    end
+
+    # Spinel's packages/ directory, which lists the standard library it
+    # provides: beside the compiler when installed, at the root of a source
+    # checkout otherwise (where `spinel` links to build/spinel).
+    def packages_dir(spinel)
+      return nil unless spinel
+
+      real = File.realpath(spinel)
+      [File.dirname(real), File.dirname(File.dirname(real))]
+        .map { |dir| File.join(dir, "packages") }
+        .find { |dir| File.directory?(dir) }
+    rescue SystemCallError
+      nil
+    end
+
+    # Relative to the working directory when inside it, else absolute.
+    def display(path)
+      rel = Pathname(path).relative_path_from(Pathname.pwd).to_s
+      rel.start_with?("..") ? path.to_s : rel
+    rescue ArgumentError
+      path.to_s
+    end
+  end
+end

data/lib/ocran/spinel_compatibility.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+require_relative "compatibility_scan"
+
+module Ocran
+  # Whether a script is likely to compile with Spinel, the ahead-of-time
+  # compiler behind --spinel.
+  #
+  # Spinel compiles a subset of Ruby: no eval of strings, no method_missing,
+  # no runtime class graph changes, and only the standard library it ships
+  # itself (https://github.com/matz/spinel/blob/master/docs/limitations.md).
+  #
+  # The walk also yields the -I roots that let Spinel find the pure-Ruby
+  # gems and the project's own lib/ directory, since Spinel resolves
+  # `require` at compile time against the roots it is given rather than
+  # against the gems installed for CRuby.
+  class SpinelCompatibility < CompatibilityScan
+    # Features Spinel provides when its own packages/ directory cannot be
+    # found to read the list from (it is installed beside the compiler).
+    # Mirrors packages/ plus the requires the compiler answers natively
+    # (src/spinel_parse.c: sp_lib_is_native, sp_require_tolerated,
+    # sp_require_preloaded) as of Spinel 2026.09.
+    FALLBACK_FEATURES = %w[
+      base64 benchmark bigdecimal cgi cgi/escape cgi/util csv digest digest/md5
+      digest/sha1 digest/sha2 erb ffi fiddle fiddle/import fileutils forwardable
+      io/buffer json logger net/http open3 openssl optparse pathname
+      securerandom set stringio strscan tempfile tmpdir uri zlib
+    ].freeze
+
+    NATIVE_FEATURES = %w[
+      io/console monitor time socket ostruct
+      thread enumerator fiber rational complex
+    ].freeze
+
+    # packages_dir: Spinel's packages/ directory, if known, to read the
+    #               features it provides from
+    def initialize(script, packages_dir: nil, project_dirs: nil)
+      super(script, project_dirs: project_dirs)
+      @features = spinel_features(packages_dir)
+      @allowed = {}
+    end
+
+    def target = "Spinel"
+
+    private
+
+    def provided_feature?(feature) = @features.include?(feature)
+
+    def gem_problem(gem)
+      if gem.native
+        [:error, "has a C extension, which Spinel cannot compile"]
+      elsif gem.stdlib
+        # Spinel has its own versions of the parts of the standard library
+        # it supports (matched by name before a gem is ever looked up), so
+        # any other default gem is standard library it does not have.
+        [:error, "Ruby standard library that Spinel does not provide"]
+      end
+    end
+
+    def gem_status(gem)
+      return super if gem_problem(gem) || @findings.any? { |f| f.severity == :error && f.origin == gem.name }
+
+      "pure Ruby, nothing unsupported found (compiled from #{gem.spec.full_gem_path})"
+    end
+
+    def dynamic_require_message(name)
+      "#{name} with a computed name: Spinel resolves requires at compile time, so the name must be a string literal"
+    end
+
+    def spinel_features(packages_dir)
+      features = NATIVE_FEATURES.dup
+      if packages_dir && File.directory?(packages_dir)
+        Dir.glob(File.join(packages_dir, "*")).each do |pkg|
+          Dir.glob("**/*.rb", base: pkg).each do |rel|
+            next if rel.start_with?("test/", "build/") || rel.include?("/test/")
+
+            features << rel.delete_suffix(".rb")
+          end
+        end
+      else
+        features.concat(FALLBACK_FEATURES)
+      end
+      features.uniq
+    end
+
+    def check_def(node)
+      if node.name == :method_missing
+        flag(:warning, node, "method_missing is never dispatched by Spinel; calls to undefined methods fail to compile")
+      end
+    end
+
+    def check_global(node)
+      if %i[$LOAD_PATH $:].include?(node.name)
+        flag(:warning, node, "#{node.name} has no effect: Spinel resolves every require at compile time")
+      end
+    end
+
+    def check_constant(node)
+      flag(:error, node, "TracePoint is not supported (it needs an interpreter loop)") if node.name == :TracePoint
+    end
+
+    def check_call(node, name, args, receiver, kernel)
+      return if @allowed[node.object_id]
+
+      case name
+      when :load
+        flag(:error, node, "load: a compiled program cannot load Ruby files at run time") if kernel && !args.empty?
+      when :eval
+        flag(:error, node, "eval of a string is not supported (no parser at run time)") if kernel
+      when :instance_eval, :class_eval, :module_eval, :class_exec
+        if node.block.nil? && args.any? && !args.first.is_a?(Prism::BlockArgumentNode)
+          flag(:error, node, "#{name} with a string is not supported (the block form works)")
+        end
+      when :define_method
+        unless literal?(args.first)
+          flag(:warning, node, "define_method with a computed name works only where Spinel can enumerate the names at compile time")
+        end
+      when :instance_variable_get, :instance_variable_set
+        unless literal?(args.first)
+          flag(:error, node, "#{name} with a computed name is not supported (only literal names like :@x)")
+        end
+      when :send, :public_send, :__send__
+        if args.first && !literal?(args.first)
+          flag(:warning, node, "#{name} with a computed method name only dispatches to methods named literally somewhere in the program")
+        end
+      when :binding
+        if kernel && args.empty?
+          flag(:error, node, "binding as an object is not supported (only binding.local_variable_get(:literal))")
+        end
+      when :local_variable_get
+        # binding.local_variable_get(:x) with a literal name is supported.
+        if receiver.is_a?(Prism::CallNode) && receiver.name == :binding && literal?(args.first)
+          @allowed[receiver.object_id] = true
+        end
+      when :each_object, :count_objects
+        flag(:error, node, "ObjectSpace.#{name} is not supported") if constant?(receiver, :ObjectSpace)
+      when :set_trace_func
+        flag(:error, node, "set_trace_func is not supported") if kernel
+      when :callcc
+        flag(:error, node, "callcc / Continuation is not supported") if kernel
+      when :refine, :using
+        if receiver.nil? && args.size == 1 && (node.block || name == :using)
+          flag(:error, node, "refinements (refine / using) are not supported")
+        end
+      when :new
+        flag(:error, node, "Class.new builds a class at run time, which is not supported") if constant?(receiver, :Class)
+      end
+    end
+  end
+end