vcdeps 0.1.0

data/lib/vcdeps/vendor.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+require "vcdeps/version"
+
+module Vcdeps
+  # Syncs an Installed's runtime DLLs, per-port copyright files, and a standalone
+  # Fiddle-preload shim into a vendor directory (§2.2/§2.7). This is a SYNC, not
+  # a copy: vendor! OWNS <into>\*.dll, <into>\licenses\* and <into>\preload.rb —
+  # it overwrites the computed write list and DELETES any owned file no longer on
+  # it (so a port removed from vcpkg.json leaves no stale DLL the shim would
+  # preload and the precompiled-gem glob would ship). Nothing else under `into`
+  # is touched, so authors may keep unrelated assets there.
+  module Vendor
+    module_function
+
+    SHIM_NAME = "preload.rb"
+    LICENSES_DIR = "licenses"
+
+    # Returns the list of files written (absolute, backslashed). See §2.2 for the
+    # four-case table; stale owned files are deleted whenever `into` exists.
+    def sync!(installed, into:, licenses: true, shim: true, out: $stderr)
+      dlls = installed.dlls
+      copyrights = licenses ? installed.copyright_files : {}
+
+      # The write plan: a DLL is vendored only when there is something to vendor;
+      # the shim is written only when DLLs exist; licenses ship whenever copyright
+      # files exist (including static-md, where there are no DLLs).
+      write_dlls   = dlls
+      write_shim   = shim && !dlls.empty?
+      write_copies = copyrights
+
+      # Nothing to write AND nothing to clean (into absent) -> [] without
+      # creating `into` (§2.2 last case).
+      if write_dlls.empty? && write_copies.empty? && !write_shim &&
+         !File.directory?(into)
+        return []
+      end
+
+      written = []
+      FileUtils.mkdir_p(into)
+
+      # Owned DLLs we intend to keep (base names), for the stale sweep.
+      kept_dll_names = []
+      write_dlls.each do |src|
+        base = File.basename(src)
+        dest = File.join(into, base)
+        FileUtils.cp(src, dest)
+        kept_dll_names << base.downcase
+        written << win(dest)
+        warn_on_ruby_bin_collision(base, out)
+      end
+
+      # Licenses.
+      kept_license_names = []
+      unless write_copies.empty?
+        ldir = File.join(into, LICENSES_DIR)
+        FileUtils.mkdir_p(ldir)
+        write_copies.each do |port, src|
+          dest = File.join(ldir, "#{port}-copyright.txt")
+          FileUtils.cp(src, dest)
+          kept_license_names << File.basename(dest).downcase
+          written << win(dest)
+        end
+      end
+
+      # Shim.
+      shim_path = File.join(into, SHIM_NAME)
+      if write_shim
+        File.write(shim_path, shim_source)
+        written << win(shim_path)
+      end
+
+      # Stale sweep of OWNED files only.
+      sweep_stale!(into, kept_dll_names, kept_license_names, write_shim)
+
+      written
+    end
+
+    # The generated preload shim (exact §2.7 template). Standalone: stdlib only,
+    # no vcdeps require, safe to require twice, safe with zero DLLs present.
+    def shim_source
+      <<~SHIM
+        # frozen_string_literal: true
+        #
+        # Generated by vcdeps #{Vcdeps::VERSION}. Do not edit; regenerate with `vcdeps vendor`.
+        #
+        # Preloads the vendored vcpkg runtime DLLs by ABSOLUTE path before the C
+        # extension loads. Windows resolves an extension's dependent DLLs via the
+        # standard search order, which checks the loaded-module list (step 4) long
+        # before PATH (step 12) and NEVER checks the .so's own directory — so loading
+        # each DLL here, by full path, is what makes `require "<gem>/<gem>"` work.
+        #
+        # The dlopen handles are intentionally leaked for process lifetime: the DLLs
+        # must stay loaded as long as the extension is loaded.
+        require "fiddle"
+
+        pending = Dir[File.join(__dir__, "*.dll")].sort
+        until pending.empty?
+          progressed = false
+          pending.delete_if do |dll|
+            Fiddle.dlopen(dll)
+            progressed = true
+            true
+          rescue Fiddle::DLError
+            false   # depends on a sibling not yet loaded — retry next pass
+          end
+          break unless progressed   # truly unloadable; let the require raise its own LoadError
+        end
+      SHIM
+    end
+
+    # --- internals -----------------------------------------------------------
+
+    # Delete any *.dll directly in `into` not on the kept list, any licenses\*
+    # file not kept, and a stale shim when no shim is being written.
+    def sweep_stale!(into, kept_dll_names, kept_license_names, write_shim)
+      Dir[File.join(into.tr("\\", "/"), "*.dll")].each do |dll|
+        File.delete(dll) unless kept_dll_names.include?(File.basename(dll).downcase)
+      end
+
+      ldir = File.join(into.tr("\\", "/"), LICENSES_DIR)
+      if File.directory?(ldir)
+        Dir[File.join(ldir, "*")].each do |f|
+          next unless File.file?(f)
+
+          File.delete(f) unless kept_license_names.include?(File.basename(f).downcase)
+        end
+        # Remove an empty licenses dir we no longer populate.
+        begin
+          Dir.rmdir(ldir) if Dir.empty?(ldir)
+        rescue SystemCallError
+          nil
+        end
+      end
+
+      shim = File.join(into.tr("\\", "/"), SHIM_NAME)
+      File.delete(shim) if !write_shim && File.exist?(shim)
+    end
+
+    # Warn when a vendored DLL base name also exists in Ruby's bindir
+    # (zlib1.dll/ffi-8.dll/yaml.dll shadowing, R§9.2) — first-loaded wins.
+    def warn_on_ruby_bin_collision(base, out)
+      bindir = RbConfig::CONFIG["bindir"].to_s
+      return if bindir.empty?
+
+      ruby_copy = File.join(bindir, base)
+      return unless File.exist?(ruby_copy)
+
+      out&.puts("[vcdeps] WARNING: #{base} also ships in #{bindir.tr('/', '\\')} " \
+                "— the copy loaded first wins process-wide; preload.rb runs " \
+                "first under normal require order.")
+    end
+
+    def win(path)
+      path.nil? ? path : path.tr("/", "\\")
+    end
+  end
+end

