vcdeps 0.1.0

data/lib/vcdeps/manifest.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Vcdeps
+  # Reads, validates, and canonically hashes a vcpkg manifest directory. The
+  # install key (§2.5) is SHA256 over the canonicalized vcpkg.json +
+  # vcpkg-configuration.json + triplet + tool version, so the same inputs always
+  # map to the same out-of-tree install root and any change forces a fresh one.
+  module Manifest
+    module_function
+
+    MANIFEST_NAME      = "vcpkg.json"
+    CONFIGURATION_NAME = "vcpkg-configuration.json"
+
+    # Absolute path to <dir>\vcpkg.json (display-backslashed).
+    def manifest_path(dir)
+      File.join(dir, MANIFEST_NAME).tr("/", "\\")
+    end
+
+    def configuration_path(dir)
+      File.join(dir, CONFIGURATION_NAME)
+    end
+
+    # Read and JSON-parse a file with BOM tolerance (editors love BOMs).
+    # Returns the parsed Hash. Raises Vcdeps::ManifestError on a missing file or
+    # a JSON syntax error (carrying the parser's position message).
+    def read_json(path)
+      raw = File.read(path, encoding: "BOM|UTF-8")
+      JSON.parse(raw)
+    rescue Errno::ENOENT
+      raise ManifestError, "vcdeps: no manifest at #{path.tr('/', '\\')}. " \
+        "Create a vcpkg.json there (see `vcdeps doctor`)."
+    rescue JSON::ParserError => e
+      raise ManifestError, "vcdeps: #{File.basename(path)} is not valid JSON: " \
+        "#{e.message}"
+    end
+
+    # Pre-flight check (§5.1/§5.2): the manifest exists, parses, and either pins
+    # "builtin-baseline" OR has a vcpkg-configuration.json beside it (git-registry
+    # instances hard-fail otherwise). Returns the parsed manifest Hash.
+    def load!(dir)
+      path = File.join(dir, MANIFEST_NAME)
+      manifest = read_json(path)
+
+      unless manifest.is_a?(Hash)
+        raise ManifestError, "vcdeps: #{MANIFEST_NAME} must be a JSON object."
+      end
+
+      has_baseline = manifest.key?("builtin-baseline") &&
+                     !manifest["builtin-baseline"].to_s.empty?
+      has_config   = File.exist?(configuration_path(dir))
+
+      unless has_baseline || has_config
+        raise ManifestError, "vcdeps: #{manifest_path(dir)} has no " \
+          "\"builtin-baseline\" (required by git-registry vcpkg instances). " \
+          "Add one with: vcdeps baseline --manifest #{dir.tr('/', '\\')}"
+      end
+
+      manifest
+    end
+
+    # The 16-hex install key for (manifest dir, triplet, tool version) (§2.5).
+    def key(dir, triplet, tool_version)
+      manifest = read_json(File.join(dir, MANIFEST_NAME))
+      config_path = configuration_path(dir)
+      config = File.exist?(config_path) ? read_json(config_path) : nil
+
+      material = [
+        canonical(manifest),
+        config ? canonical(config) : "",
+        triplet.to_s,
+        tool_version.to_s
+      ].join("\0")
+
+      Digest::SHA256.hexdigest(material)[0, 16]
+    end
+
+    # Canonical JSON: recursively sort object keys, preserve array order,
+    # compact-generate. Two textually different but semantically identical
+    # manifests canonicalize identically.
+    def canonical(value)
+      JSON.generate(sort_value(value))
+    end
+
+    def sort_value(value)
+      case value
+      when Hash
+        value.keys.sort.each_with_object({}) do |k, h|
+          h[k] = sort_value(value[k])
+        end
+      when Array
+        value.map { |v| sort_value(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/vcdeps/mkmf.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# vcdeps/mkmf — the extconf.rb entry point. NEVER require this into a normal
+# process: it requires "mkmf", which mutates global build state. Load it only
+# from inside an extconf.rb, after `require "mkmf"` and the suite's mswin guard.
+#
+#   require "vcdeps/mkmf"
+#   Vcdeps.mkmf!(vendor: File.expand_path("../../lib/foo/vendor", __dir__))
+
+require "mkmf"
+require "vcvars"
+require "vcdeps"
+
+module Vcdeps
+  module_function
+
+  # Install the manifest's ports and wire mkmf so the compile/link see the vcpkg
+  # tree FIRST (defeating opt-dir shadowing, R§8.4). Behavior in order (§2.4):
+  #   1. Vcvars.activate! (idempotent) so mkmf's own try_compile probes work.
+  #   2. --with-vcdeps-dir bypass: skip vcpkg, wire a prebuilt <prefix>.
+  #   3. install! (manifest defaults to the extension SOURCE dir — $srcdir).
+  #   4. PREPEND -I to $INCFLAGS and unshift lib_dir onto $LIBPATH.
+  #   5. vendor! when vendor: is given; else warn loudly if DLLs went unvendored.
+  #
+  # triplet precedence: kwarg > --with-vcdeps-triplet= > VCDEPS_TRIPLET > default.
+  # Returns the Installed. Raises everything install!/vendor! raise.
+  def mkmf!(manifest: nil, triplet: nil, vendor: nil, force: false)
+    # 1. Toolchain: a Vcvars::Error propagates (no cl == doomed; message names
+    #    `vcvars doctor`). No-op when a dev env is already active (CI).
+    Vcvars.activate!
+
+    # triplet from --with-vcdeps-triplet (with_config) sits between kwarg and ENV.
+    cfg_triplet = mkmf_with_config("vcdeps-triplet")
+    resolved_triplet = triplet || (cfg_triplet unless cfg_triplet == true) || nil
+
+    # 2. Bypass: --with-vcdeps-dir=<prefix> wires a prebuilt tree, no vcpkg.
+    bypass = mkmf_with_config("vcdeps-dir")
+    installed =
+      if bypass && bypass != true
+        bypass_installed(File.expand_path(bypass), resolved_triplet)
+      else
+        manifest_dir = manifest || default_manifest_dir
+        install!(manifest: manifest_dir, triplet: resolved_triplet, force: force)
+      end
+
+    wire_mkmf!(installed)
+    handle_vendor(installed, vendor)
+
+    installed
+  end
+
+  # Wire mkmf: PREPEND the include dir to $INCFLAGS (it precedes $CPPFLAGS on the
+  # compile line) and unshift the lib dir onto $LIBPATH (renders before the
+  # opt-dir -libpath:). q() double-quotes a spaced path; $LIBPATH quoting is
+  # delegated to mkmf's libpathflag (verified to quote spaced paths).
+  def wire_mkmf!(installed)
+    inc = installed.include_dir
+    $INCFLAGS = "-I#{mkmf_quote(inc)} #{$INCFLAGS}"
+    $LIBPATH.unshift(installed.lib_dir)
+    installed
+  end
+
+  # Build an Installed for a --with-vcdeps-dir bypass (tool: nil; prefix taken
+  # as-is so include/lib/bin resolve under <prefix>; dlls from a bin\*.dll glob;
+  # ports: []).
+  def bypass_installed(prefix, triplet)
+    triplet ||= resolve_triplet_for_bypass
+    Installed.new(root: prefix, triplet: triplet, manifest_dir: prefix,
+                  key: "bypass", tool: nil, prefix: prefix)
+  end
+
+  # The extension SOURCE dir: File.expand_path($srcdir) when mkmf defined it
+  # (under rake-compiler cwd is tmp/<arch>/... while vcpkg.json sits beside
+  # extconf.rb — $srcdir is the correct anchor), else Dir.pwd.
+  def default_manifest_dir
+    srcdir = (defined?($srcdir) && $srcdir) ? $srcdir : nil
+    srcdir ? File.expand_path(srcdir) : Dir.pwd
+  end
+
+  # vendor! when a vendor dir is given; else loudly warn that the built .so will
+  # need these DLLs at runtime and the .so's own dir is not searched (R§9.1).
+  def handle_vendor(installed, vendor)
+    if vendor
+      vendor!(installed, into: vendor)
+    elsif !installed.dlls.empty?
+      warn <<~MSG
+        [vcdeps] WARNING: this build links #{installed.dlls.size} runtime DLL(s)
+        that are NOT vendored. The built extension will fail to load at runtime
+        ("LoadError: 126: The specified module could not be found") because
+        Windows does not search the .so's own directory for dependent DLLs.
+        Pass `vendor:` to Vcdeps.mkmf! (so vcdeps copies the DLLs + a preload
+        shim into your gem), or build with --with-vcdeps-triplet=x64-windows-static-md
+        to link the libraries statically and ship no DLLs.
+      MSG
+    end
+  end
+
+  # --- mkmf seams (kept tiny so tests can reason about them) ----------------
+
+  # Read a --with-<name>[=value] flag via mkmf's with_config. Returns the value,
+  # true (bare flag), or nil/false (absent). Wrapped so a non-mkmf context is
+  # tolerated in unit tests.
+  def mkmf_with_config(name)
+    return nil unless respond_to?(:with_config, true) || defined?(with_config)
+
+    with_config(name)
+  rescue StandardError
+    nil
+  end
+
+  # Double-quote a path containing spaces for a naked -I flag (§5.20). Already
+  # backslashed by Installed.
+  def mkmf_quote(path)
+    path.to_s.include?(" ") ? %("#{path}") : path.to_s
+  end
+
+  def resolve_triplet_for_bypass
+    env = ENV["VCDEPS_TRIPLET"]
+    return env if env && !env.empty?
+
+    default_triplet
+  end
+
+  private_class_method :resolve_triplet_for_bypass
+end

data/lib/vcdeps/runner.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "time"
+
+module Vcdeps
+  # The ONLY place a vcpkg argv is constructed and spawned. Every `--x-*` flag
+  # lives in `args` so an upstream rename is a one-line fix (R§3/§5.13), and the
+  # runner test pins the exact argv. Combined child output is streamed to `out`
+  # line by line (never silent during a multi-minute port build); on any abnormal
+  # unwind the child is TerminateProcess'd and reaped so vcpkg.exe never outlives
+  # the call (§3.2).
+  module Runner
+    module_function
+
+    MARKER_NAME = ".vcdeps-complete"
+    LOG_TAIL_MAX = 4000
+
+    # Build the `vcpkg install` argv (§5.13 pin). All `--x-*` roots redirect out
+    # of the gem tree into <home> (R§7 path-length trap).
+    def install_args(exe, triplet, manifest_dir, install_root, home)
+      [
+        exe,
+        "install",
+        "--triplet", triplet,
+        "--x-manifest-root=#{manifest_dir}",
+        "--x-install-root=#{install_root}",
+        "--x-buildtrees-root=#{File.join(home, 'blds')}",
+        "--x-packages-root=#{File.join(home, 'pkgs')}"
+      ]
+    end
+
+    # The child environment: telemetry OFF by default (a gem install must not
+    # phone home, §5.15), VCPKG_ROOT pinned to the tool's own root. All other
+    # vcpkg env (binary cache, downloads) passes through untouched (§5.18).
+    def child_env(tool_root)
+      env = {}
+      env["VCPKG_DISABLE_METRICS"] = "1" unless ENV["VCDEPS_METRICS"] == "1"
+      env["VCPKG_ROOT"] = tool_root if tool_root
+      env
+    end
+
+    # Run `vcpkg install`. Streams combined output to `out` (nil to silence),
+    # returns the captured combined output on success, raises InstallError on a
+    # nonzero exit. `command` is the full argv (already built by install_args).
+    def run_install(command, env:, chdir:, out:)
+      run(command, env: env, chdir: chdir, out: out)
+    end
+
+    # Generic streamed runner shared by install! and baseline!. Raises
+    # InstallError on nonzero exit; the network-failure hint (§5.17) is appended
+    # by the caller via install_error so this stays generic.
+    def run(command, env:, chdir:, out:)
+      combined = +""
+
+      Open3.popen2e(env, *command, chdir: chdir) do |_stdin, oe, wt|
+        pid = wt.pid
+        oe.binmode
+        begin
+          # Buffered each_line dispatches to a scheduler's io_read hook on mswin
+          # (§6); reads block in VM I/O with the GVL released. Scrub to UTF-8.
+          oe.each_line do |raw|
+            line = raw.dup.force_encoding("UTF-8").scrub("�")
+            combined << line
+            out&.print(line)
+            out&.flush if out.respond_to?(:flush)
+          end
+          status = wt.value
+          unless status.success?
+            raise InstallError.new(
+              install_error_message(command, status.exitstatus, combined),
+              command: command, status: status.exitstatus,
+              log_tail: log_tail(combined)
+            )
+          end
+        rescue InstallError
+          raise
+        rescue Exception # rubocop:disable Lint/RescueException
+          # ANY abnormal unwind (Interrupt, Timeout, a raise from the out block):
+          # kill THIS vcpkg.exe so its install-root lock handle is released. We
+          # do it HERE, before Open3's block teardown tries to drain the pipe
+          # (which would otherwise block on a still-running child). TerminateProcess
+          # is not recursive — helper processes vcpkg spawned may briefly survive
+          # (§3.2/§5.16). The pipe is then closed so the drain returns at once.
+          begin
+            Process.kill(:KILL, pid)
+          rescue Errno::ESRCH, RangeError
+            nil
+          end
+          begin
+            oe.close
+          rescue IOError
+            nil
+          end
+          raise
+        end
+      end
+
+      combined
+    end
+
+    # Last <= LOG_TAIL_MAX chars, UTF-8 scrubbed.
+    def log_tail(combined)
+      tail = combined.length > LOG_TAIL_MAX ? combined[-LOG_TAIL_MAX..] : combined
+      tail.to_s.dup.force_encoding("UTF-8").scrub("�")
+    end
+
+    # Compose the InstallError message, appending the offline hint when the
+    # output looks network-shaped (§5.17).
+    def install_error_message(command, status, combined)
+      msg = "vcdeps: `#{File.basename(command.first)} #{command[1]}` exited #{status}."
+      if combined =~ /(failed to (fetch|download)|could not resolve|network)/i
+        msg += " First install of this baseline requires network access; " \
+               "see `vcdeps doctor` checks 9-10."
+      end
+      msg
+    end
+
+    # ---- completion marker (§2.5) -------------------------------------------
+
+    def marker_path(install_root)
+      File.join(install_root, MARKER_NAME)
+    end
+
+    def marker_present?(install_root)
+      File.exist?(marker_path(install_root))
+    end
+
+    # Write the marker atomically: temp file then File.rename (atomic on NTFS).
+    def write_marker!(install_root, key, tool_version)
+      payload = JSON.generate(
+        "key" => key,
+        "tool_version" => tool_version.to_s,
+        "finished_at" => Time.now.utc.iso8601
+      )
+      final = marker_path(install_root)
+      tmp = "#{final}.tmp.#{Process.pid}"
+      File.write(tmp, payload)
+      File.rename(tmp, final)
+    ensure
+      File.unlink(tmp) if tmp && File.exist?(tmp) && !File.exist?(final)
+    end
+  end
+end

data/lib/vcdeps/tool.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "open3"
+require "vcvars"
+
+module Vcdeps
+  # Where a usable vcpkg lives. `source` is one of :env, :devenv, :vs, :actions,
+  # :private (see §2.2). `version` is the date stamp parsed from `vcpkg version`.
+  Tool = Struct.new(:exe, :root, :version, :source, keyword_init: true) do
+    # => "vcpkg 2026-02-21 (vs) at C:\...\VC\vcpkg"
+    def to_s
+      "vcpkg #{version || '?'} (#{source}) at #{root}"
+    end
+  end
+
+  # Locates a usable vcpkg instance (or bootstraps a private one). The
+  # resolution order and validation are the load-bearing integration logic
+  # (R§2.5): every candidate must have a real vcpkg.exe AND a ".vcpkg-root"
+  # marker before it is trusted, and a user-set VCPKG_INSTALLATION_ROOT that
+  # lies (runner-images #9269) is skipped rather than believed.
+  module ToolFinder
+    module_function
+
+    # The upstream standalone vcpkg.exe (the same artifact vcpkg-init downloads).
+    BOOTSTRAP_URL =
+      "https://github.com/microsoft/vcpkg-tool/releases/latest/download/vcpkg.exe"
+
+    # Memoized version per resolved exe path: avoids re-spawning `vcpkg version`.
+    def version_cache
+      @version_cache ||= {}
+    end
+
+    # Display-normalize to backslashes, like Vcvars::Locator.win.
+    def win(path)
+      path.nil? ? path : path.tr("/", "\\")
+    end
+
+    # A directory is a valid vcpkg root iff it holds vcpkg.exe AND a
+    # ".vcpkg-root" marker (R§2.2/R§2.3). Returns the absolute exe path or nil.
+    def valid_root(root)
+      return nil if root.nil? || root.to_s.empty?
+
+      exe = File.join(root, "vcpkg.exe")
+      marker = File.join(root, ".vcpkg-root")
+      return nil unless File.file?(exe) && File.exist?(marker)
+
+      File.expand_path(exe)
+    end
+
+    # Resolve a Tool, or nil. With bootstrap: true a miss bootstraps a private
+    # instance instead of returning nil. Resolution order is §2.3 steps 1-5.
+    def find(bootstrap: false, out: $stderr)
+      tool = resolve
+      return tool if tool
+      return nil  unless bootstrap
+
+      Vcdeps.bootstrap!(out: out)
+    end
+
+    # The five-step resolution (no bootstrap). Returns a Tool or nil.
+    def resolve
+      # 1. Explicit VCPKG_ROOT — explicit beats implicit.
+      if (exe = valid_root(ENV["VCPKG_ROOT"]))
+        return build_tool(exe, :env)
+      end
+
+      # 2. Activate vcvars (idempotent, mswin only, errors swallowed) and read
+      #    the VCPKG_ROOT the VS developer env sets. After activation the VS
+      #    bundle's VCPKG_ROOT is usually already present (R§2.1).
+      activate_vcvars_quietly
+      if (exe = valid_root(ENV["VCPKG_ROOT"]))
+        return build_tool(exe, :devenv)
+      end
+
+      # 3. Vcvars.locate.vs_path + "\VC\vcpkg" probed directly (covers a located
+      #    VS even if the activation env did not export the vcpkg extension).
+      if (vs = locate_vs_path) && (exe = valid_root(File.join(vs, "VC", "vcpkg")))
+        return build_tool(exe, :vs)
+      end
+
+      # 4. VCPKG_INSTALLATION_ROOT (GitHub Actions) — VALIDATED; a stale/wrong
+      #    value (issue #9269) is skipped, not trusted.
+      if (exe = valid_root(ENV["VCPKG_INSTALLATION_ROOT"]))
+        return build_tool(exe, :actions)
+      end
+
+      # 5. A previously bootstrapped private instance under <home>\vcpkg.
+      if (exe = valid_root(File.join(Vcdeps.home, "vcpkg")))
+        return build_tool(exe, :private)
+      end
+
+      nil
+    end
+
+    # Build a Tool for a resolved exe, reading (and memoizing) its version.
+    def build_tool(exe, source)
+      Tool.new(exe: win(exe), root: win(File.dirname(exe)),
+               version: read_version(exe), source: source)
+    end
+
+    # Parse the date stamp from `vcpkg version`'s first line:
+    #   "vcpkg package management program version 2026-02-21-<sha>..."
+    # -> "2026-02-21". Falls back to the whole token if the shape differs.
+    # Memoized per exe path.
+    def read_version(exe)
+      key = File.expand_path(exe)
+      return version_cache[key] if version_cache.key?(key)
+
+      version_cache[key] = capture_version(exe)
+    end
+
+    def capture_version(exe)
+      out, status = Open3.capture2(exe, "version")
+      return nil unless status&.success?
+
+      line = out.to_s.lines.first.to_s
+      # Grab a leading date "YYYY-MM-DD" from the version token if present.
+      if (m = line.match(/version\s+(\d{4}-\d{2}-\d{2})/))
+        m[1]
+      elsif (m = line.match(/(\d{4}-\d{2}-\d{2})/))
+        m[1]
+      else
+        line.strip.empty? ? nil : line.strip
+      end
+    rescue StandardError
+      nil
+    end
+
+    # Vcvars.activate! is idempotent and mswin-only; any failure here is not
+    # fatal to resolution (steps 3-5 may still find a tool), so swallow it.
+    def activate_vcvars_quietly
+      return unless Vcvars.mswin?
+
+      Vcvars.activate!
+    rescue StandardError
+      nil
+    end
+
+    def locate_vs_path
+      inst = Vcvars.locate
+      inst&.vs_path
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/vcdeps/triplet.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Vcdeps
+  # Derives the vcpkg triplet for the running Ruby and validates user-supplied
+  # triplets. The default is the dynamic-CRT, dynamic-library triplet that
+  # matches an `-MD` mswin Ruby (x64 -> "x64-windows"); static-CRT triplets are
+  # rejected (the LNK2005/dual-heap hazard, R§4).
+  #
+  # No "x64" literal lives in code: the architecture token is derived from
+  # RbConfig::CONFIG["arch"], so arm64-mswin derives "arm64-windows" for free.
+  module Triplet
+    module_function
+
+    # Maps a Ruby arch string to its vcpkg architecture token, or nil if
+    # unrecognized. Mirrors Vcvars::Doctor.arch's regexes.
+    #   "x64-mswin64_140"   -> "x64"
+    #   "arm64-mswin64_140" -> "arm64"
+    #   "i386-mswin32"      -> "x86"
+    def arch_token(arch)
+      a = arch.to_s
+      return "x64"   if a =~ /\A(?:x64|x86_64|amd64)/i
+      return "arm64" if a =~ /arm64|aarch64/i
+      return "x86"   if a =~ /\A(?:i[3-6]86|x86)/i
+      nil
+    end
+
+    # Known architecture prefixes a triplet may start with — used to detect an
+    # arch mismatch against the running Ruby.
+    ARCH_TOKENS = %w[x64 x86 arm64 arm].freeze
+
+    # The default triplet for the given Ruby arch (dynamic CRT, dynamic libs).
+    # Raises Vcdeps::TripletError for an unrecognized arch.
+    def default(arch = RbConfig::CONFIG["arch"])
+      token = arch_token(arch)
+      raise TripletError, "vcdeps: cannot derive a vcpkg triplet for arch " \
+        "#{arch.inspect} (recognized: x64, x86, arm64). Set VCDEPS_TRIPLET or " \
+        "pass --with-vcdeps-triplet=<triplet> explicitly." if token.nil?
+
+      "#{token}-windows"
+    end
+
+    # Validate a triplet against §2.6 and return it unchanged, or raise
+    # Vcdeps::TripletError. `arch` is the running Ruby's arch (for the mismatch
+    # check); pass it explicitly in tests to exercise the forward-compat path.
+    def validate!(triplet, arch: RbConfig::CONFIG["arch"])
+      t = triplet.to_s
+
+      unless t =~ /\A[a-z0-9][a-z0-9-]*\z/
+        raise TripletError, "vcdeps: invalid triplet #{triplet.inspect} " \
+          "(must match /\\A[a-z0-9][a-z0-9-]*\\z/). Run `vcdeps doctor`."
+      end
+
+      # Reject a static-CRT triplet (-static suffix). static-md (static libs +
+      # dynamic CRT) is fine; plain -static sets VCPKG_CRT_LINKAGE static.
+      if t =~ /-static\z/
+        raise TripletError, "vcdeps: triplet #{triplet.inspect} uses a STATIC " \
+          "CRT, which is ABI-incompatible with this -MD Ruby (LNK2005 / dual " \
+          "heap). Use #{t.sub(/-static\z/, '-static-md')} (static libs, dynamic " \
+          "CRT — no DLLs to vendor) or the default #{default(arch)}."
+      end
+
+      # If the triplet leads with a known arch token that differs from this
+      # Ruby's arch, it would LNK1112 at link time.
+      lead = t.split("-", 2).first
+      ruby_token = arch_token(arch)
+      if ARCH_TOKENS.include?(lead) && ruby_token && lead != ruby_token
+        raise TripletError, "vcdeps: triplet #{triplet.inspect} targets #{lead} " \
+          "but this Ruby is #{ruby_token} (#{arch}); linking would fail with " \
+          "LNK1112. Use a #{ruby_token}-* triplet (default #{default(arch)})."
+      end
+
+      t
+    end
+  end
+end