ocran 1.4.6 → 1.5.0

data/lib/ocran/roundhouse_builder.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+require "fileutils"
+require "open3"
+require "pathname"
+require "tmpdir"
+require_relative "command_output" unless defined?(Ocran::CommandOutput)
+require_relative "aot_toolchain"
+
+module Ocran
+  # Builds --roundhouse output: a Rails application compiled to a native
+  # server binary by Roundhouse (https://github.com/rubys/roundhouse) and
+  # Spinel (https://github.com/matz/spinel).
+  #
+  # Roundhouse lowers the app to the subset of Ruby Spinel compiles and
+  # writes it out as a spin project; its `make assets` builds static/ and
+  # `spin build` compiles the rest. The binary
+  # reads its static assets, configuration and SQLite database from beside
+  # it, so the result is a directory: the binary plus those files.
+  #
+  # Whether an app gets through depends on how much of it Roundhouse covers
+  # yet. When it does not - or when the tools are missing - the user gets
+  # Roundhouse's own analysis of the app (`roundhouse check`), whose gem
+  # census says which of the app's gems it does not model.
+  class RoundhouseBuilder
+    include CommandOutput
+
+    # What the binary reads at run time, copied from the generated project.
+    RUNTIME_DIRS = %w[static public db config].freeze
+
+    MAX_OUTPUT_LINES = 60
+    MAX_CHECK_ERRORS = 15
+
+    # Keeps the child tools out of whatever bundle OCRAN was started under:
+    # Roundhouse's spin project may shell out to Ruby (asset steps, tests).
+    BUNDLER_FREE_ENV = {
+      "RUBYOPT" => nil,
+      "BUNDLER_SETUP" => nil,
+      "BUNDLE_GEMFILE" => nil,
+      "BUNDLE_LOCKFILE" => nil
+    }.freeze
+
+    def initialize(option)
+      @option = option
+      @app = option.roundhouse_app
+      @output = option.roundhouse_output
+    end
+
+    def build
+      tools = AotToolchain.find_all(%i[roundhouse spinel spin])
+      missing = tools.select { |_, path| path.nil? }.keys
+      report_missing_tools(tools, missing) unless missing.empty?
+
+      tools.each do |name, path|
+        verbose "Using #{name} at #{path} (#{AotToolchain.version(path) || "version unknown"})"
+      end
+
+      work = Dir.mktmpdir("ocran-roundhouse")
+      project = File.join(work, "spinel")
+      @env = child_env(tools)
+
+      say "Transpiling #{display(@app)} with Roundhouse"
+      command = [tools[:roundhouse], "--target", "spinel", *@option.roundhouse_options, "-o", project, @app.to_s]
+      output, status = run(command)
+      transpile_failed(tools, output, status, work) unless status.success?
+
+      build_assets(project, work)
+
+      say "Compiling with Spinel (spin build); the first build of a large app can take a few minutes"
+      output, status = run([tools[:spin], "build"], chdir: project, env: library_path_env(project))
+      compile_failed(tools, output, status, work) unless status.success?
+
+      install(project)
+      FileUtils.remove_entry(work)
+    end
+
+    private
+
+    def run(command, chdir: Dir.pwd, env: {})
+      verbose command.join(" ")
+      Open3.capture2e(@env.merge(env), *command, chdir: chdir)
+    rescue SystemCallError => e
+      [e.message, nil]
+    end
+
+    # The generated project builds its static assets with `make assets`:
+    # Turbo and Stimulus copied out of their gems, the app's own JavaScript
+    # and stylesheets, and Tailwind when the app uses it (through npx).
+    # Bundler installs only the Gemfile's assets group for it, so no
+    # C-extension gem is compiled for a step that only copies files.
+    # Without static/ the binary still serves pages, with every stylesheet
+    # and script a 404, so a failure here stops the build.
+    def build_assets(project, work)
+      makefile = File.join(project, "Makefile")
+      return unless File.file?(makefile) && File.foreach(makefile).any? { |l| l.start_with?("assets:") }
+
+      retry_command = "cd #{File.join(work, "spinel")} && BUNDLE_ONLY=assets bundle install && BUNDLE_ONLY=assets make assets"
+      make = AotToolchain.search_path("make", @env)
+      bundle = AotToolchain.search_path("bundle", @env)
+      unless make && bundle
+        error "Building the static assets needs `make` and `bundle`, which #{make ? "`bundle` was" : bundle ? "`make` was" : "were"} not found."
+        STDERR.puts "  The generated project is kept; with both installed: #{retry_command}"
+        raise "the static assets could not be built"
+      end
+
+      say "Building static assets (make assets)"
+      env = { "BUNDLE_ONLY" => "assets" }
+      [[bundle, "install"], [make, "assets"]].each do |command|
+        output, status = run(command, chdir: project, env: env)
+        next if status&.success?
+
+        print_failure("Building the static assets failed (#{command.map { |c| File.basename(c) }.join(" ")})", output, status)
+        STDERR.puts "Things to check:"
+        STDERR.puts "  - an app that builds Tailwind needs Node.js and npm for `npx @tailwindcss/cli`"
+        STDERR.puts "  - the generated project is kept; to retry: #{retry_command}"
+        raise "the static assets could not be built"
+      end
+    end
+
+    # spin links the allocator spin.toml names by bare name (-ljemalloc), and
+    # the linker searches only its default directories, which on Apple
+    # Silicon do not include Homebrew's /opt/homebrew/lib. pkg-config knows
+    # where the library is, so its -L directories go on LIBRARY_PATH (which
+    # gcc and clang both read) for the build.
+    def library_path_env(project)
+      manifest = File.join(project, "spin.toml")
+      allocator = File.file?(manifest) && File.read(manifest)[/^\s*allocator\s*=\s*"([^"]+)"/, 1]
+      return {} unless allocator && allocator != "system"
+
+      pkg_config = AotToolchain.search_path("pkg-config", @env)
+      return {} unless pkg_config
+
+      output, status = Open3.capture2(pkg_config, "--libs-only-L", allocator, err: File::NULL)
+      return {} unless status.success?
+
+      dirs = output.split.select { |flag| flag.start_with?("-L") }.map { |flag| flag.delete_prefix("-L") }
+      return {} if dirs.empty?
+
+      verbose "Adding #{dirs.join(", ")} (pkg-config #{allocator}) to LIBRARY_PATH"
+      { "LIBRARY_PATH" => (dirs + [ENV.fetch("LIBRARY_PATH", "")]).reject(&:empty?).join(File::PATH_SEPARATOR) }
+    rescue SystemCallError
+      {}
+    end
+
+    # spin calls spinel by name, so a spinel found outside PATH (through
+    # SPINEL or a conventional location) is put on the child's PATH.
+    def child_env(tools)
+      dirs = tools.values.compact.map { |path| File.dirname(path) }.uniq
+      BUNDLER_FREE_ENV.merge("PATH" => (dirs + [ENV.fetch("PATH", "")]).join(File::PATH_SEPARATOR))
+    end
+
+    def report_missing_tools(tools, missing)
+      commands = missing.map { |name| "`#{AotToolchain::TOOLS[name].command}`" }
+      list = commands.size > 1 ? "#{commands[0..-2].join(", ")} and #{commands[-1]}" : commands.first
+      error "--roundhouse needs #{list}, which #{missing.size == 1 ? "was" : "were"} not found."
+      STDERR.puts
+      STDERR.puts AotToolchain.install_instructions(missing)
+      STDERR.puts
+
+      if tools[:roundhouse]
+        @env = child_env(tools)
+        print_check(tools[:roundhouse], "Meanwhile, Roundhouse's analysis of #{display(@app)}:")
+      else
+        STDERR.puts "Once Roundhouse is installed, `roundhouse check --continue #{display(@app)}` lists the gems"
+        STDERR.puts "and constructs of the app it does not cover yet; OCRAN shows it when a build fails."
+      end
+      raise "the Roundhouse toolchain is not installed"
+    end
+
+    def transpile_failed(tools, output, status, work)
+      print_failure("Roundhouse could not transpile #{display(@app)}", output, status)
+      print_check(tools[:roundhouse], "Roundhouse's analysis of the app:")
+      STDERR.puts
+      STDERR.puts "Things to try:"
+      STDERR.puts "  - what Roundhouse covers: #{AotToolchain::ROUNDHOUSE_URL}/blob/main/docs/guide/rails-coverage.md"
+      STDERR.puts "  - --roundhouse-opt --survey --roundhouse-opt --allow-unsupported transpiles an app that is"
+      STDERR.puts "    not fully covered yet, with a stub at each unsupported site"
+      STDERR.puts "  - the generated project so far is in #{work}"
+      raise "Roundhouse could not transpile #{display(@app)}"
+    end
+
+    def compile_failed(tools, output, status, work)
+      print_failure("Spinel could not compile the transpiled app (spin build)", output, status)
+
+      STDERR.puts "Things to check:"
+      versions = tools.map { |name, path| "#{name}: #{AotToolchain.version(path) || "version unknown"}" }
+      STDERR.puts "  - versions in use (#{versions.join("; ")}); each Roundhouse snapshot names the Spinel"
+      STDERR.puts "    release it was tested against in #{AotToolchain::ROUNDHOUSE_URL}/blob/main/RELEASES.md,"
+      STDERR.puts "    and a mismatch is the most common cause of a failing build"
+      missing_libs.each do |lib, package|
+        STDERR.puts "  - the #{lib} development headers seem to be missing (#{package})"
+      end
+      unlinked_libs(output).each do |lib|
+        STDERR.puts "  - the linker could not find lib#{lib}: install it (Debian/Ubuntu: lib#{lib}-dev; macOS: brew install #{lib});"
+        STDERR.puts "    if it is installed outside the linker's default directories, set LIBRARY_PATH to its lib directory"
+      end
+      STDERR.puts "  - the generated project is kept in #{File.join(work, "spinel")}; run `spin build` there to retry"
+      STDERR.puts "  - a compiler error in the generated code is a bug in Roundhouse or Spinel: please report it"
+      raise "Spinel could not compile the transpiled app"
+    end
+
+    def print_failure(heading, output, status)
+      lines = output.to_s.lines
+      exit_status = status ? "exit status #{status.exitstatus.inspect}" : "could not be started"
+      STDERR.puts "#{heading} (#{exit_status}):"
+      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
+    end
+
+    # Prints the useful part of `roundhouse check --continue`: the gem
+    # census (which gems Roundhouse does not model), the summary, the first
+    # errors and the punch list of unsupported constructs. The full report
+    # of a large app runs to thousands of lines.
+    def print_check(roundhouse, heading)
+      say "Analyzing #{display(@app)} with roundhouse check"
+      output, status = run([roundhouse, "check", "--continue", @app.to_s])
+      return STDERR.puts("(roundhouse check could not be run: #{output.to_s.strip})") unless status
+
+      lines = output.lines.map(&:chomp)
+      summary = lines.grep(/\Aroundhouse-check:/)
+      errors = lines.grep(/: error\[/)
+      survey_start = lines.index { |l| l.include?("Survey:") }
+      survey = survey_start ? lines[survey_start..].take_while { |l| !l.start_with?("roundhouse-check:") }.reject(&:empty?) : []
+
+      STDERR.puts heading
+      STDERR.puts
+      summary.each { |l| STDERR.puts "  #{l}" }
+      if summary.any? { |l| l.match?(/\d+ unknown/) && !l.match?(/\b0 unknown/) }
+        STDERR.puts "  (\"unknown\" gems are ones Roundhouse does not model: code using them cannot be compiled yet)"
+      end
+      unless errors.empty?
+        STDERR.puts
+        errors.first(MAX_CHECK_ERRORS).each { |l| STDERR.puts "  #{l}" }
+        STDERR.puts "  ... and #{errors.size - MAX_CHECK_ERRORS} more error(s)" if errors.size > MAX_CHECK_ERRORS
+      end
+      unless survey.empty?
+        STDERR.puts
+        survey.first(30).each { |l| STDERR.puts "  #{l}" }
+      end
+      STDERR.puts
+      STDERR.puts "  Full report: roundhouse check --continue #{display(@app)}"
+    end
+
+    # Libraries the generated project links that pkg-config cannot find,
+    # as [library, package hint] pairs. Empty when pkg-config is not there
+    # to ask.
+    def missing_libs
+      return [] unless AotToolchain.search_path("pkg-config")
+
+      { "sqlite3" => "libsqlite3-dev / brew install sqlite",
+        "jemalloc" => "libjemalloc-dev / brew install jemalloc" }.reject do |lib, _|
+        Kernel.system("pkg-config", "--exists", lib)
+      end.to_a
+    end
+
+    # Libraries the link step could not find, from GNU ld's
+    # "cannot find -lfoo" and Apple ld's "library 'foo' not found".
+    def unlinked_libs(output)
+      output.to_s.scan(/cannot find -l([\w.+-]+)|library '([\w.+-]+)' not found/).flatten.compact.uniq
+    end
+
+    def install(project)
+      bin_dir = File.join(project, "build", "bin")
+      binaries = Dir.glob(File.join(bin_dir, "*")).select { |f| File.file?(f) && File.executable?(f) }
+      binary = binaries.find { |f| File.basename(f, ".*") == @app.basename.to_s } || binaries.first
+      raise "spin build succeeded but produced no executable in #{bin_dir}" unless binary
+
+      @output.mkpath
+      target = @output + File.basename(binary)
+      FileUtils.cp(binary, target)
+      File.chmod(0o755, target)
+
+      RUNTIME_DIRS.each do |dir|
+        source = File.join(project, dir)
+        next unless File.directory?(source)
+
+        FileUtils.rm_rf(@output + dir)
+        FileUtils.cp_r(source, @output + dir)
+      end
+      # storage/ holds the database and uploads, so a rebuild keeps it.
+      (@output + "storage").mkpath
+
+      seed_database
+      say "Finished building #{display(@output)}"
+      say "Run it with: cd #{display(@output)} && ./#{File.basename(binary)}  (serves on port 3000; PORT or -p to change)"
+      say "It needs libsqlite3 and libjemalloc at run time (Debian/Ubuntu: libsqlite3-0 libjemalloc2)."
+    end
+
+    # Creates the database from the generated seed on the first build, when
+    # the sqlite3 command is there to do it.
+    def seed_database
+      seed = @output + "db" + "seed.sql"
+      database = @output + "storage" + "development.sqlite3"
+      return unless seed.file? && !database.exist?
+
+      sqlite3 = AotToolchain.search_path("sqlite3")
+      unless sqlite3
+        say "Create the database before the first start: sqlite3 storage/development.sqlite3 < db/seed.sql"
+        return
+      end
+
+      verbose "Seeding #{database} from #{seed}"
+      unless Kernel.system(sqlite3, database.to_s, in: seed.to_s)
+        warning "Could not create the database from #{seed}; run: sqlite3 storage/development.sqlite3 < db/seed.sql"
+      end
+    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/runner.rb

@@ -6,8 +6,19 @@ module Ocran
     load File.expand_path("command_output.rb", __dir__)
     include CommandOutput
 
-    def fatal_error(statement)
-      error statement
+    # Errors that describe a problem with the input or the build host - an
+    # invalid option, a missing file, a path OCRAN cannot write, a value too
+    # large for the executable format - rather than a bug in OCRAN. They
+    # are reported by their message; a backtrace would only bury it. Any
+    # other exception is a bug and keeps Ruby's full report.
+    USER_ERRORS = [RuntimeError, ArgumentError, SystemCallError, IOError].freeze
+
+    # Reports a USER_ERRORS exception and exits. With --verbose the
+    # backtrace is shown too, for when the message is not enough.
+    def user_error(e)
+      message = e.instance_of?(RuntimeError) ? e.message : "#{e.message} (#{e.class})"
+      error message
+      STDERR.puts e.backtrace.map { |line| "\tfrom #{line}" } if @option&.verbose? && e.backtrace
       exit false
     end
 
@@ -18,11 +29,9 @@ module Ocran
       load File.expand_path("option.rb", __dir__)
       @option = Option.new.tap do |opt|
         opt.parse(ARGV)
-      rescue RuntimeError => e
-        # Capture RuntimeError during parsing and display an appropriate
-        # error message to the user. This error usually occurs from invalid
-        # option arguments.
-        fatal_error e.message
+      rescue *USER_ERRORS => e
+        # Invalid option arguments, usually; report them as such.
+        user_error e
       else
         # Update ARGV with the parsed command line arguments to pass to
         # the user's script. This ensures the script executes based on
@@ -31,6 +40,7 @@ module Ocran
       end
 
       Ocran.option = @option
+      @option.warnings.each { |message| warning message }
 
       @ignore_modules = ObjectSpace.each_object(Module).to_a
     end
@@ -206,6 +216,24 @@ module Ocran
     end
 
     def build
+      # Native compilation hands the source to an ahead-of-time compiler, and
+      # --wasm to a WebAssembly runtime; nothing was loaded, and none of the
+      # packaging below applies.
+      if @option.spinel? || @option.roundhouse? || @option.wasm_runtime
+        Dir.chdir(@pre_env.pwd)
+        if @option.wasm_runtime
+          require_relative "wasm_builder"
+          WasmBuilder.new(@option).build
+        elsif @option.roundhouse?
+          require_relative "roundhouse_builder"
+          RoundhouseBuilder.new(@option).build
+        else
+          require_relative "spinel_builder"
+          SpinelBuilder.new(@option).build
+        end
+        return
+      end
+
       # If the script was run and autoload is enabled, attempt to autoload libraries.
       if @option.force_autoload?
         attempt_load_autoload(@ignore_modules)
@@ -226,8 +254,10 @@ module Ocran
 
       if @option.use_inno_setup?
         # Native on Windows; on POSIX allow it when an ISCC command is
-        # available (e.g. via Wine wrapper scripts or in tests).
-        if Gem.win_platform? || system("command -v ISCC > /dev/null 2>&1")
+        # available (e.g. via Wine wrapper scripts or in tests). Checked
+        # here, before the files are collected, so a missing ISCC fails fast.
+        require_relative "inno_setup_script_builder"
+        if InnoSetupScriptBuilder.iscc_available?
           direction.build_inno_setup_installer
         else
           raise "Inno Setup is only supported on Windows (no ISCC command found in PATH)"
@@ -238,13 +268,15 @@ module Ocran
         direction.build_output_dir(@option.output_dir)
       elsif @option.output_zip
         direction.build_zip(@option.output_zip)
+      elsif @option.static_runtime?
+        direction.build_static_runtime_exe
       elsif @option.cosmo_zip?
         direction.build_cosmo_zip_exe
       else
         direction.build_stab_exe
       end
-    rescue RuntimeError => e
-      fatal_error e.message
+    rescue *USER_ERRORS => e
+      user_error e
     end
   end
 end

data/lib/ocran/runtime_sdk.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+require "pathname"
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+require "json"
+require_relative "pe_imports"
+
+module Ocran
+  # The SDK part of a static runtime (<runtime>/sdk, written by
+  # runtime/make-sdk.rb): what is needed to link the runtime again with more
+  # C extensions statically linked in - its link inputs and link command
+  # (link.args), Ruby's headers, the runtime's rbconfig.rb with the
+  # <arch>-fake.rb Ruby's cross builds use to describe the target, and the
+  # gem extensions already linked in (exts/*.line).
+  #
+  # Linking needs a compiler for the runtime's target on the build host. For
+  # a MinGW runtime (toolchain "gcc" in sdk.json): the one link.args names
+  # (e.g. x86_64-w64-mingw32ucrt-gcc on Linux), or OCRAN_RUNTIME_CC (e.g. gcc
+  # from RubyInstaller's MSYS2 on Windows). For an mswin runtime ("msvc"):
+  # cl and nmake of Visual Studio (Build Tools), from a developer prompt.
+  class RuntimeSdk
+    BUILD_STATIC_EXT = File.expand_path("static_runtime/build_static_ext.rb", __dir__)
+
+    # One statically built extension: the feature it provides ("bcrypt_ext"),
+    # its Init function, the static library and the libraries it links with.
+    Extension = Struct.new(:feature, :init, :archive, :libs) do
+      def self.parse(line, base)
+        feature, init, archive, libs = line.strip.split(" ", 4)
+        raise "bad extension line #{line.inspect}" unless feature&.match?(%r{\A[\w/.-]+\z}) && init&.match?(/\A\w+\z/)
+
+        new(feature, init, File.expand_path(archive.sub("@SDK@", base.to_s)), libs.to_s.split(","))
+      end
+    end
+
+    attr_reader :dir, :arch, :toolchain
+
+    def initialize(dir, arch:)
+      @dir = Pathname(dir)
+      @arch = arch
+      raise "#{@dir} is not a static runtime SDK (no link.args)" unless (@dir / "link.args").file?
+
+      @info = (@dir / "sdk.json").file? ? JSON.parse((@dir / "sdk.json").read) : {}
+      @toolchain = @info.fetch("toolchain", "gcc")
+    end
+
+    # Libraries available as DLLs instead of linked in (--runtime-dll):
+    # name ("sybdb") => { "dll" => ..., "import" => ... }, relative to the SDK.
+    def dlls = @info.fetch("dlls", {})
+
+    # extconf.rb options for gems whose C library the SDK provides, so that
+    # extconf.rb uses it instead of downloading and building its own.
+    GEM_EXTCONF_ARGS = {
+      "nokogiri" => ["--use-system-libraries"],
+      "tiny_tds" => ["--with-freetds-dir=@SDK_DEPS@"],
+    }.freeze
+
+    def extconf_args(gem_name)
+      (GEM_EXTCONF_ARGS[gem_name] || []).map { |a| a.gsub("@SDK_DEPS@", (@dir / "deps").to_s) }
+    end
+
+    def msvc? = @toolchain == "msvc"
+
+    # True when the application archive cannot be appended to the
+    # executable but is linked in as the section __OCRAN,__zip (macOS, where
+    # appended data would break the code signature).
+    def section_payload? = @info["payload"] == "section"
+
+    def link_args = (@dir / "link.args").read.lines(chomp: true).map { |a| a.gsub("@SDK@", @dir.to_s) }
+
+    # The SDK's header directories, ahead of whatever an extconf.rb adds:
+    # the SDK's libraries are the ones linked, so their headers must win
+    # over a system copy (nokogiri adds the libxml2 headers of Apple's SDK,
+    # an older libxml2, on macOS).
+    def sdk_include_flags
+      deps = @dir / "deps" / "include"
+      [deps, deps / "libxml2"].select(&:directory?).map { |dir| "-I#{dir}" }
+    end
+
+    # The C compiler driver of the target.
+    def cc
+      return "cl" if msvc?
+
+      env = ENV["OCRAN_RUNTIME_CC"]
+      env && !env.empty? ? env : link_args.first
+    end
+
+    # The gem extensions already linked into the runtime.
+    def base_extensions
+      Dir[(@dir / "exts/*.line").to_s].sort.map { |f| Extension.parse(File.read(f), @dir) }
+    end
+
+    # Fails early, with a hint, when the build host has no compiler for the
+    # runtime's target.
+    def check_toolchain!
+      return check_msvc! if msvc?
+
+      out, status = Open3.capture2e(cc, "-dumpmachine")
+      expected = @info["dumpmachine"]
+      return if status.success? && (expected.nil? || out.include?(expected))
+
+      raise "#{cc} #{status.success? ? "does not target #{expected} (#{out.strip})" : "did not run"}; " \
+            "set OCRAN_RUNTIME_CC to #{toolchain_hint}"
+    rescue SystemCallError
+      raise "#{cc} not found; set OCRAN_RUNTIME_CC to #{toolchain_hint}"
+    end
+
+    def toolchain_hint
+      target_os = @info.fetch("target_os", "mingw32")
+      if target_os.start_with?("darwin")
+        return "clang from Xcode or the Command Line Tools (xcode-select --install)"
+      end
+      if target_os.start_with?("mingw")
+        "a MinGW-w64 UCRT C compiler (on Linux: gcc-mingw-w64-ucrt64, on Windows: RubyInstaller's " \
+          "MSYS2, e.g. ucrt64/bin/gcc.exe)"
+      else
+        "a musl C compiler (musl-gcc from musl-tools)"
+      end
+    end
+
+    def check_msvc!
+      %w[cl nmake].each do |tool|
+        Open3.capture2e(tool, "-?")
+      rescue SystemCallError
+        raise "#{tool} not found: building C extensions for an mswin runtime needs Visual Studio " \
+              "(Build Tools); run ocran from a \"x64 Native Tools\" developer prompt"
+      end
+    end
+
+    # Compiles the C extension in +ext_dir+ (a gem's ext/<name>/, with its
+    # extconf.rb) to a static library under +work_dir+. +gem_path+: more
+    # gem directories for the gems extconf.rb itself uses.
+    def build_extension(ext_dir, work_dir, *extconf_args, gem_path: [])
+      pkgconfig = File.join(work_dir.to_s + ".pkgconfig")
+      FileUtils.mkdir_p(pkgconfig)
+      Dir[(@dir / "deps/lib/pkgconfig/*.pc").to_s].each do |pc|
+        File.write(File.join(pkgconfig, File.basename(pc)), File.read(pc).gsub("@SDK_DEPS@", (@dir / "deps").to_s))
+      end
+      # The SDK's rbconfig.rb is found first on the load path; a MinGW SDK
+      # also has Ruby's <arch>-fake.rb, which makes any Ruby pose as the
+      # runtime's (an mswin build host runs the runtime's own revision).
+      fake = Dir[(@dir / "*-fake.rb").to_s].first
+      env = { "RUBYOPT" => nil, "BUNDLE_GEMFILE" => nil, "BUNDLER_SETUP" => nil,
+              "OCRAN_RUNTIME_CC" => msvc? ? nil : ENV["OCRAN_RUNTIME_CC"] || (cc == link_args.first ? nil : cc),
+              "OCRAN_RUNTIME_LIBS" => @info.fetch("libs", []).join(" "),
+              "OCRAN_RUNTIME_CPPFLAGS" => (sdk_include_flags + @info.fetch("cppflags", [])).join(" "),
+              "PKG_CONFIG_LIBDIR" => pkgconfig, "PKG_CONFIG_PATH" => "",
+              # Build-time gems extconf.rb uses (nokogiri: mini_portile2):
+              # the build host's, which the target's RbConfig would hide.
+              "GEM_HOME" => Gem.dir, "GEM_PATH" => (gem_path + Gem.path).join(File::PATH_SEPARATOR) }
+      cmd = [RbConfig.ruby, "--disable=gems", "-I", @dir.to_s, *(fake ? ["-r", fake] : []), BUILD_STATIC_EXT,
+             (@dir / "include").to_s, (@dir / "include" / @arch).to_s, ext_dir.to_s, work_dir.to_s, *extconf_args]
+      out, status = Open3.capture2e(env, *cmd)
+      unless status.success?
+        raise "Building the C extension in #{ext_dir} for the static runtime failed:\n#{out.lines.last(25).join}"
+      end
+
+      Extension.parse(out.lines.last, @dir)
+    end
+
+    # Links the runtime with the given extensions registered in addition to
+    # those it already has, into +output+. Libraries named in +dlls+ are
+    # linked against their DLL instead of statically (see #dll_files).
+    # macOS: the application archive is linked in as a section (see
+    # #section_payload?); +archive+ is that file.
+    def link(extensions, output, dlls: [], archive: nil)
+      unknown = dlls - self.dlls.keys
+      unless unknown.empty?
+        raise "No DLL build of #{unknown.join(", ")} in #{@dir} (available: #{self.dlls.keys.join(", ")})"
+      end
+      as_dll = dlls.to_h { |name| ["-l#{name}", (@dir / self.dlls[name]["import"]).to_s] }
+      all = base_extensions + extensions
+      Dir.mktmpdir do |tmp|
+        src = File.join(tmp, "ocran_exts.c")
+        File.write(src, exts_source(all))
+        obj = File.join(tmp, msvc? ? "ocran_exts.obj" : "ocran_exts.o")
+        if msvc?
+          run("cl", "-nologo", "-MT", "-O2", "-c", src, "-Fo#{obj}")
+        else
+          run(cc, "-O2", "-c", src, "-o", obj)
+        end
+
+        extra = [obj] + all.flat_map { |ext| [ext.archive, *ext.libs] } + @info.fetch("libs", [])
+        args = link_args
+        args[0] = cc
+        cmd = args.flat_map { |a| a == "@EXTRA@" ? extra : [a.gsub("@OUTPUT@", output.to_s)] }
+        cmd = cmd.map { |a| as_dll.fetch(a, a) }
+        cmd += ["-o", output.to_s] unless args.any? { |a| a.include?("@OUTPUT@") }
+        cmd += ["-Wl,-sectcreate,__OCRAN,__zip,#{archive}"] if archive
+        run(*cmd)
+      end
+      strip = strip_tool
+      run(strip, output.to_s) if strip
+      output
+    end
+
+    # The strip of the compiler in use: sdk.json names the SDK build host's
+    # (nil on macOS, where stripping would break the signature), which
+    # another compiler named with OCRAN_RUNTIME_CC may not come with (MSYS2
+    # has gcc and strip, not x86_64-w64-mingw32ucrt-strip).
+    def strip_tool
+      return nil if msvc? || (@info.key?("strip") && @info["strip"].nil?)
+
+      derived = cc.sub(/gcc(\.exe)?\z/) { "strip#{$1}" } if cc.match?(/gcc(\.exe)?\z/)
+      return derived if derived && cc != link_args.first
+
+      @info["strip"] || derived
+    end
+
+    # The DLL files to ship next to the executable for +dlls+: each named
+    # library's DLL and the SDK DLLs it imports in turn (libsybdb-5.dll
+    # needs libiconv-2.dll).
+    def dll_files(dlls)
+      by_file = self.dlls.values.to_h { |d| [File.basename(d["dll"]).downcase, @dir / d["dll"]] }
+      queue = dlls.map { |name| @dir / self.dlls.fetch(name)["dll"] }
+      found = {}
+      until queue.empty?
+        dll = queue.shift
+        next if found[dll.basename.to_s.downcase]
+
+        found[dll.basename.to_s.downcase] = dll
+        PEImports.dll_names(dll.to_s).each { |name| queue << by_file[name.downcase] if by_file[name.downcase] }
+      end
+      found.values
+    end
+
+    private
+
+    def exts_source(extensions)
+      <<~C
+        /* generated by ocran (Ocran::RuntimeSdk) */
+        void ruby_init_ext(const char *name, void (*init)(void));
+        #{extensions.map { |e| "extern void #{e.init}(void);" }.join("\n")}
+        void ocran_init_extra_exts(void)
+        {
+        #{extensions.map { |e| "    ruby_init_ext(\"#{e.feature}.so\", #{e.init});" }.join("\n")}
+        }
+      C
+    end
+
+    # Compilers, linkers and strip run with SOURCE_DATE_EPOCH set: binutils
+    # then writes that, not the current time, into a PE header it rewrites
+    # (strip does), so that the same application links to the same bytes.
+    def run(*cmd)
+      out, status = Open3.capture2e({ "SOURCE_DATE_EPOCH" => ENV["SOURCE_DATE_EPOCH"] || "1767225600" }, *cmd)
+      raise "#{cmd.first} failed:\n#{out.lines.last(25).join}" unless status.success?
+
+      out
+    end
+  end
+end