faster_path 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fb5780bd8ce8ea17d538b540ac69b1c023118d1351e167cde418ee48a4f8085
-  data.tar.gz: b12bc7a5ab8e4e26cfd46328bdb9e4b57eea367a9c40e76aeba74e12f06eb0e7
+  metadata.gz: fc913650b2f0738a6fd67abfadedea3bd40b91942a0743ef30e57ec8c976724d
+  data.tar.gz: 73316052dfde708cedc6ee10bfc41a63554411a02a8ad10e39bfd94d2280445e
 SHA512:
-  metadata.gz: fa615d0278378e74432832369cf56b16147ecc0e5e27bd12b1fd90c2690fab41dc68fd3042e8dd7c92b8ebb7741f7d08e9db25bd0cec61b384b520f9bd8b400a
-  data.tar.gz: 905389671e4062ef0824e7fb7af8d05fefb1df0ad2a5919bc8a54a8506309ba77cea577859ea49da4e15616fd2fb4bf1d025e5082baef6e61bf18c0c9799d000
+  metadata.gz: 87fc380b17b8c7ce94a3d5cc1026fc41902257624c058eb4806eab4e6fa2a4b102f6dcc7819304888f8abdbf39f9b45b59ad4aa00ece6fc5622aa25d8404e5b6
+  data.tar.gz: '083f2de1d9e2852a56ecd1d44d3232da1b52a5975d9eb6e7de36ece4dcb91e69280daff0091d337d8b03bda33ed3a2a3b48c5334b3049b727c995481602875ac'

data/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "faster_path"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "memchr",
  "rutie",

data/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "faster_path"
-version = "0.5.0"
+version = "0.5.1"
 authors = ["Daniel P. Clark <6ftdan@gmail.com>"]
 description = "Alternative to Pathname"
 homepage = "https://github.com/danielpclark/faster_path"

data/README.md

@@ -114,12 +114,16 @@ As mentioned earlier Sprockets, which handles assets, changed away from using `P
 ## Requirements
 
 * Ruby 3.2, 3.3 or 3.4 (the Rust extension is built with [Rutie](https://github.com/danielpclark/rutie) 0.13, which supports these)
-* Rust 1.71 or later: `gem install` builds the extension with Cargo (through the
+* Rust 1.71 or later, unless a prebuilt extension exists for your platform (see
+  [Installation](#installation)): `gem install` builds the extension with Cargo (through the
   [rutie](https://rubygems.org/gems/rutie) gem's Rake task) and keeps only the built library
 
 ## Installation
 
-Ensure Rust is installed, with `cargo` on your `PATH`:
+Each [release](https://github.com/danielpclark/faster_path/releases) carries a prebuilt
+extension for Ruby 3.4 on Linux x86_64, macOS (arm64 and x86_64) and Windows x64. On those,
+`gem install` needs no Rust. Everywhere else (another Ruby version, OS or CPU), ensure Rust is
+installed, with `cargo` on your `PATH`:
 
 [Install Rust](https://www.rust-lang.org/tools/install)
 
@@ -130,7 +134,7 @@ curl -sSf https://sh.rustup.rs | sh
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'faster_path', '~> 0.5.0'
+gem 'faster_path', '~> 0.5.1'
 ```
 
 And then execute:
