Added bundler as default gems. Revisit [Feature #12733]

  * bin/*, lib/bundler/*, lib/bundler.rb, spec/bundler, man/*:
    Merge from latest stable branch of bundler/bundler repository and
    added workaround patches. I will backport them into upstream.
  * common.mk, defs/gmake.mk: Added `test-bundler` task for test suite
    of bundler.
  * tool/sync_default_gems.rb: Added sync task for bundler.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@65509 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 653 insertions, 0 deletions

diff --git a/man/gemfile.5.txt b/man/gemfile.5.txt
new file mode 100644
index 0000000000..0ff77795ad
--- /dev/null
+++ b/man/gemfile.5.txt
@@ -0,0 +1,653 @@
+GEMFILE(5)							    GEMFILE(5)
+
+
+
+1mNAME0m
+       1mGemfile 22m- A format for describing gem dependencies for Ruby programs
+
+1mSYNOPSIS0m
+       A 1mGemfile 22mdescribes the gem dependencies required to execute associated
+       Ruby code.
+
+       Place the 1mGemfile 22min the root of the directory containing  the  associ-
+       ated  code.  For instance, in a Rails application, place the 1mGemfile 22min
+       the same directory as the 1mRakefile22m.
+
+1mSYNTAX0m
+       A 1mGemfile 22mis evaluated as Ruby code, in a context which makes available
+       a number of methods used to describe the gem requirements.
+
+1mGLOBAL SOURCES0m
+       At the top of the 1mGemfile22m, add a line for the 1mRubygems 22msource that con-
+       tains the gems listed in the 1mGemfile22m.
+
+
+
+	   source "https://rubygems.org"
+
+
+
+       It is possible, but not recommended as of Bundler 1.7, to add  multiple
+       global  1msource  22mlines.  Each  of these 1msource22ms 1mMUST 22mbe a valid Rubygems
+       repository.
+
+       Sources are checked for gems  following	the  heuristics  described  in
+       4mSOURCE24m  4mPRIORITY24m.  If	a  gem	is found in more than one global source,
+       Bundler will print a warning after installing the gem indicating  which
+       source  was used, and listing the other sources where the gem is avail-
+       able. A specific source can be selected for gems that  need  to	use  a
+       non-standard repository, suppressing this warning, by using the 1m:source0m
+       option or a 1msource 22mblock.
+
+   1mCREDENTIALS0m
+       Some gem sources require a username and password. Use bundle  config(1)
+       4mbundle-config.1.html24m  to  set  the username and password for any of the
+       sources that need it. The command must be run  once  on	each  computer
+       that  will  install  the  Gemfile,  but this keeps the credentials from
+       being stored in plain text in version control.
+
+
+
+	   bundle config gems.example.com user:password
+
+
+
+       For some sources, like a company Gemfury account, it may be  easier  to
+       include the credentials in the Gemfile as part of the source URL.
+
+
+
+	   source "https://user:password@gems.example.com"
+
+
+
+       Credentials in the source URL will take precedence over credentials set
+       using 1mconfig22m.
+
+1mRUBY0m
+       If your application requires a specific Ruby version or engine, specify
+       your  requirements using the 1mruby 22mmethod, with the following arguments.
+       All parameters are 1mOPTIONAL 22munless otherwise specified.
+
+   1mVERSION (required)0m
+       The version of Ruby that your application requires. If your application
+       requires  an  alternate	Ruby  engine, such as JRuby, Rubinius or Truf-
+       fleRuby, this should be the Ruby version that the engine is  compatible
+       with.
+
+
+
+	   ruby "1.9.3"
+
+
+
+   1mENGINE0m
+       Each  application 4mmay24m specify a Ruby engine. If an engine is specified,
+       an engine version 4mmust24m also be specified.
+
+       What exactly is an Engine? - A Ruby engine is an implementation of  the
+       Ruby language.
+
+       o   For	background:  the  reference  or original implementation of the
+	   Ruby  programming  language	is  called  Matz's  Ruby   Interpreter
+	   4mhttps://en.wikipedia.org/wiki/Ruby_MRI24m,  or  MRI for short. This is
+	   named after Ruby creator Yukihiro Matsumoto, also  known  as  Matz.
+	   MRI	is also known as CRuby, because it is written in C. MRI is the
+	   most widely used Ruby engine.
+
+       o   Other implementations 4mhttps://www.ruby-lang.org/en/about/24m  of  Ruby
+	   exist. Some of the more well-known implementations include Rubinius
+	   4mhttps://rubinius.com/24m, and JRuby 4mhttp://jruby.org/24m. Rubinius is  an
+	   alternative	implementation	of  Ruby  written in Ruby. JRuby is an
+	   implementation of Ruby on the JVM, short for Java Virtual Machine.
+
+
+
+   1mENGINE VERSION0m
+       Each application 4mmay24m specify a Ruby engine version. If an  engine  ver-
+       sion  is  specified, an engine 4mmust24m also be specified. If the engine is
+       "ruby" the engine version specified 4mmust24m match the Ruby version.
+
+
+
+	   ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
+
+
+
+   1mPATCHLEVEL0m
+       Each application 4mmay24m specify a Ruby patchlevel.
+
+
+
+	   ruby "2.0.0", :patchlevel => "247"
+
+
+
+1mGEMS0m
+       Specify gem requirements using the 1mgem 22mmethod, with the following argu-
+       ments. All parameters are 1mOPTIONAL 22munless otherwise specified.
+
+   1mNAME (required)0m
+       For each gem requirement, list a single 4mgem24m line.
+
+
+
+	   gem "nokogiri"
+
+
+
+   1mVERSION0m
+       Each 4mgem24m 1mMAY 22mhave one or more version specifiers.
+
+
+
+	   gem "nokogiri", ">= 1.4.2"
+	   gem "RedCloth", ">= 4.1.0", "< 4.2.0"
+
+
+
+   1mREQUIRE AS0m
+       Each  4mgem24m  1mMAY 22mspecify files that should be used when autorequiring via
+       1mBundler.require22m. You may pass an array with multiple files or  1mtrue  22mif
+       file  you  want	1mrequired  22mhas same name as 4mgem24m or 1mfalse 22mto prevent any
+       file from being autorequired.
+
+
+
+	   gem "redis", :require => ["redis/connection/hiredis", "redis"]
+	   gem "webmock", :require => false
+	   gem "debugger", :require => true
+
+
+
+       The argument defaults to the name of the gem. For  example,  these  are
+       identical:
+
+
+
+	   gem "nokogiri"
+	   gem "nokogiri", :require => "nokogiri"
+	   gem "nokogiri", :require => true
+
+
+
+   1mGROUPS0m
+       Each  4mgem24m  1mMAY  22mspecify  membership in one or more groups. Any 4mgem24m that
+       does not specify membership in any  group  is  placed  in  the  1mdefault0m
+       group.
+
+
+
+	   gem "rspec", :group => :test
+	   gem "wirble", :groups => [:development, :test]
+
+
+
+       The  Bundler  runtime  allows  its  two main methods, 1mBundler.setup 22mand
+       1mBundler.require22m, to limit their impact to particular groups.
+
+
+
+	   # setup adds gems to Ruby's load path
+	   Bundler.setup		    # defaults to all groups
+	   require "bundler/setup"	    # same as Bundler.setup
+	   Bundler.setup(:default)	    # only set up the _default_ group
+	   Bundler.setup(:test) 	    # only set up the _test_ group (but `not` _default_)
+	   Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
+
+	   # require requires all of the gems in the specified groups
+	   Bundler.require		    # defaults to the _default_ group
+	   Bundler.require(:default)	    # identical
+	   Bundler.require(:default, :test) # requires the _default_ and _test_ groups
+	   Bundler.require(:test)	    # requires the _test_ group
+
+
+
+       The Bundler CLI allows you to specify a list of groups whose gems  1mbun-0m
+       1mdle  install  22mshould  not install with the 1m--without 22moption. To specify
+       multiple groups to ignore, specify a list of groups separated  by  spa-
+       ces.
+
+
+
+	   bundle install --without test
+	   bundle install --without development test
+
+
+
+       After running 1mbundle install --without test22m, bundler will remember that
+       you excluded the test group in the last installation. The next time you
+       run  1mbundle  install22m, without any 1m--without option22m, bundler will recall
+       it.
+
+       Also, calling 1mBundler.setup 22mwith  no  parameters,  or  calling  1mrequire0m
+       1m"bundler/setup"  22mwill setup all groups except for the ones you excluded
+       via 1m--without 22m(since they are not available).
+
+       Note that on 1mbundle install22m, bundler downloads and evaluates all  gems,
+       in  order to create a single canonical list of all of the required gems
+       and their dependencies. This means that you cannot list different  ver-
+       sions  of  the  same  gems  in  different groups. For more details, see
+       Understanding Bundler 4mhttp://bundler.io/rationale.html24m.
+
+   1mPLATFORMS0m
+       If a gem should only be used in a particular platform or set  of  plat-
+       forms,  you  can  specify  them. Platforms are essentially identical to
+       groups, except that you do not need to use the  1m--without  22minstall-time
+       flag to exclude groups of gems for other platforms.
+
+       There are a number of 1mGemfile 22mplatforms:
+
+       1mruby	22mC Ruby (MRI), Rubinius or TruffleRuby, but 1mNOT 22mWindows
+
+       1mmri	22mSame as 4mruby24m, but only C Ruby (MRI)
+
+       1mmingw	22mWindows 32 bit 'mingw32' platform (aka RubyInstaller)
+
+       1mx64_mingw0m
+	      Windows 64 bit 'mingw32' platform (aka RubyInstaller x64)
+
+       1mrbx	22mRubinius
+
+       1mjruby	22mJRuby
+
+       1mtruffleruby0m
+	      TruffleRuby
+
+       1mmswin	22mWindows
+
+       You  can  restrict  further  by	platform and version for all platforms
+       4mexcept24m for 1mrbx22m, 1mjruby22m, 1mtruffleruby 22mand 1mmswin22m.
+
+       To specify a version in addition to a platform, append the version num-
+       ber without the delimiter to the platform. For example, to specify that
+       a gem should only be used on platforms with Ruby 2.3, use:
+
+
+
+	   ruby_23
+
+
+
+       The full list of platforms and supported versions includes:
+
+       1mruby	22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
+
+       1mmri	22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
+
+       1mmingw	22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
+
+       1mx64_mingw0m
+	      2.0, 2.1, 2.2, 2.3, 2.4, 2.5
+
+       As with groups, you can specify one or more platforms:
+
+
+
+	   gem "weakling",   :platforms => :jruby
+	   gem "ruby-debug", :platforms => :mri_18
+	   gem "nokogiri",   :platforms => [:mri_18, :jruby]
+
+
+
+       All operations involving groups (1mbundle install  4m22mbundle-install.1.html24m,
+       1mBundler.setup22m,  1mBundler.require22m)  behave  exactly  the  same  as if any
+       groups not matching the current platform were explicitly excluded.
+
+   1mSOURCE0m
+       You can select an alternate Rubygems repository for  a  gem  using  the
+       ':source' option.
+
+
+
+	   gem "some_internal_gem", :source => "https://gems.example.com"
+
+
+
+       This  forces  the  gem  to  be  loaded from this source and ignores any
+       global sources declared at the top level of the file. If the  gem  does
+       not exist in this source, it will not be installed.
+
+       Bundler will search for child dependencies of this gem by first looking
+       in the source selected for the parent, but if they are not found there,
+       it  will  fall  back  on global sources using the ordering described in
+       4mSOURCE24m 4mPRIORITY24m.
+
+       Selecting a specific source repository this  way  also  suppresses  the
+       ambiguous gem warning described above in 4mGLOBAL24m 4mSOURCES24m 4m(#source)24m.
+
+       Using  the  1m:source  22moption  for  an individual gem will also make that
+       source available as a possible global source for any other  gems  which
+       do  not	specify explicit sources. Thus, when adding gems with explicit
+       sources, it is recommended that you also ensure all other gems  in  the
+       Gemfile are using explicit sources.
+
+   1mGIT0m
+       If necessary, you can specify that a gem is located at a particular git
+       repository using the 1m:git 22mparameter. The repository can be accessed via
+       several protocols:
+
+       1mHTTP(S)0m
+	      gem "rails", :git => "https://github.com/rails/rails.git"
+
+       1mSSH	22mgem "rails", :git => "git@github.com:rails/rails.git"
+
+       1mgit	22mgem "rails", :git => "git://github.com/rails/rails.git"
+
+       If using SSH, the user that you use to run 1mbundle install MUST 22mhave the
+       appropriate keys available in their 1m$HOME/.ssh22m.
+
+       1mNOTE22m: 1mhttp:// 22mand 1mgit:// 22mURLs should be avoided  if  at  all  possible.
+       These  protocols  are  unauthenticated, so a man-in-the-middle attacker
+       can deliver malicious code and compromise your system.  HTTPS  and  SSH
+       are strongly preferred.
+
+       The  1mgroup22m,  1mplatforms22m,  and  1mrequire  22moptions are available and behave
+       exactly the same as they would for a normal gem.
+
+       A git repository 1mSHOULD 22mhave at least one file,  at  the  root  of	the
+       directory  containing  the  gem, with the extension 1m.gemspec22m. This file
+       1mMUST 22mcontain a valid gem specification, as expected by  the  1mgem	build0m
+       command.
+
+       If  a  git repository does not have a 1m.gemspec22m, bundler will attempt to
+       create one, but it will not contain any dependencies, executables, or C
+       extension  compilation  instructions. As a result, it may fail to prop-
+       erly integrate into your application.
+
+       If a git repository does have a 1m.gemspec 22mfor the gem  you  attached  it
+       to,  a version specifier, if provided, means that the git repository is
+       only valid if the 1m.gemspec 22mspecifies a  version  matching  the  version
+       specifier. If not, bundler will print a warning.
+
+
+
+	   gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git"
+	   # bundle install will fail, because the .gemspec in the rails
+	   # repository's master branch specifies version 3.0.0
+
+
+
+       If  a  git repository does 1mnot 22mhave a 1m.gemspec 22mfor the gem you attached
+       it to, a version specifier 1mMUST 22mbe provided. Bundler will use this ver-
+       sion in the simple 1m.gemspec 22mit creates.
+
+       Git repositories support a number of additional options.
+
+       1mbranch22m, 1mtag22m, and 1mref0m
+	      You  1mMUST 22monly specify at most one of these options. The default
+	      is 1m:branch => "master"0m
+
+       For example:
+
+	      git "https://github.com/rails/rails.git", :branch  =>  "5-0-sta-
+	      ble" do
+
+	      git "https://github.com/rails/rails.git", :tag => "v5.0.0" do
+
+	      git "https://github.com/rails/rails.git", :ref => "4aded" do
+
+       1msubmodules0m
+	      For	   reference,	       a	 git	     submodule
+	      4mhttps://git-scm.com/book/en/v2/Git-Tools-Submodules24m	 lets	you
+	      have  another  git repository within a subfolder of your reposi-
+	      tory. Specify 1m:submodules => true 22mto cause bundler to expand any
+	      submodules included in the git repository
+
+       If  a  git repository contains multiple 1m.gemspecs22m, each 1m.gemspec 22mrepre-
+       sents a gem located at the same place in the file system as  the  1m.gem-0m
+       1mspec22m.
+
+
+
+	   |~rails		     [git root]
+	   | |-rails.gemspec	     [rails gem located here]
+	   |~actionpack
+	   | |-actionpack.gemspec    [actionpack gem located here]
+	   |~activesupport
+	   | |-activesupport.gemspec [activesupport gem located here]
+	   |...
+
+
+
+       To  install  a  gem located in a git repository, bundler changes to the
+       directory containing the gemspec, runs 1mgem build name.gemspec 22mand  then
+       installs the resulting gem. The 1mgem build 22mcommand, which comes standard
+       with Rubygems, evaluates the 1m.gemspec 22min the context of  the  directory
+       in which it is located.
+
+   1mGIT SOURCE0m
+       A  custom  git source can be defined via the 1mgit_source 22mmethod. Provide
+       the source's name as an argument, and a block which receives  a	single
+       argument  and  interpolates  it	into  a string to return the full repo
+       address:
+
+
+
+	   git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
+	   gem 'rails', :stash => 'forks/rails'
+
+
+
+       In addition, if you wish to choose a specific branch:
+
+
+
+	   gem "rails", :stash => "forks/rails", :branch => "branch_name"
+
+
+
+   1mGITHUB0m
+       1mNOTE22m: This shorthand should be avoided until Bundler 2.0, since it cur-
+       rently expands to an insecure 1mgit:// 22mURL. This allows a man-in-the-mid-
+       dle attacker to compromise your system.
+
+       If the git repository you want to use is hosted on GitHub and  is  pub-
+       lic,  you  can use the :github shorthand to specify the github username
+       and repository name (without  the  trailing  ".git"),  separated  by  a
+       slash.  If  both the username and repository name are the same, you can
+       omit one.
+
+
+
+	   gem "rails", :github => "rails/rails"
+	   gem "rails", :github => "rails"
+
+
+
+       Are both equivalent to
+
+
+
+	   gem "rails", :git => "git://github.com/rails/rails.git"
+
+
+
+       Since the 1mgithub 22mmethod is a specialization of 1mgit_source22m, it accepts a
+       1m:branch 22mnamed argument.
+
+   1mGIST0m
+       If the git repository you want to use is hosted as a Github Gist and is
+       public, you can use the :gist shorthand to specify the gist  identifier
+       (without the trailing ".git").
+
+
+
+	   gem "the_hatch", :gist => "4815162342"
+
+
+
+       Is equivalent to:
+
+
+
+	   gem "the_hatch", :git => "https://gist.github.com/4815162342.git"
+
+
+
+       Since  the  1mgist 22mmethod is a specialization of 1mgit_source22m, it accepts a
+       1m:branch 22mnamed argument.
+
+   1mBITBUCKET0m
+       If the git repository you want to use is hosted	on  Bitbucket  and  is
+       public,	you  can use the :bitbucket shorthand to specify the bitbucket
+       username and repository name (without the trailing  ".git"),  separated
+       by  a slash. If both the username and repository name are the same, you
+       can omit one.
+
+
+
+	   gem "rails", :bitbucket => "rails/rails"
+	   gem "rails", :bitbucket => "rails"
+
+
+
+       Are both equivalent to
+
+
+
+	   gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git"
+
+
+
+       Since the 1mbitbucket  22mmethod  is  a	specialization	of  1mgit_source22m,  it
+       accepts a 1m:branch 22mnamed argument.
+
+   1mPATH0m
+       You  can  specify that a gem is located in a particular location on the
+       file system. Relative paths are resolved relative to the directory con-
+       taining the 1mGemfile22m.
+
+       Similar	to the semantics of the 1m:git 22moption, the 1m:path 22moption requires
+       that the directory in question either contains a 1m.gemspec 22mfor the  gem,
+       or that you specify an explicit version that bundler should use.
+
+       Unlike  1m:git22m,  bundler does not compile C extensions for gems specified
+       as paths.
+
+
+
+	   gem "rails", :path => "vendor/rails"
+
+
+
+       If you would like to use multiple local gems directly from the filesys-
+       tem,  you can set a global 1mpath 22moption to the path containing the gem's
+       files. This will automatically load gemspec files from subdirectories.
+
+
+
+	   path 'components' do
+	     gem 'admin_ui'
+	     gem 'public_ui'
+	   end
+
+
+
+1mBLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS0m
+       The 1m:source22m, 1m:git22m, 1m:path22m, 1m:group22m, and 1m:platforms 22moptions may be applied
+       to a group of gems by using block form.
+
+
+
+	   source "https://gems.example.com" do
+	     gem "some_internal_gem"
+	     gem "another_internal_gem"
+	   end
+
+	   git "https://github.com/rails/rails.git" do
+	     gem "activesupport"
+	     gem "actionpack"
+	   end
+
+	   platforms :ruby do
+	     gem "ruby-debug"
+	     gem "sqlite3"
+	   end
+
+	   group :development, :optional => true do
+	     gem "wirble"
+	     gem "faker"
+	   end
+
+
+
+       In  the	case of the group block form the :optional option can be given
+       to prevent a group from being installed unless  listed  in  the	1m--with0m
+       option given to the 1mbundle install 22mcommand.
+
+       In  the	case of the 1mgit 22mblock form, the 1m:ref22m, 1m:branch22m, 1m:tag22m, and 1m:sub-0m
+       1mmodules 22moptions may be passed to the 1mgit 22mmethod, and all  gems  in  the
+       block will inherit those options.
+
+       The  presence  of  a  1msource  22mblock in a Gemfile also makes that source
+       available as a possible global source for any other gems which  do  not
+       specify explicit sources. Thus, when defining source blocks, it is rec-
+       ommended that you also ensure all other gems in the Gemfile  are  using
+       explicit  sources,  either  via	source blocks or 1m:source 22mdirectives on
+       individual gems.
+
+1mINSTALL_IF0m
+       The 1minstall_if 22mmethod allows gems to be installed based on	a  proc  or
+       lambda.	This  is  especially useful for optional gems that can only be
+       used if certain software is installed or some other conditions are met.
+
+
+
+	   install_if -> { RUBY_PLATFORM =~ /darwin/ } do
+	     gem "pasteboard"
+	   end
+
+
+
+1mGEMSPEC0m
+       The 1m.gemspec  4m22mhttp://guides.rubygems.org/specification-reference/24m  file
+       is where you provide metadata about your gem to Rubygems. Some required
+       Gemspec attributes include the name, description, and homepage of  your
+       gem.  This is also where you specify the dependencies your gem needs to
+       run.
+
+       If you wish to use Bundler to help install dependencies for a gem while
+       it  is being developed, use the 1mgemspec 22mmethod to pull in the dependen-
+       cies listed in the 1m.gemspec 22mfile.
+
+       The 1mgemspec 22mmethod adds any runtime dependencies as gem requirements in
+       the  default  group.  It  also  adds  development  dependencies	as gem
+       requirements in the 1mdevelopment 22mgroup. Finally, it adds a gem  require-
+       ment on your project (1m:path => '.'22m). In conjunction with 1mBundler.setup22m,
+       this allows you to require project files in your test code as you would
+       if  the	project  were  installed as a gem; you need not manipulate the
+       load path manually or require project files via relative paths.
+
+       The 1mgemspec 22mmethod supports optional 1m:path22m, 1m:glob22m, 1m:name22m, and 1m:develop-0m
+       1mment_group 22moptions, which control where bundler looks for the 1m.gemspec22m,
+       the glob it uses to look for the  gemspec  (defaults  to:  "{,4m,24m/*}.gem-
+       spec"),	what named 1m.gemspec 22mit uses (if more than one is present), and
+       which group development dependencies are included in.
+
+       When a 1mgemspec 22mdependency encounters version conflicts  during  resolu-
+       tion,  the  local  version under development will always be selected --
+       even if there are remote versions that better match other  requirements
+       for the 1mgemspec 22mgem.
+
+1mSOURCE PRIORITY0m
+       When  attempting  to locate a gem to satisfy a gem requirement, bundler
+       uses the following priority order:
+
+       1.  The source explicitly attached to the gem (using 1m:source22m, 1m:path22m, or
+	   1m:git22m)
+
+       2.  For implicit gems (dependencies of explicit gems), any source, git,
+	   or path repository declared on the parent. This results in  bundler
+	   prioritizing  the  ActiveSupport  gem from the Rails git repository
+	   over ones from 1mrubygems.org0m
+
+       3.  The sources specified  via  global  1msource  22mlines,  searching  each
+	   source in your 1mGemfile 22mfrom last added to first added.
+
+
+
+
+
+
+				 October 2018			    GEMFILE(5)