Add ability to install only the pure-ruby variant

Author: jamescook

.github/workflows/ci.yml

@@ -14,6 +14,26 @@ jobs:
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  # Packaging check, not a behaviour check: the suite already runs everything
+  # under CATARACT_PURE=1, but that leaves the compiled extension on disk. This
+  # installs the built gem with no extension at all, which is the only way to
+  # catch a stub Makefile that stops satisfying RubyGems, or a file the pure
+  # backend needs going missing from spec.files.
+  pure-only-install:
+    name: Install with --disable-native-extension
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+
+    - name: Install without the C extension and verify the pure backend
+      run: bundle exec rake gem:verify_pure_only
+
   lint:
     if: github.actor == 'jamescook'
     needs: test-ubuntu

.gitignore

@@ -56,3 +56,6 @@ docs/
 
 .cache/
 .cocci/
+
+# Generated at build time by ext/cataract/extconf.rb
+lib/cataract/build_config.rb

README.md

@@ -40,6 +40,22 @@ Cataract includes a pure Ruby implementation alongside the C extension. This is
 - Development/debugging without needing to recompile C code
 - Environments with restricted native code execution
 
+**Install without compiling the C extension at all:**
+```bash
+gem install cataract -- --disable-native-extension
+```
+
+```bash
+# Bundler equivalent, set before `bundle install`
+bundle config set build.cataract --disable-native-extension
+```
+
+Installed this way there is no compile step and no compiler needed. The gem
+records the choice at build time, so `require 'cataract'` loads the pure Ruby
+backend on its own — no environment variable, and `Cataract::IMPLEMENTATION`
+reports `:ruby`. A missing extension that *wasn't* asked for still raises,
+rather than quietly falling back to a slower backend.
+
 **In your Gemfile:**
 ```ruby
 gem 'cataract', require: 'cataract/pure'

ext/cataract/extconf.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require 'mkmf'
+require_relative 'extension_config'
+
+# Nothing below runs for a --disable-native-extension install; the stub
+# Makefile and build config are already written by this point.
+return unless ExtensionConfig.build_native_extension?
 
 # Helper methods for platform detection
 def darwin?

ext/cataract/extension_config.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'fileutils'
+
+# Shared by both extconf.rb files.
+#
+# `gem install cataract -- --disable-native-extension` installs the pure Ruby
+# backend on its own, for hosts with no compiler. Both extensions honour the
+# flag, and the decision has to reach runtime, which is what the generated
+# build config carries.
+module ExtensionConfig
+  # Written into the installed gem's lib/, alongside the code that reads it.
+  GENERATED_CONFIG = File.expand_path('../../lib/cataract/build_config.rb', __dir__)
+
+  module_function
+
+  def native_extension?
+    enable_config('native-extension', true)
+  end
+
+  # RubyGems calls a build failed whenever extconf leaves no Makefile, so
+  # opting out still has to write one. It needs every target the install
+  # invokes; each does nothing.
+  def write_stub_makefile
+    File.write('Makefile', <<~MAKE)
+      all install static install-so install-rb clean:
+      \t@true
+      .PHONY: all install static install-so install-rb clean
+    MAKE
+  end
+
+  # Records which backend this install has, for lib/cataract.rb to read.
+  # Written on both paths so re-enabling the extension overwrites a stale
+  # opt-out rather than leaving the library pointed at pure Ruby.
+  def write_build_config(native:)
+    FileUtils.mkdir_p(File.dirname(GENERATED_CONFIG))
+    File.write(GENERATED_CONFIG, <<~RUBY)
+      # frozen_string_literal: true
+
+      # Generated by ext/cataract/extconf.rb at build time. Do not edit.
+      module Cataract
+        module BuildConfig
+          # False when installed with --disable-native-extension.
+          NATIVE_EXTENSION = #{native}
+        end
+      end
+    RUBY
+  end
+
+  # Called first by both extconf files. Returns false when the caller should
+  # stop without building.
+  def build_native_extension?
+    if native_extension?
+      write_build_config(native: true)
+      return true
+    end
+
+    puts 'Native extension: DISABLED (--disable-native-extension) - installing pure Ruby only'
+    write_build_config(native: false)
+    write_stub_makefile
+    false
+  end
+end

ext/cataract_color/extconf.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'mkmf'
+require_relative '../cataract/extension_config'
+
+# The colour extension is C too, so a compiler-less install skips it as well.
+return unless ExtensionConfig.build_native_extension?
 
 # Add include path for cataract.h from main extension
 $INCFLAGS << ' -I$(srcdir)/../cataract'

lib/cataract.rb

@@ -35,7 +35,25 @@ class << self
   end
 end
 
-if %w[1 true].include?(ENV.fetch('CATARACT_PURE', nil)) || RUBY_ENGINE == 'jruby'
+# Generated by ext/cataract/extconf.rb at build time, recording whether this
+# install has a compiled extension. Missing only in a source checkout that has
+# never been compiled, where the extension is the expectation.
+#
+# The extension is never loaded speculatively: if it should be here and isn't,
+# the require below raises rather than quietly dropping to a backend several
+# times slower.
+cataract_build_config = File.expand_path('cataract/build_config.rb', __dir__)
+require cataract_build_config if File.exist?(cataract_build_config)
+
+module Cataract
+  module BuildConfig
+    NATIVE_EXTENSION = true unless defined?(NATIVE_EXTENSION)
+  end
+end
+
+if %w[1 true].include?(ENV.fetch('CATARACT_PURE', nil)) ||
+   RUBY_ENGINE == 'jruby' ||
+   !Cataract::BuildConfig::NATIVE_EXTENSION
   require_relative 'cataract/pure'
   Cataract::Backends.active = Cataract::Backends::Pure
 else

lib/tasks/gem.rake

@@ -40,6 +40,97 @@ namespace :gem do
     puts "\nTo release, run: rake release"
   end
 
+  desc 'Verify the gem installs and runs with --disable-native-extension'
+  task :verify_pure_only do
+    require 'tmpdir'
+
+    # The suite already runs everything under CATARACT_PURE=1, but that leaves
+    # the compiled extension on disk. This installs the built gem with no
+    # extension at all - the only way to catch a stub Makefile that stops
+    # satisfying RubyGems, or a file the pure backend needs dropping out of
+    # spec.files.
+    Dir.mktmpdir do |dir|
+      gem_file = File.join(dir, 'cataract-pure-only.gem')
+      gem_home = File.join(dir, 'gems')
+
+      # Runtime dependencies may already be satisfiable outside this scratch
+      # home, in which case `gem install` won't copy them in. Keep the
+      # inherited path on the end so they still resolve, or activating
+      # cataract fails and surfaces as a bare LoadError. The check asserts
+      # cataract itself came from the scratch install.
+      search_path = [gem_home, ENV.fetch('GEM_PATH', nil)].compact.reject(&:empty?)
+      env = { 'GEM_HOME' => gem_home, 'GEM_PATH' => search_path.join(File::PATH_SEPARATOR) }
+
+      sh 'gem', 'build', 'cataract.gemspec', '-o', gem_file
+      sh env, 'gem', 'install', gem_file, '--no-document', '--', '--disable-native-extension'
+
+      compiled = Dir.glob(File.join(gem_home, '**', '*.{so,bundle}'))
+      raise "Expected no compiled artifacts, found: #{compiled.join(', ')}" unless compiled.empty?
+
+      puts "\n✓ Nothing was compiled"
+
+      File.write(File.join(dir, 'sample.css'), "body { color: red; }\n@media print { .a, .b { margin: 0; } }\n")
+
+      # Run outside this checkout with CATARACT_PURE unset, so the installed
+      # gem has to reach the pure backend on its own rather than being told to.
+      check = <<~RUBY
+        require 'cataract'
+
+        # GEM_PATH reaches beyond the scratch install so dependencies resolve,
+        # so confirm this is the gem we just built and not one already present.
+        spec = Gem.loaded_specs['cataract']
+        unless spec && File.realpath(spec.full_gem_path).start_with?('#{File.realpath(dir)}')
+          raise "cataract loaded from \#{spec&.full_gem_path.inspect}, not the scratch install"
+        end
+
+        # The build recorded the decision, rather than it being inferred.
+        if Cataract::BuildConfig::NATIVE_EXTENSION
+          raise 'BuildConfig::NATIVE_EXTENSION is true; expected the install to have recorded false'
+        end
+
+        # The compiled objects are genuinely absent, not merely unused. Without
+        # this, a stale extension left on the load path would satisfy every
+        # other assertion here.
+        %w[cataract/native_extension cataract/cataract_color].each do |ext|
+          begin
+            require ext
+          rescue LoadError
+            next
+          end
+          raise "\#{ext} loaded; expected no compiled extension to be available"
+        end
+
+        unless Cataract::IMPLEMENTATION == :ruby
+          raise "Expected the pure backend, got \#{Cataract::IMPLEMENTATION.inspect}"
+        end
+
+        unless defined?(Cataract::Backends::Native).nil?
+          raise 'Cataract::Backends::Native is defined; the native backend should never have loaded'
+        end
+
+        sheet = Cataract::Stylesheet.parse(File.read('sample.css'))
+        raise "Expected 3 rules, got \#{sheet.rules_count}" unless sheet.rules_count == 3
+
+        css = sheet.to_s
+        raise "Declaration lost: \#{css.inspect}" unless css.include?('color: red')
+        raise "Media query lost: \#{css.inspect}" unless css.include?('@media print')
+
+        puts "✓ No compiled extension is loadable"
+        puts "✓ Loaded the \#{Cataract::IMPLEMENTATION} backend and parsed \#{sheet.rules_count} rules"
+      RUBY
+
+      # verbose(false) so rake doesn't echo the whole check script back
+      Dir.chdir(dir) do
+        verbose(false) do
+          sh env.merge('RUBYOPT' => nil, 'BUNDLE_GEMFILE' => nil, 'CATARACT_PURE' => nil),
+             RbConfig.ruby, '-e', check
+        end
+      end
+    end
+
+    puts "\n✓ Pure-only install verified"
+  end
+
   desc 'Bump version (usage: rake gem:bump[major|minor|patch])'
   task :bump, [:type] do |_t, args|
     type = args[:type] || 'patch'