Rails' binstubs vs. Bundler binstubs - incompatibility and breaking changes, maybe?

00_Rails-binstubs-vs-Bundler-binstubs.md

Rails' binstubs vs. Bundler binstubs

There's an incompatibility in the Rails vs Bundler-generated bin/bundle binstub. Futher, other Bundler-generated binstubs (e.g., bin/rspec) generated by older versions of Bundler don't play well with those generated by Bundler v1.16.

The Binstubs and versions.

bin/rspec

The older rspec-old.rb was generated by an older version of Bundler. Using the Gemfile.lock as a guide, I'd guess it was Bundler v1.13.7.

The current rspec.rb was generated by Bundler v1.16.0.

bin/bundle

The older bundle-old.rb was generated by Rails as part of the original rails new, circa Dec 11, 2015. That was Rails v4.2.5, and the Bundler being used then (based on the Gemfile.lock) was v1.10.6. A new Rails v5.1.4 will generate an identical bin/bundle to this one, as confirmed by bin/rails app:update:bin.

The current bundle.rb was generated by Bundler v1.16.0.

What's a developer to do?

It's unclear, to this developer, anyhow, which bin/bundle we should be using? It sure seems we need the Bundler-generated version for things to work with other Bundler-generated binstubs. But then why do we have the Rails-generated binstubs at all? Perhaps some advice, at least, in the Rails guides, and/or in Bundler's docs would be helpful?

bundle-old.rb

#!/usr/bin/env ruby
ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
load Gem.bin_path('bundler', 'bundle')

bundle.rb

#!/usr/bin/env ruby
# frozen_string_literal: true

#
# This file was generated by Bundler.
#
# The application 'bundle' is installed as part of a gem, and
# this file is here to facilitate running it.
#

require "rubygems"

m = Module.new do
    module_function

  def invoked_as_script?
    File.expand_path($0) == File.expand_path(__FILE__)
  end

  def env_var_version
    ENV["BUNDLER_VERSION"]
  end

  def cli_arg_version
    return unless invoked_as_script? # don't want to hijack other binstubs
    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
    bundler_version = nil
    update_index = nil
    ARGV.each_with_index do |a, i|
      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
        bundler_version = a
      end
      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
      bundler_version = $1 || ">= 0.a"
      update_index = i
    end
    bundler_version
  end

  def gemfile
    gemfile = ENV["BUNDLE_GEMFILE"]
    return gemfile if gemfile && !gemfile.empty?

    File.expand_path("../../Gemfile", __FILE__)
  end

  def lockfile
    lockfile =
      case File.basename(gemfile)
      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
      else "#{gemfile}.lock"
      end
    File.expand_path(lockfile)
  end

  def lockfile_version
    return unless File.file?(lockfile)
    lockfile_contents = File.read(lockfile)
    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
    Regexp.last_match(1)
  end

  def bundler_version
    @bundler_version ||= begin
      env_var_version || cli_arg_version ||
        lockfile_version || "#{Gem::Requirement.default}.a"
    end
  end

  def load_bundler!
    ENV["BUNDLE_GEMFILE"] ||= gemfile

    # must dup string for RG < 1.8 compatibility
    activate_bundler(bundler_version.dup)
  end

  def activate_bundler(bundler_version)
    if Gem::Version.correct?(bundler_version) && Gem::Version.new(bundler_version).release < Gem::Version.new("2.0")
      bundler_version = "< 2"
    end
    gem_error = activation_error_handling do
      gem "bundler", bundler_version
    end
    return if gem_error.nil?
    require_error = activation_error_handling do
      require "bundler/version"
    end
    return if require_error.nil? && Gem::Requirement.new(bundler_version).satisfied_by?(Gem::Version.new(Bundler::VERSION))
    warn "Activating bundler (#{bundler_version}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_version}'`"
    exit 42
  end

  def activation_error_handling
    yield
    nil
  rescue StandardError, LoadError => e
    e
  end
end

m.load_bundler!

if m.invoked_as_script?
  load Gem.bin_path("bundler", "bundle")
end

rspec-old.rb

#!/usr/bin/env ruby
# frozen_string_literal: true
#
# This file was generated by Bundler.
#
# The application 'rspec' is installed as part of a gem, and
# this file is here to facilitate running it.
#

require "pathname"
ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
  Pathname.new(__FILE__).realpath)

require "rubygems"
require "bundler/setup"

load Gem.bin_path("rspec-core", "rspec")

rspec.rb

#!/usr/bin/env ruby
# frozen_string_literal: true

#
# This file was generated by Bundler.
#
# The application 'rspec' is installed as part of a gem, and
# this file is here to facilitate running it.
#

bundle_binstub = File.expand_path("../bundle", __FILE__)
load(bundle_binstub) if File.file?(bundle_binstub)

require "pathname"
ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
  Pathname.new(__FILE__).realpath)

require "rubygems"
require "bundler/setup"

load Gem.bin_path("rspec-core", "rspec")

For posterity, the open issue against rails/rails is here: rails/rails#31193