Auto merge of #5276 - bundler:seg-platform-docs, r=indirect

Document 1.14 platform changes

See https://github.com/bundler/bundler/issues/4853

@indirect feel free to add any other docs you think might be helpful to this branch

10 files changed, 125 insertions, 17 deletions

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 67e1527677..97e764dea9 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -36,9 +36,9 @@ Bundler doesn't use a Gemfile to list development dependencies, because when we
 
   4. Set up a shell alias to run Bundler from your clone, e.g. a Bash alias:
 
-        $ alias dbundle='BUNDLE_DISABLE_POSTIT=1 ruby -I /path/to/bundler/lib /path/to/bundler/exe/bundle'
+        $ alias dbundle='BUNDLE_TRAMPOLINE_DISABLE=1 ruby -I /path/to/bundler/lib /path/to/bundler/exe/bundle'
 
-     The `BUNDLE_DISABLE_POSTIT` environment variable ensures that the version of Bundler in `/path/to/bundler/lib` will be used. Without that environment setting, Bundler will automatically download, install, and run the version of Bundler listed in `Gemfile.lock`. With that set up, you can test changes you've made to Bundler by running `dbundle`, without interfering with the regular `bundle` command.
+     The `BUNDLE_TRAMPOLINE_DISABLE` environment variable ensures that the version of Bundler in `/path/to/bundler/lib` will be used. Without that environment setting, Bundler will automatically download, install, and run the version of Bundler listed in `Gemfile.lock`. With that set up, you can test changes you've made to Bundler by running `dbundle`, without interfering with the regular `bundle` command.
 
 To dive into the code with Pry: `RUBYOPT=-rpry dbundle` to require pry and then run commands.
 
diff --git a/lib/bundler/postit_trampoline.rb b/lib/bundler/postit_trampoline.rb
index 2a22489954..b62a5e7676 100644
--- a/lib/bundler/postit_trampoline.rb
+++ b/lib/bundler/postit_trampoline.rb
@@ -8,11 +8,11 @@ environment = BundlerVendoredPostIt::PostIt::Environment.new([])
 version = Gem::Requirement.new(environment.bundler_version)
 if version.requirements.size == 1 && version.requirements.first.first == "=" # version.exact?
   if version.requirements.first.last.segments.first >= 2
-    ENV["BUNDLE_ENABLE_TRAMPOLINE"] = "true"
+    ENV["BUNDLE_TRAMPOLINE_FORCE"] = "true"
   end
 end
 
-if ENV["BUNDLE_ENABLE_TRAMPOLINE"] && !ENV["BUNDLE_DISABLE_POSTIT"]
+if ENV["BUNDLE_TRAMPOLINE_FORCE"] && !ENV["BUNDLE_TRAMPOLINE_DISABLE"]
   installed_version =
     if defined?(Bundler::VERSION)
       Bundler::VERSION
@@ -70,4 +70,4 @@ You're running Bundler #{installed_version} but this project uses #{running_vers
     abort "The running bundler (#{running_version}) does not match the required `#{version}`"
   end
 
-end # if ENV["BUNDLE_ENABLE_TRAMPOLINE"] && !ENV["BUNDLE_DISABLE_POSTIT"]
+end # if ENV["BUNDLE_TRAMPOLINE_FORCE"] && !ENV["BUNDLE_TRAMPOLINE_DISABLE"]
diff --git a/lib/bundler/settings.rb b/lib/bundler/settings.rb
index 2f532c832f..35ad17ae43 100644
--- a/lib/bundler/settings.rb
+++ b/lib/bundler/settings.rb
@@ -240,7 +240,12 @@ module Bundler
     end
 
     def to_bool(value)
-      !(value.nil? || value == "" || value =~ /^(false|f|no|n|0)$/i || value == false)
+      case value
+      when nil, /\A(false|f|no|n|0|)\z/i, false
+        false
+      else
+        true
+      end
     end
 
     def is_num(value)
@@ -298,10 +303,10 @@ module Bundler
     }xo
 
     def load_config(config_file)
-      return {} unless config_file
+      return {} if !config_file || ignore_config?
       SharedHelpers.filesystem_access(config_file, :read) do |file|
         valid_file = file.exist? && !file.size.zero?
-        return {} if ignore_config? || !valid_file
+        return {} unless valid_file
         require "bundler/yaml_serializer"
         YAMLSerializer.load file.read
       end
diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn
index cb9fc6cc00..fd15a24288 100644
--- a/man/bundle-config.ronn
+++ b/man/bundle-config.ronn
@@ -155,6 +155,20 @@ learn more about their operation in [bundle install(1)][bundle-install].
    The number of redirects allowed for network requests. Defaults to `5`.
 * `timeout` (`BUNDLE_TIMEOUT`):
    The seconds allowed before timing out for network requests. Defaults to `10`.
