rudy4 0.2.0

data/lib/rudy4/cli.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "error"
+require_relative "version"
+require_relative "vendor"
+require_relative "generator"
+require_relative "doctor"
+
+module Rudy4
+  # Command-line front end for the rudy4 gem.
+  #
+  #   rudy4 init NAME [--force]   scaffold a self-contained extension gem
+  #   rudy4 doctor [--quick]      check the Ruby + GDC toolchain
+  #   rudy4 vendor                refresh the vendored rudy4 sources in place
+  #   rudy4 --version
+  #   rudy4 help
+  class CLI
+    EXIT_OK    = 0
+    EXIT_ERROR = 1
+    EXIT_USAGE = 64
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @out  = out
+      @err  = err
+    end
+
+    def run
+      command = @argv.shift
+
+      case command
+      when nil, "help", "-h", "--help" then usage; EXIT_OK
+      when "--version", "-v", "version" then @out.puts Rudy4::VERSION; EXIT_OK
+      when "init", "new"                then cmd_init
+      when "doctor", "check"            then cmd_doctor
+      when "vendor"                     then cmd_vendor
+      else
+        @err.puts "rudy4: unknown command #{command.inspect}"
+        @err.puts
+        usage(@err)
+        EXIT_USAGE
+      end
+    rescue UsageError => e
+      @err.puts "rudy4: #{e.message}"
+      EXIT_USAGE
+    rescue Error => e
+      @err.puts "rudy4: #{e.message}"
+      EXIT_ERROR
+    end
+
+    private
+
+    # Minimal hand-rolled option parsing — the gem deliberately has no runtime
+    # dependencies, so no OptionParser/Thor.
+    def parse_options(args, allowed)
+      opts = {}
+      rest = []
+
+      args.each do |arg|
+        case arg
+        when "--force"        then require_flag(allowed, "force"); opts[:force] = true
+        when "--quick"        then require_flag(allowed, "quick"); opts[:quick] = true
+        when "--help", "-h"   then require_flag(allowed, "help"); opts[:help] = true
+        when /\A--/           then raise UsageError, "unknown option #{arg}"
+        else rest << arg
+        end
+      end
+
+      [opts, rest]
+    end
+
+    def require_flag(allowed, name)
+      return if allowed.include?(name)
+
+      raise UsageError, "option --#{name} is not valid for this command"
+    end
+
+    def cmd_init
+      opts, rest = parse_options(@argv, %w[force help])
+      if opts[:help]
+        usage(@out)
+        return EXIT_OK
+      end
+
+      name = rest.shift
+      if name.nil? || name.empty?
+        raise UsageError, "usage: rudy4 init NAME\n       e.g. rudy4 init fast_math"
+      end
+
+      unless rest.empty?
+        raise UsageError, "rudy4 init takes a single NAME (got: #{([name] + rest).join(' ')})"
+      end
+
+      generator = Generator.new(name, force: opts[:force], out: @out)
+      files = generator.call
+      generator.print_next_steps
+
+      @out.puts
+      @out.puts "  #{files.length} files written."
+      EXIT_OK
+    end
+
+    def cmd_doctor
+      opts, rest = parse_options(@argv, %w[quick help])
+      if opts[:help]
+        usage(@out)
+        return EXIT_OK
+      end
+
+      raise UsageError, "rudy4 doctor takes no arguments" unless rest.empty?
+
+      Doctor.new(quick: opts[:quick], out: @out).call
+    end
+
+    # Refresh the vendored rudy4 sources inside an existing scaffolded project.
+    # The copied-in library is pinned to the gem version it was generated with;
+    # this re-syncs it after a rudy4 upgrade, without touching user code.
+    def cmd_vendor
+      opts, rest = parse_options(@argv, %w[help])
+      if opts[:help]
+        usage(@out)
+        return EXIT_OK
+      end
+
+      raise UsageError, "rudy4 vendor takes no arguments" unless rest.empty?
+
+      target = find_extension_dir
+      unless target
+        raise Error, <<~MSG
+          No D extension module found from #{Dir.pwd} upward.
+          Run this from the root of a rudy4-generated project (or one of its
+          subdirectories) — expected something like ext/NAME/NAME.d.
+        MSG
+      end
+
+      unless Vendor.present?
+        raise Error, "The rudy4 gem's vendored sources are missing; reinstall the gem."
+      end
+
+      dest = File.join(target, "rudy")
+      FileUtils.mkdir_p(dest)
+
+      written = Vendor.d_sources.map do |source|
+        relative = source.delete_prefix("#{Vendor.rudy_dir}/")
+        path = File.join(dest, relative)
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(source, path)
+        relative
+      end
+
+      @out.puts "Refreshed #{written.length} vendored rudy4 sources in #{dest}"
+      @out.puts "Refreshed from rudy4 gem v#{Rudy4::VERSION}. Review the rudy4 CHANGELOG for API"
+      @out.puts "changes, then run `rake compile`."
+      EXIT_OK
+    end
+
+    # Walk up from the current directory looking for an extension whose D source
+    # matches the name of its own directory (the layout `rudy4 init` produces).
+    def find_extension_dir
+      dir = File.expand_path(Dir.pwd)
+
+      loop do
+        ext = File.join(dir, "ext")
+        if File.directory?(ext)
+          Dir.children(ext).sort.each do |entry|
+            candidate = File.join(ext, entry)
+            next unless File.directory?(candidate)
+            return candidate if File.file?(File.join(candidate, "#{entry}.d"))
+          end
+        end
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+
+      nil
+    end
+
+    def usage(io = @out)
+      io.puts <<~TEXT
+        rudy4 #{Rudy4::VERSION} — write Ruby native extensions in D
+
+        Usage:
+          rudy4 init NAME [--force]   Scaffold a self-contained extension gem
+          rudy4 doctor [--quick]      Check the Ruby + GDC toolchain
+          rudy4 vendor                Refresh the vendored rudy4 sources
+          rudy4 --version
+          rudy4 help
+
+        Getting started:
+          rudy4 init fast_math
+          cd fast_math
+          rake compile                # build the D extension with GDC
+          rake test                   # run the generated test suite
+
+        Then edit ext/fast_math/fast_math.d and repeat `rake compile && rake test`.
+      TEXT
+    end
+  end
+end