data/lib/vcdeps/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Vcdeps
+  VERSION = "0.1.0"
+end

data/lib/vcdeps.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "fileutils"
+require "tmpdir"
+require "vcdeps/version"
+
+# vcdeps — vcpkg-powered native dependencies for Ruby C extensions on Windows
+# (MSVC). Declare ports in a manifest, get correct mkmf flags and loadable
+# runtime DLLs, no global state. Companion to vcvars (the toolchain) the way
+# vcpkg is companion to MSVC.
+#
+#   # in ext/<gem>/extconf.rb, after require "mkmf":
+#   require "vcdeps/mkmf"
+#   Vcdeps.mkmf!(vendor: File.expand_path("../../lib/foo/vendor", __dir__))
+#
+# Library use:
+#
+#   require "vcdeps"
+#   inst = Vcdeps.install!(manifest: "ext/foo")
+#   Vcdeps.vendor!(inst, into: "lib/foo/vendor")
+#
+# Windows MSVC (mswin) Ruby only. Pure Ruby — no compiler required to install.
+module Vcdeps
+  class Error          < StandardError; end # root; everything vcdeps raises
+  class ToolNotFound   < Error; end         # no usable vcpkg anywhere
+  class BootstrapError < Error; end         # private bootstrap failed
+  class ManifestError  < Error; end         # vcpkg.json missing/unparsable/no baseline
+  class TripletError   < Error; end         # unknown arch, static-CRT triplet, arch mismatch
+
+  # `vcpkg install` exited nonzero. Carries the exact failing argv, the child
+  # exit status, and the last <= 4000 chars of combined output (UTF-8 scrubbed).
+  class InstallError < Error
+    attr_reader :command, :status, :log_tail
+
+    def initialize(message, command:, status:, log_tail:)
+      super(message)
+      @command = command
+      @status = status
+      @log_tail = log_tail
+    end
+  end
+
+  module_function
+
+  # The vcdeps state root: ENV["VCDEPS_HOME"] or %LOCALAPPDATA%\vcdeps.
+  # Deliberately a SHORT path (vcpkg port builds break in deep trees, R§7).
+  def home
+    base = ENV["VCDEPS_HOME"]
+    base = File.join(ENV["LOCALAPPDATA"] || Dir.tmpdir, "vcdeps") if base.nil? || base.empty?
+    base.tr("/", "\\")
+  end
+
+  # Triplet for this Ruby (x64 -> "x64-windows", arm64 -> "arm64-windows", ...).
+  # Raises Vcdeps::TripletError for an unrecognized arch.
+  def default_triplet(arch = RbConfig::CONFIG["arch"])
+    Triplet.default(arch)
+  end
+
+  # Locate a usable vcpkg (§2.3 resolution order). Returns a Tool or nil; with
+  # bootstrap: true a miss bootstraps a private instance instead of nil.
+  def tool(bootstrap: false, out: $stderr)
+    ToolFinder.find(bootstrap: bootstrap, out: out)
+  end
+
+  # tool(), but raises Vcdeps::ToolNotFound (with the three remedies) on a miss.
+  # Default consent for bootstrap comes from ENV so `gem install` can be
+  # unblocked without editing anything.
+  def tool!(bootstrap: ENV["VCDEPS_BOOTSTRAP"] == "1", out: $stderr)
+    found = tool(bootstrap: bootstrap, out: out)
+    return found if found
+
+    raise ToolNotFound, <<~MSG.strip
+      vcdeps: no usable vcpkg found. Pick one of:
+        (a) Install the VS "vcpkg package manager" component
+            (Microsoft.VisualStudio.Component.Vcpkg) — it is Recommended (not
+            Required) in the "Desktop development with C++" workload, so a
+            cl-capable box can still lack it.
+        (b) Set VCPKG_ROOT to an existing vcpkg instance.
+        (c) Run `vcdeps bootstrap` (or set VCDEPS_BOOTSTRAP=1 for non-interactive
+            installs).
+      See `vcdeps doctor` for details.
+    MSG
+  end
+
+  # Create the private, registration-free vcpkg instance under <home>\vcpkg
+  # (the vcpkg-init mechanism, R§2.4). Idempotent. Raises BootstrapError.
+  def bootstrap!(out: $stderr)
+    require "vcdeps/bootstrap"
+    Bootstrap.run!(out: out)
+  end
+
+  # Run `vcpkg install` for <manifest>\vcpkg.json into <home>\installed\<key>.
+  # Streams combined output to `out` (nil to silence). Fast path: a present
+  # .vcdeps-complete marker means the install is provably current and vcpkg is
+  # not invoked (force: true bypasses it). Triplet precedence: kwarg >
+  # ENV["VCDEPS_TRIPLET"] > default_triplet.
+  #
+  # Raises ManifestError / TripletError / ToolNotFound / InstallError.
+  def install!(manifest: Dir.pwd, triplet: nil, tool: nil, force: false, out: $stderr)
+    manifest_dir = File.expand_path(manifest)
+
+    # Pre-flight the manifest BEFORE locating the tool (a missing vcpkg.json or
+    # missing baseline must never invoke vcpkg, §5.1/§5.2).
+    Manifest.load!(manifest_dir)
+
+    resolved_triplet = resolve_triplet(triplet)
+    Triplet.validate!(resolved_triplet)
+
+    resolved_tool = tool || tool!(out: out)
+
+    key = Manifest.key(manifest_dir, resolved_triplet, resolved_tool.version)
+    install_root = File.join(home, "installed", key).tr("/", "\\")
+
+    installed = Installed.new(root: install_root, triplet: resolved_triplet,
+                              manifest_dir: manifest_dir, key: key, tool: resolved_tool)
+
+    # Fast path: marker present and not forced.
+    return installed if !force && Runner.marker_present?(install_root)
+
+    FileUtils.mkdir_p(install_root)
+    command = Runner.install_args(resolved_tool.exe, resolved_triplet,
+                                  manifest_dir, install_root, home)
+    Runner.run_install(command, env: Runner.child_env(resolved_tool.root),
+                       chdir: manifest_dir, out: out)
+    Runner.write_marker!(install_root, key, resolved_tool.version)
+
+    installed
+  end
+
+  # Sync an Installed's runtime DLLs (+ copyright files, + preload shim) into
+  # `into` (§2.2). SYNC, not copy: owns <into>\*.dll, <into>\licenses\* and
+  # <into>\preload.rb. Returns the list of files written.
+  def vendor!(installed, into:, licenses: true, shim: true, out: $stderr)
+    require "vcdeps/vendor"
+    Vendor.sync!(installed, into: File.expand_path(into),
+                 licenses: licenses, shim: shim, out: out)
+  end
+
+  # Write/update "builtin-baseline" in <manifest>\vcpkg.json by running
+  # `vcpkg x-update-baseline --add-initial-baseline` with chdir: manifest.
+  # Returns the resulting baseline SHA (re-read from the manifest).
+  # Raises ManifestError / ToolNotFound / InstallError.
+  def baseline!(manifest: Dir.pwd, tool: nil, out: $stderr)
+    manifest_dir = File.expand_path(manifest)
+    path = File.join(manifest_dir, Manifest::MANIFEST_NAME)
+    unless File.exist?(path)
+      raise ManifestError, "vcdeps: no manifest at #{path.tr('/', '\\')} to add a " \
+        "baseline to."
+    end
+
+    resolved_tool = tool || tool!(out: out)
+    command = [resolved_tool.exe, "x-update-baseline", "--add-initial-baseline"]
+    Runner.run(command, env: Runner.child_env(resolved_tool.root),
+               chdir: manifest_dir, out: out)
+
+    manifest = Manifest.read_json(path)
+    manifest["builtin-baseline"].to_s
+  end
+
+  # Triplet precedence for install! (kwarg > VCDEPS_TRIPLET > default).
+  def resolve_triplet(kwarg)
+    return kwarg if kwarg && !kwarg.to_s.empty?
+
+    env = ENV["VCDEPS_TRIPLET"]
+    return env if env && !env.empty?
+
+    default_triplet
+  end
+  private_class_method :resolve_triplet
+end
+
+require "vcdeps/triplet"
+require "vcdeps/tool"
+require "vcdeps/manifest"
+require "vcdeps/runner"
+require "vcdeps/installed"
+# NOTE: vcdeps/mkmf, vcdeps/vendor, vcdeps/bootstrap, vcdeps/doctor and
+# vcdeps/cli are required lazily (mkmf must never be loaded into a normal
+# process; the others are CLI-only or pulled in on first use).

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: vcdeps
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  vcdeps wires Microsoft's vcpkg package manager into mkmf: declare native
+  dependencies in ext/<gem>/vcpkg.json, call Vcdeps.mkmf! from extconf.rb, and
+  vcdeps locates (or bootstraps) vcpkg, installs the ports out of tree with the
+  correct dynamic-CRT triplet, prepends the include/lib paths so they win over
+  Ruby's own opt-dir, and vendors the runtime DLLs with a generated
+  Fiddle-preload shim so the built extension actually loads.
+
+  It provides a library API (install!/vendor!/baseline!/tool!), the extconf
+  entry point Vcdeps.mkmf!, and a CLI (vcdeps doctor/where/install/vendor/
+  baseline/bootstrap). Manifest mode only; builds and caches live under
+  %LOCALAPPDATA%\vcdeps, never inside the gem. Windows MSVC (mswin) Ruby
+  only. Pure Ruby — no compiler required to install vcdeps itself.
+executables:
+- vcdeps
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/vcdeps
+- lib/vcdeps.rb
+- lib/vcdeps/bootstrap.rb
+- lib/vcdeps/cli.rb
+- lib/vcdeps/doctor.rb
+- lib/vcdeps/installed.rb
+- lib/vcdeps/manifest.rb
+- lib/vcdeps/mkmf.rb
+- lib/vcdeps/runner.rb
+- lib/vcdeps/tool.rb
+- lib/vcdeps/triplet.rb
+- lib/vcdeps/vendor.rb
+- lib/vcdeps/version.rb
+homepage: https://github.com/main-path/vcdeps
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/vcdeps
+  source_code_uri: https://github.com/main-path/vcdeps
+  changelog_uri: https://github.com/main-path/vcdeps/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/vcdeps/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: vcpkg-powered native dependencies for Ruby C extensions on Windows (MSVC),
+  companion to vcvars.
+test_files: []