diff options
author | The Bundler Bot <bot@bundler.io> | 2016-12-27 13:52:21 +0000 |
---|---|---|
committer | The Bundler Bot <bot@bundler.io> | 2016-12-27 13:52:21 +0000 |
commit | 159c7dc8566f9bdd54f6d877658ad29397e2ec67 (patch) | |
tree | f8069d7a59b6c6c50d58ec9e1cca8f33e153bb58 | |
parent | 5fef8dcb0eeda222fed881975534ebe8bce388bd (diff) | |
parent | f8534729342feb1314dba9da46f457f8e5247e2f (diff) | |
download | bundler-159c7dc8566f9bdd54f6d877658ad29397e2ec67.tar.gz |
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
-rw-r--r-- | DEVELOPMENT.md | 4 | ||||
-rw-r--r-- | lib/bundler/postit_trampoline.rb | 6 | ||||
-rw-r--r-- | lib/bundler/settings.rb | 11 | ||||
-rw-r--r-- | man/bundle-config.ronn | 15 | ||||
-rw-r--r-- | man/bundle-lock.ronn | 13 | ||||
-rw-r--r-- | man/bundle.ronn | 22 | ||||
-rw-r--r-- | spec/bundler/settings_spec.rb | 9 | ||||
-rw-r--r-- | spec/other/trampoline_spec.rb | 8 | ||||
-rw-r--r-- | spec/quality_spec.rb | 52 | ||||
-rw-r--r-- | spec/support/helpers.rb | 2 |
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 |