data/lib/rudy4/doctor.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "stringio"
+require "tmpdir"
+
+require_relative "error"
+require_relative "generator"
+require_relative "vendor"
+require_relative "version"
+
+module Rudy4
+  # `rudy4 doctor` — check that this machine can actually build a D-backed
+  # Ruby extension, and prove it by scaffolding and compiling a throwaway
+  # extension. Every failure carries a fix, not just a diagnosis.
+  class Doctor
+    Error = Rudy4::Error
+    # Runtime/toolchain combinations rudy4 has been tested against. Anything
+    # else gets a warning, never a hard failure — the point is to be honest
+    # about what is verified, not to refuse to try.
+    TESTED_RUBY_MAJOR  = "4"
+    MIN_GDC_MAJOR      = 13
+    GDC_CANDIDATES     = ["gdc-14", "gdc-13", "gdc-12", "gdc"].freeze
+
+    PASS  = "ok"
+    WARN  = "warn"
+    FAIL  = "fail"
+
+    Check = Struct.new(:status, :label, :detail, :fix)
+
+    def initialize(quick: false, out: $stdout)
+      @quick = quick
+      @out   = out
+      @checks = []
+    end
+
+    def call
+      @out.puts "rudy4 doctor — #{Rudy4::VERSION} on ruby #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+      @out.puts
+
+      check_ruby
+      check_ruby_headers
+      check_shared_libruby
+      check_gdc
+      check_vendored_sources
+      check_build unless @quick
+
+      report
+    end
+
+    private
+
+    def add(status, label, detail = nil, fix = nil)
+      @checks << Check.new(status, label, detail, fix)
+    end
+
+    # --- individual checks ---------------------------------------------------
+
+    def check_ruby
+      major = RUBY_VERSION.split(".").first
+      if major == TESTED_RUBY_MAJOR
+        add PASS, "ruby #{RUBY_VERSION}", "matches the tested 4.x C API"
+      else
+        add WARN, "ruby #{RUBY_VERSION}",
+                 "rudy4 is only tested against Ruby #{TESTED_RUBY_MAJOR}.x",
+                 "Expect compile or ABI problems on Ruby #{major}.x; pin Ruby 4.x for now."
+      end
+    end
+
+    def check_ruby_headers
+      hdr     = RbConfig::CONFIG["rubyhdrdir"]
+      archhdr = RbConfig::CONFIG["rubyarchhdrdir"]
+
+      if hdr && File.directory?(hdr) && File.file?(File.join(hdr, "ruby.h"))
+        add PASS, "ruby headers", hdr
+      else
+        add FAIL, "ruby headers",
+                 "ruby.h not found (#{hdr.inspect})",
+                 "Install the development headers: `apt-get install ruby-dev` " \
+                 "(Debian/Ubuntu) or `ruby-devel` (Fedora), or use a Ruby built with headers."
+      end
+
+      if archhdr && File.directory?(archhdr)
+        add PASS, "ruby arch headers", archhdr
+      else
+        add FAIL, "ruby arch headers",
+                 "rubyarchhdrdir not found (#{archhdr.inspect})",
+                 "Same fix as ruby headers — they ship together (ruby-dev / ruby-devel)."
+      end
+    end
+
+    def check_shared_libruby
+      libarg = RbConfig::CONFIG["LIBRUBYARG_SHARED"].to_s
+      libdir = RbConfig::CONFIG["libdir"].to_s
+
+      if libarg.empty?
+        add FAIL, "shared libruby",
+                 "this Ruby has no LIBRUBYARG_SHARED",
+                 "The extension links against libruby.so, so Ruby must be built " \
+                 "with --enable-shared. Rebuild Ruby with that flag (or install a " \
+                 "distro/shared build)."
+      else
+        add PASS, "shared libruby", "#{libarg} (in #{libdir})"
+      end
+    end
+
+    def check_gdc
+      @gdc = detect_gdc
+
+      unless @gdc
+        add FAIL, "gdc (D compiler)",
+                 "no GDC binary found (looked for #{GDC_CANDIDATES.join(', ')})",
+                 "Install it — Ubuntu 24.04: `apt-get install gdc-14`; " \
+                 "see https://gdcproject.org/downloads. Set $GDC to point at a specific binary."
+        return
+      end
+
+      version = @gdc_version = gdc_version(@gdc)
+      major   = version&.split(".")&.first.to_i
+
+      if version.nil?
+        add WARN, "gdc (D compiler)", "#{@gdc} (version not parsed)"
+      elsif major >= MIN_GDC_MAJOR
+        detail = "#{@gdc} — GDC #{version}"
+        detail += ", matches the tested GDC 14" if major == 14
+        add PASS, "gdc (D compiler)", detail
+      else
+        add WARN, "gdc (D compiler)",
+                 "#{@gdc} — GDC #{version} (older than the required #{MIN_GDC_MAJOR})",
+                 "Upgrade to GDC 14 (`apt-get install gdc-14`); rudy4 uses D features " \
+                 "older front-ends do not implement."
+      end
+    end
+
+    def check_vendored_sources
+      if Vendor.present?
+        count = Vendor.d_sources.length
+        add PASS, "vendored rudy4 sources", "#{count} .d files in #{Vendor.rudy_dir}"
+      else
+        add FAIL, "vendored rudy4 sources",
+                 "missing from #{Vendor.rudy_dir}",
+                 "Reinstall the gem: `gem install rudy4`."
+      end
+    end
+
+    # The real test: scaffold a throwaway extension, build it with GDC, load it.
+    def check_build
+      unless @gdc && Vendor.present?
+        add WARN, "build smoke test", "skipped (fix the failures above first)"
+        return
+      end
+
+      Dir.mktmpdir("rudy4-doctor-") do |tmp|
+        name = "doctor_probe"
+        generator = Generator.new(name, parent_dir: tmp, out: StringIO.new)
+        generator.call
+
+        ext_dir = File.join(tmp, name, "ext", name)
+        ok, output = run_build(ext_dir)
+
+        unless ok
+          add FAIL, "build smoke test",
+                   "GDC could not compile a scaffolded extension",
+                   "Compiler output:\n#{indent(output)}"
+          return
+        end
+
+        loaded, detail = run_load(File.join(tmp, name, "lib"), name)
+        if loaded
+          add PASS, "build smoke test", "compiled and loaded a scaffolded extension (#{detail})"
+        else
+          add FAIL, "build smoke test",
+                   "the extension compiled but could not be loaded",
+                   detail
+        end
+      end
+    rescue Generator::Error => e
+      add FAIL, "build smoke test", e.message, nil
+    end
+
+    def run_build(ext_dir)
+      env = { "GDC" => File.basename(@gdc) }
+      output = +""
+      lib_dir = File.expand_path("../../lib", ext_dir)
+
+      ok = Dir.chdir(ext_dir) do
+        FileUtils.rm_f("Makefile")
+
+        out1, err1, st1 = Open3.capture3(env, RbConfig.ruby, "extconf.rb")
+        output << out1 << err1
+        next false unless st1.success?
+
+        out2, err2, st2 = Open3.capture3(env, "make")
+        output << out2 << err2
+        next false unless st2.success?
+
+        # RubyGems runs `make install` after `make`; do the same so the .so
+        # lands in lib/ where `require` will find it.
+        out3, err3, st3 = Open3.capture3(env, "make", "install", "RUBYARCHDIR=#{lib_dir}")
+        output << out3 << err3
+        st3.success?
+      end
+      [!!ok, output.strip]
+    end
+
+    def run_load(lib_dir, name)
+      script = "require #{name.inspect}; print #{const_name(name)}.add(2, 3)"
+      out, status = Open3.capture2e(RbConfig.ruby, "-I#{lib_dir}", "-e", script)
+
+      if status.success? && out.strip == "5"
+        [true, "add(2, 3) == 5"]
+      else
+        [false, "loading the built extension failed:\n#{indent(out)}"]
+      end
+    end
+
+    def const_name(snake)
+      snake.split("_").map { |part| part[0].upcase + part[1..] }.join
+    end
+
+    # --- toolchain discovery -------------------------------------------------
+
+    def detect_gdc
+      explicit = ENV["GDC"]
+      return File.expand_path(explicit) if explicit && !explicit.empty? && which(explicit)
+
+      candidates = GDC_CANDIDATES.dup
+      candidates.unshift(File.basename(explicit)) if explicit && !explicit.empty?
+      candidates.uniq.each do |candidate|
+        path = which(candidate)
+        return path if path
+      end
+
+      nil
+    end
+
+    def which(binary)
+      return binary if binary.include?("/") && File.executable?(binary)
+
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        path = File.join(dir, binary)
+        return path if File.executable?(path) && !File.directory?(path)
+      end
+      nil
+    end
+
+    def gdc_version(binary)
+      out = IO.popen([binary, "--version"], err: [:child, :out], &:read)
+      # "gdc-14 (Ubuntu 14.2.0-4ubuntu2~24.04.1) 14.2.0" -> 14.2.0 (the GDC
+      # release; the Ubuntu build suffix differs by distro).
+      out[/\b(\d+\.\d+\.\d+)\b/, 1] || out[/\b(\d+\.\d+)\b/, 1]
+    rescue SystemCallError
+      nil
+    end
+
+    # --- reporting -----------------------------------------------------------
+
+    def report
+      @out.puts
+      failed = @checks.any? { |c| c.status == FAIL }
+      warned = @checks.any? { |c| c.status == WARN }
+
+      @checks.each do |check|
+        @out.puts "#{marker(check.status)} #{check.label}#{": #{check.detail}" if check.detail}"
+        @out.puts "      → #{check.fix}" if check.fix
+      end
+
+      @out.puts
+      if failed
+        @out.puts "Not ready to build. Fix the items marked #{marker(FAIL)} above."
+        1
+      elsif warned
+        @out.puts "Usable, with warnings — see #{marker(WARN)} items above."
+        0
+      else
+        @out.puts "All good. Try:  rudy4 init fast_math && cd fast_math && rake test"
+        0
+      end
+    end
+
+    def marker(status)
+      case status
+      when PASS then "[ ok ]"
+      when WARN then "[warn]"
+      else           "[fail]"
+      end
+    end
+
+    def indent(text, spaces = 8)
+      text.to_s.lines.map { |line| " " * spaces + line }.join.rstrip
+    end
+  end
+end