+* `force_ruby_platform` (`BUNDLE_FORCE_RUBY_PLATFORM`):
+   Ignore the current machine's platform and install only `ruby` platform gems.
+   As a result, gems with native extensions will be compiled from source.
+* `specific_platform` (`BUNDLE_SPECIFIC_PLATFORM`):
+   Allow bundler to resolve for the specific running platform and store it in
+   the lockfile, instead of only using a generic platform.
+   A specific platform is the exact platform triple reported by
+   `Gem::Platform.local`, such as `x86_64-darwin-16` or `universal-java-1.8`.
+   On the other hand, generic platforms are those such as `ruby`, `mswin`, or
+   `java`. In this example, `x86_64-darwin-16` would map to `ruby` and
+   `universal-java-1.8` to `java`.
+* `disable_checksum_validation` (`BUNDLE_DISABLE_CHECKSUM_VALIDATION`):
+   Allow installing gems even if they do not match the checksum provided by
+   RubyGems.
 
 In general, you should set these settings per-application by using the applicable
 flag to the [bundle install(1)][bundle-install] or [bundle package(1)][bundle-package] command.
@@ -236,4 +250,3 @@ This is especially useful for private repositories on hosts such as Github,
 where you can use personal OAuth tokens:
 
     export BUNDLE_GITHUB__COM=abcd0123generatedtoken:x-oauth-basic
-
diff --git a/man/bundle-lock.ronn b/man/bundle-lock.ronn
index b18d819c21..31ecd3c877 100644
--- a/man/bundle-lock.ronn
+++ b/man/bundle-lock.ronn
@@ -42,7 +42,8 @@ Lock the gems specified in Gemfile.
   Fall back to using the single-file index of all gems.
 
 * `--add-platform`:
-  Add a new platform to the lockfile.
+  Add a new platform to the lockfile, re-resolving for the addition of that
+  platform.
 
 * `--remove-platform`:
   Remove a platform from the lockfile.