@@ -143,9 +147,11 @@ Or install it yourself as:
 
 Installing compiles the Rust extension for the Ruby doing the installing ("Building native
 extensions. This could take a while..."), which takes about a minute the first time while Cargo
-fetches and builds the dependencies. If Rust is missing, the install fails at that step with
-Cargo not being found; install Rust and run it again. Nothing is downloaded from GitHub: there are
-no prebuilt binaries.
+fetches and builds the dependencies. When Cargo is not found, the install downloads the release's
+prebuilt extension for your platform instead (`faster_path-<version>-ruby<XY>-<os>-<cpu>.tar.gz`,
+checked against its SHA-256 file) and fails with a message naming that file if there is none.
+`FASTER_PATH_PREBUILT_URL` points the download at another directory holding the same files, for
+mirrors or machines without access to GitHub.
 
 ## Visual Benchmarks
 

data/Rakefile

@@ -34,6 +34,13 @@ end
 desc 'Build the Rust extension'
 task build_lib: 'rutie:build'
 
+desc 'Package the built extension as the prebuilt release asset for this platform, in pkg/'
+task prebuilt: 'rutie:build' do
+  require 'faster_path/prebuilt'
+  FileUtils.mkdir_p('pkg')
+  puts FasterPath::Prebuilt.package(FasterPath::BuildTask.built_library, 'pkg')
+end
+
 desc 'Code Quality Check'
 task :lint do
   puts

data/ext/Rakefile

@@ -1,14 +1,40 @@
 require 'fileutils'
 require_relative '../lib/faster_path/build_task'
+require_relative '../lib/faster_path/prebuilt'
 
 FasterPath::BuildTask.define
 
-# Keeps the built library (in lib/faster_path, where FasterPath loads it from)
-# and removes the rest of Cargo's output from the installed gem.
+# Builds the extension, keeps the built library (in lib/faster_path, where
+# FasterPath loads it from) and removes the rest of Cargo's output from the
+# installed gem.
 task install_library: 'rutie:build' do
   FileUtils.mkdir_p(FasterPath::BuildTask::INSTALLED_LIBRARY_DIR)
   FileUtils.cp(FasterPath::BuildTask.built_library, FasterPath::BuildTask::INSTALLED_LIBRARY_DIR)
   Rake::Task['rutie:clean'].invoke
 end
 
-task default: :install_library
+NO_PREBUILT = <<~MESSAGE
+  ****
+  Rust's Cargo was not found, and this release of faster_path has no prebuilt
+  extension for this platform (%s).
+  Install Rust (https://www.rust-lang.org/tools/install) and run the install
+  again, or set FASTER_PATH_PREBUILT_URL to a directory holding the asset.
+  ****
+MESSAGE
+
+# Installs the prebuilt library from this version's GitHub release instead.
+task :install_prebuilt do
+  library = FasterPath::Prebuilt.install(FasterPath::BuildTask::PROJECT_DIR)
+  raise format(NO_PREBUILT, FasterPath::Prebuilt.asset_name) unless library
+
+  puts "Installed the prebuilt extension #{File.basename(library)}"
+end
+
+task :default do
+  if FasterPath::BuildTask.cargo?
+    Rake::Task[:install_library].invoke
+  else
+    puts 'Cargo was not found; downloading the prebuilt extension for this platform instead'
+    Rake::Task[:install_prebuilt].invoke
+  end
+end

data/faster_path.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.files         = [
     'Cargo.lock', 'Cargo.toml', 'Gemfile', 'MIT-LICENSE.txt', 'README.md', 'Rakefile',
     'bin/console', 'bin/setup', 'ext/Rakefile', 'faster_path.gemspec', 'lib/faster_path.rb',
-    'lib/faster_path/version.rb', 'lib/faster_path/build_task.rb',
+    'lib/faster_path/version.rb', 'lib/faster_path/build_task.rb', 'lib/faster_path/prebuilt.rb',
     'lib/faster_path/optional/monkeypatches.rb', 'lib/faster_path/optional/refinements.rb'
   ]
   spec.files += Dir['src/**/*']

data/lib/faster_path/build_task.rb

@@ -28,5 +28,15 @@ module FasterPath
     def self.built_library
       Rutie.new(:faster_path).ffi_library(File.join(PROJECT_DIR, 'lib'))
     end
+
+    # Whether Cargo can be run: named by CARGO, or on the PATH
+    def self.cargo?
+      return true if ENV['CARGO']
+
+      exts = RbConfig::CONFIG['EXEEXT'].empty? ? [''] : ['', RbConfig::CONFIG['EXEEXT']]
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+        exts.any? { |ext| File.executable?(File.join(dir, "cargo#{ext}")) }
+      end
+    end
   end
 end

data/lib/faster_path/prebuilt.rb

@@ -0,0 +1,118 @@
+require 'digest/sha2'
+require 'fileutils'
+require 'net/http'
+require 'rbconfig'
+require 'rubygems/package'
+require 'stringio'
+require 'uri'
+require 'zlib'
+require_relative 'version'
+
+module FasterPath
+  # The prebuilt extension that the GitHub release of each version carries
+  # for a few platforms, so that the gem installs without Rust there:
+  # `gem install` falls back to it when Cargo is not found (see ext/Rakefile),
+  # and the release workflow builds it with `rake prebuilt`.
+  module Prebuilt
+    RELEASES = 'https://github.com/danielpclark/faster_path/releases/download'.freeze
+    # Where the library sits in the tarball and, unpacked, in the gem
+    LIBRARY_DIR = File.join('lib', 'faster_path').freeze
+    MAX_REDIRECTS = 5
+
+    # The asset for the running Ruby, e.g. "faster_path-0.5.0-ruby34-linux-x86_64.tar.gz":
+    # the gem version, the Ruby minor version the library was built for (an
+    # extension works with every patch release of it), the OS family and the CPU.
+    def self.asset_name(rbconfig = RbConfig::CONFIG, version = FasterPath::VERSION)
+      major, minor = rbconfig['ruby_version'].split('.')
+      "faster_path-#{version}-ruby#{major}#{minor}-#{os(rbconfig)}-#{cpu(rbconfig)}.tar.gz"
+    end
+
+    def self.os(rbconfig)
+      case rbconfig['host_os']
+      when /darwin/ then 'darwin'
+      when /mingw|mswin|cygwin/ then 'windows'
+      else rbconfig['host_os'][/\A[a-z]+/]
+      end
+    end
+
+    def self.cpu(rbconfig)
+      { 'x64' => 'x86_64', 'amd64' => 'x86_64', 'aarch64' => 'arm64' }.fetch(rbconfig['target_cpu'], rbconfig['target_cpu'])
+    end
+
+    # Packs the built `library` as lib/faster_path/<file> into `dir`, with a
+    # SHA-256 checksum file next to it, and returns the tarball's path.
+    def self.package(library, dir, asset = asset_name)
+      path = File.join(dir, asset)
+      data = File.binread(library)
+      File.open(path, 'wb') do |file|
+        Zlib::GzipWriter.wrap(file) do |gz|
+          Gem::Package::TarWriter.new(gz) do |tar|
+            tar.add_file_simple(File.join(LIBRARY_DIR, File.basename(library)), 0o644, data.bytesize) { |io| io.write(data) }
+          end
+        end
+      end
+      File.write("#{path}.sha256", "#{Digest::SHA256.file(path).hexdigest}  #{asset}\n")
+      path
+    end
+
+    # Downloads this platform's asset of this version's release, checks it
+    # against its checksum file and unpacks the library into `project_dir`.
+    # Returns the library's path, or nil when the release has no asset for
+    # this platform. FASTER_PATH_PREBUILT_URL replaces the release's URL.
+    def self.install(project_dir, base_url = ENV.fetch('FASTER_PATH_PREBUILT_URL', "#{RELEASES}/v#{FasterPath::VERSION}"))
+      asset = asset_name
+      tarball = fetch("#{base_url}/#{asset}")
+      return nil unless tarball
+
+      checksum = fetch("#{base_url}/#{asset}.sha256")
+      raise "#{asset} has no checksum file at #{base_url}" unless checksum
+
+      verify(tarball, checksum, asset)
+      unpack(tarball, project_dir)
+    end
+
+    # The body at `url`, following redirects, or nil if it does not exist.
+    def self.fetch(url, redirects = MAX_REDIRECTS)
+      uri = URI(url)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') { |http| http.get(uri.request_uri) }
+      case response
+      when Net::HTTPSuccess then response.body
+      when Net::HTTPNotFound then nil
+      when Net::HTTPRedirection
+        raise "Too many redirects fetching #{url}" if redirects.zero?
+
+        fetch(URI.join(url, response['Location']).to_s, redirects - 1)
+      else raise "#{url}: #{response.code} #{response.message}"
+      end
+    end
+
+    def self.verify(tarball, checksum, asset)
+      expected = checksum.split.first.to_s.downcase
+      actual = Digest::SHA256.hexdigest(tarball)
+      raise "#{asset} does not match its checksum (expected #{expected}, got #{actual})" unless expected == actual
+    end
+
+    # Unpacks the library of the tarball `data` into `project_dir` and returns its path.
+    def self.unpack(data, project_dir)
+      installed = nil
+      Zlib::GzipReader.wrap(StringIO.new(data)) do |gz|
+        Gem::Package::TarReader.new(gz) do |tar|
+          tar.each do |entry|
+            next unless entry.file? && File.dirname(entry.full_name) == LIBRARY_DIR
+
+            installed = write_library(project_dir, File.basename(entry.full_name), entry.read)
+          end
+        end
+      end
+      installed || raise("No #{LIBRARY_DIR} library in the tarball")
+    end
+
+    def self.write_library(project_dir, name, data)
+      dir = File.join(project_dir, LIBRARY_DIR)
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, name)
+      File.binwrite(path, data)
+      path
+    end
+  end
+end

data/lib/faster_path/version.rb

@@ -1,3 +1,3 @@
 module FasterPath
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: faster_path
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Daniel P. Clark
@@ -157,6 +157,7 @@ files:
 - lib/faster_path/build_task.rb
 - lib/faster_path/optional/monkeypatches.rb
 - lib/faster_path/optional/refinements.rb
+- lib/faster_path/prebuilt.rb
 - lib/faster_path/version.rb
 - src/basename.rs
 - src/chop_basename.rs