data/lib/rudy4/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rudy4
+  # Base class for the errors this gem reports to the user as a one-line
+  # message plus an exit status, rather than a backtrace.
+  class Error < StandardError; end
+
+  # A command-line usage mistake (unknown option, too many arguments).
+  class UsageError < Error; end
+end

data/lib/rudy4/generator.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+require_relative "error"
+require_relative "templates"
+require_relative "vendor"
+
+module Rudy4
+  # `rudy4 init NAME` — scaffold a self-contained D-backed extension gem.
+  #
+  # "Self-contained" is the point: the generated project vendors the rudy4 D
+  # library under ext/NAME/rudy/, so it compiles with nothing but GDC + the
+  # Ruby headers — no rudy4 checkout, no RUDY4_ROOT.
+  class Generator
+    Error = Rudy4::Error
+
+    # A rubygems-legal name: lowercase, digits, underscores; must start with a
+    # letter. We reject dots/hyphens on purpose — the extension name is spliced
+    # into D identifiers and file names, where they would not survive.
+    NAME_RE = /\A[a-z][a-z0-9_]*\z/
+
+    # The names Ruby's own kernel/object namespace already owns well enough
+    # that shadowing them would confuse rather than help a first project.
+    RESERVED = %w[
+      ruby rudy rudy4 object kernel basicobject module klass class
+      string integer float array hash symbol range struct
+    ].freeze
+
+    attr_reader :name, :dir
+
+    # @param name [String] the extension name (also the gem and directory name)
+    # @param parent_dir [String] where to create `NAME/`
+    # @param force [Boolean] write into an existing non-empty directory
+    def initialize(name, parent_dir: Dir.pwd, force: false, out: $stdout)
+      @name   = name.to_s
+      @dir    = File.expand_path(File.join(parent_dir, @name))
+      @force  = force
+      @out    = out
+
+      validate_name!
+    end
+
+    def call
+      guard_target!
+
+      unless Vendor.present?
+        raise Error, <<~MSG
+          The rudy4 gem's vendored D library is missing (#{Vendor.rudy_dir}).
+          Reinstall the gem (`gem install rudy4`) — a scaffold without it
+          could never compile.
+        MSG
+      end
+
+      FileUtils.mkdir_p(@dir)
+      written = []
+      each_file { |relative, content| written << write_file(relative, content) }
+      written += vendor_sources
+      written.sort
+    end
+
+    def print_next_steps
+      @out.puts <<~TEXT
+
+        Created #{@name}/ — a Ruby extension gem whose native half is D.
+
+        Next:
+          cd #{@name}
+          rake compile      # GDC builds ext/#{@name}/#{@name}.d
+          rake test         # 7 assertions against the compiled extension
+
+        Then edit ext/#{@name}/#{@name}.d and repeat `rake compile && rake test`.
+        Stuck? Run `rudy4 doctor` from inside the project.
+      TEXT
+    end
+
+    private
+
+    def validate_name!
+      raise Error, "Extension name is required." if @name.empty?
+
+      unless @name.match?(NAME_RE)
+        raise Error, <<~MSG
+          "#{@name}" is not a usable extension name.
+          Use `snake_case` — a lowercase letter, then lowercase letters,
+          digits or underscores (e.g. `fast_math`). Dotted or hyphenated
+          names do not survive being spliced into D identifiers.
+        MSG
+      end
+
+      return unless RESERVED.include?(@name)
+
+      raise Error, <<~MSG
+        "#{@name}" is reserved by rudy4 or by Ruby itself; pick another name.
+      MSG
+    end
+
+    def guard_target!
+      return unless File.exist?(@dir)
+      return if @force
+      return if Dir.children(@dir).empty?
+
+      raise Error, <<~MSG
+        #{@dir} already exists and is not empty.
+        Pick another name, or re-run with --force to write into it anyway.
+      MSG
+    end
+
+    def ruby_req
+      # Scaffold for the Ruby running the generator's major.minor. rudy4 tracks
+      # the 4.x C API; claiming a looser requirement would be a lie.
+      RbConfig::CONFIG["ruby_version"] || "4.0"
+    end
+
+    def tokens
+      {
+        "PROJECT_CONST" => camelize(@name),
+        "PROJECT_NAME"  => @name,
+        "RUBY_REQ"      => ruby_req,
+        "AUTHOR"        => git_config("user.name") || "Your Name",
+        "EMAIL"         => git_config("user.email") || "you@example.com",
+      }
+    end
+
+    def camelize(snake)
+      snake.split("_").map { |part| part[0].upcase + part[1..] }.join
+    end
+
+    def git_config(key)
+      value = IO.popen(["git", "config", "--get", key], &:read).strip
+      value.empty? ? nil : value
+    rescue SystemCallError
+      nil
+    end
+
+    def each_file
+      yield "#{@name}.gemspec",                        Templates.render(Templates::GEMSPEC, tokens)
+      yield "lib/#{@name}.rb",                         Templates.render(Templates::LIB_RB, tokens)
+      yield "lib/#{@name}/version.rb",                 Templates.render(Templates::VERSION_RB, tokens)
+      yield "ext/#{@name}/#{@name}.d",                 Templates.render(Templates::D_SOURCE, tokens)
+      yield "ext/#{@name}/extconf.rb",                 Templates.render(Templates::EXTCONF_RB, tokens)
+      yield "test/#{@name}_test.rb",                   Templates.render(Templates::TEST_RB, tokens)
+      yield "Rakefile",                                Templates.render(Templates::RAKEFILE, tokens)
+      yield "README.md",                               Templates.render(Templates::README, tokens)
+      yield ".gitignore",                              Templates::GITIGNORE
+    end
+
+    def write_file(relative, content)
+      path = File.join(@dir, relative)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+      relative
+    end
+
+    # Copy the vendored rudy4 library in, preserving the `rudy/` module
+    # directory so `import rudy.bind.value;` resolves at build time.
+    def vendor_sources
+      sources = Vendor.d_sources
+      raise Error, "No vendored rudy4 D sources found in #{Vendor.rudy_dir}." if sources.empty?
+
+      sources.map do |source|
+        relative = File.join("ext", @name, "rudy",
+                             source.delete_prefix("#{Vendor.rudy_dir}/"))
+        path = File.join(@dir, relative)
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(source, path)
+        relative
+      end
+    end
+  end
+end