@@ -78,6 +79,16 @@ For instance, you only want to update `nokogiri`, run `bundle lock --update noko
 Bundler will update `nokogiri` and any of its dependencies, but leave the rest of the
 gems that you specified locked to the versions in the `Gemfile.lock`.
 
+## SUPPORTING OTHER PLATFORMS
+
+If you want your bundle to support platforms other than the one you're running
+locally, you can run `bundle lock --add-platform PLATFORM` to add PLATFORM to
+the lockfile, force bundler to re-resolve and consider the new platform when
+picking gems, all without needing to have a machine that matches PLATFORM handy
+to install those platform-specific gems on.
+
+For a full explanation of gem platforms, see `gem help platform`.
+
 ## PATCH LEVEL OPTIONS
 
 See [bundle update(1)][bundle-update] for details.
diff --git a/man/bundle.ronn b/man/bundle.ronn
index f2b1daa08f..59fed42304 100644
--- a/man/bundle.ronn
+++ b/man/bundle.ronn
@@ -55,7 +55,7 @@ We divide `bundle` subcommands into primary commands and utilities.
 * `bundle show(1)`:
   Show the source location of a particular gem in the bundle
 
-* `bundle outdated(1)`:
+* [`bundle outdated(1)`][bundle-outdated]:
   Show all of the outdated gems in the current bundle
 
 * `bundle console(1)`:
@@ -64,7 +64,7 @@ We divide `bundle` subcommands into primary commands and utilities.
 * `bundle open(1)`:
   Open an installed gem in the editor
 
-* `bundle lock(1)`:
+* [`bundle lock(1)`][bundle-lock]:
   Generate a lockfile for your dependencies
 
 * `bundle viz(1)`:
@@ -91,6 +91,24 @@ When running a command that isn't listed in PRIMARY COMMANDS or UTILITIES,
 Bundler will try to find an executable on your path named `bundler-<command>`
 and execute it, passing down any extra arguments to it.
 
+## BUNDLER TRAMPOLINING
+
+Bundler includes a feature called trampolining, designed to allow a single
+developer to work on multiple projects, each on different Bundler versions.
+The trampoline will infer the correct version of Bundler to use for each project
+and load that version instead of the version directly invoked (which is almost
+always the newest version installed locally).
+
+Bundler by default will use the Bundler version in the current directory to
+determine the version to trampoline to, reading from the `BUNDLED WITH` section.
+However, if the `BUNDLER_VERSION` environment variable is set, that version will
+override the lockfile inference and can be used in directories without a
+lockfile.
+
+Until the target version is Bundler 2 or later, `BUNDLE_TRAMPOLINE_FORCE` must
+be set for the trampoline to be used. Additionally, `BUNDLE_TRAMPOLINE_DISABLE` can
+be set to completely disable the trampoline.
+
 ## OBSOLETE
 
 These commands are obsolete and should no longer be used
diff --git a/spec/bundler/settings_spec.rb b/spec/bundler/settings_spec.rb
index 5a9d0cb08b..04e221a57c 100644
--- a/spec/bundler/settings_spec.rb
+++ b/spec/bundler/settings_spec.rb
@@ -51,6 +51,15 @@ that would suck --ehhh=oh geez it looks like i might have broken bundler somehow
       end]
       expect(loaded).to eq(expected)
     end
+
+    context "when BUNDLE_IGNORE_CONFIG is set" do
+      before { ENV["BUNDLE_IGNORE_CONFIG"] = "TRUE" }
+
+      it "ignores the config" do
+        loaded = settings.send(:load_config, bundled_app("config"))
+        expect(loaded).to eq({})
+      end
+    end
   end
 
   describe "#[]" do
diff --git a/spec/other/trampoline_spec.rb b/spec/other/trampoline_spec.rb
index 9a8e0a4a5d..88e0302f00 100644
--- a/spec/other/trampoline_spec.rb
+++ b/spec/other/trampoline_spec.rb
@@ -3,8 +3,8 @@ require "spec_helper"
 
 describe "bundler version trampolining" do
   before do
-    ENV["BUNDLE_DISABLE_POSTIT"] = nil
-    ENV["BUNDLE_ENABLE_TRAMPOLINE"] = "true"
+    ENV["BUNDLE_TRAMPOLINE_DISABLE"] = nil
+    ENV["BUNDLE_TRAMPOLINE_FORCE"] = "true"
     FileUtils.rm_rf(system_gem_path)
     FileUtils.cp_r(base_system_gems, system_gem_path)
   end
@@ -59,8 +59,8 @@ describe "bundler version trampolining" do
     end
   end
 
-  context "without BUNDLE_ENABLE_TRAMPOLINE" do
-    before { ENV["BUNDLE_ENABLE_TRAMPOLINE"] = nil }
+  context "without BUNDLE_TRAMPOLINE_FORCE" do
+    before { ENV["BUNDLE_TRAMPOLINE_FORCE"] = nil }
 
     context "when the version is >= 2" do
       let(:version) { "2.7182818285" }
diff --git a/spec/quality_spec.rb b/spec/quality_spec.rb
index 5f73228b4a..9148bf512f 100644
--- a/spec/quality_spec.rb
+++ b/spec/quality_spec.rb
@@ -191,6 +191,58 @@ describe "The library itself" do
     expect(error_messages.compact).to be_well_formed
   end
 
+  it "documents all used settings" do
+    exemptions = %w(
+      allow_offline_install
+      auto_install
+      cache_all
+      cache_all_platforms
+      clean
+      console
+      disable_exec_load
+      disable_local_branch_check
+      disable_shared_gems
+      gem.coc
+      gem.mit
+      jobs
+      major_deprecations
+      no_install
+      no_prune
+      only_update_to_newer_versions
+      plugins
+      shebang
+      silence_root_warning
+      ssl_verify_mode
+      system_bindir
+      user_agent
+      warned_version
+    )
+
+    all_settings = Hash.new {|h, k| h[k] = [] }
+    documented_settings = exemptions
+
+    Bundler::Settings::BOOL_KEYS.each {|k| all_settings[k] << "in Bundler::Settings::BOOL_KEYS" }
+    Bundler::Settings::NUMBER_KEYS.each {|k| all_settings[k] << "in Bundler::Settings::NUMBER_KEYS" }
+
+    Dir.chdir(File.expand_path("../../lib", __FILE__)) do
+      key_pattern = /([a-z\._-]+)/i
+      `git ls-files -z`.split("\x0").each do |filename|
+        File.readlines(filename).each_with_index do |line, number|
+          line.scan(/Bundler\.settings\[:#{key_pattern}\]/).flatten.each {|s| all_settings[s] << "referenced at `lib/#{filename}:#{number}`" }
+        end
+      end
+      documented_settings = File.read("../man/bundle-config.ronn").scan(/^\* `#{key_pattern}`/).flatten
+    end
+
+    documented_settings.each {|s| all_settings.delete(s) }
+    exemptions.each {|s| all_settings.delete(s) }
+    error_messages = all_settings.map do |setting, refs|
+      "The `#{setting}` setting is undocumented\n\t- #{refs.join("\n\t- ")}"
+    end
+
+    expect(error_messages.sort).to be_well_formed
+  end
+
   it "can still be built" do
     Dir.chdir(root) do
       begin
diff --git a/spec/support/helpers.rb b/spec/support/helpers.rb
index 3912ad068f..738b1f7b3b 100644
--- a/spec/support/helpers.rb
+++ b/spec/support/helpers.rb
@@ -12,7 +12,7 @@ module Spec
       end
       FileUtils.mkdir_p(tmp)
       FileUtils.mkdir_p(home)
-      ENV["BUNDLE_DISABLE_POSTIT"] = "1"
+      ENV["BUNDLE_TRAMPOLINE_DISABLE"] = "1"
       Bundler.reset!
       Bundler.ui = nil
       Bundler.ui # force it to initialize