From 59c8d50653480bef3f24517296e6ddf937fdf6bc Mon Sep 17 00:00:00 2001 From: hsbt Date: Fri, 2 Nov 2018 23:07:56 +0000 Subject: 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 --- man/bundle-install.1.txt | 401 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 401 insertions(+) create mode 100644 man/bundle-install.1.txt (limited to 'man/bundle-install.1.txt') diff --git a/man/bundle-install.1.txt b/man/bundle-install.1.txt new file mode 100644 index 0000000000..1b7f3adcdf --- /dev/null +++ b/man/bundle-install.1.txt @@ -0,0 +1,401 @@ +BUNDLE-INSTALL(1) BUNDLE-INSTALL(1) + + + +1mNAME0m + 1mbundle-install 22m- Install the dependencies specified in your Gemfile + +1mSYNOPSIS0m + 1mbundle install 22m[--binstubs[=DIRECTORY]] [--clean] [--deployment] + [--frozen] [--full-index] [--gemfile=GEMFILE] [--jobs=NUMBER] [--local] + [--no-cache] [--no-prune] [--path PATH] [--quiet] [--redownload] + [--retry=NUMBER] [--shebang] [--standalone[=GROUP[ GROUP...]]] [--sys- + tem] [--trust-policy=POLICY] [--with=GROUP[ GROUP...]] [--with- + out=GROUP[ GROUP...]] + +1mDESCRIPTION0m + Install the gems specified in your Gemfile(5). If this is the first + time you run bundle install (and a 1mGemfile.lock 22mdoes not exist), + Bundler will fetch all remote sources, resolve dependencies and install + all needed gems. + + If a 1mGemfile.lock 22mdoes exist, and you have not updated your Gemfile(5), + Bundler will fetch all remote sources, but use the dependencies speci- + fied in the 1mGemfile.lock 22minstead of resolving dependencies. + + If a 1mGemfile.lock 22mdoes exist, and you have updated your Gemfile(5), + Bundler will use the dependencies in the 1mGemfile.lock 22mfor all gems that + you did not update, but will re-resolve the dependencies of gems that + you did update. You can find more information about this update process + below under 4mCONSERVATIVE24m 4mUPDATING24m. + +1mOPTIONS0m + To apply any of 1m--binstubs22m, 1m--deployment22m, 1m--path22m, or 1m--without 22mevery + time 1mbundle install 22mis run, use 1mbundle config 22m(see bundle-config(1)). + + 1m--binstubs[=]0m + Binstubs are scripts that wrap around executables. Bundler cre- + ates a small Ruby file (a binstub) that loads Bundler, runs the + command, and puts it in 1mbin/22m. This lets you link the binstub + inside of an application to the exact gem version the applica- + tion needs. + + Creates a directory (defaults to 1m~/bin22m) and places any executa- + bles from the gem there. These executables run in Bundler's con- + text. If used, you might add this directory to your environ- + ment's 1mPATH 22mvariable. For instance, if the 1mrails 22mgem comes with + a 1mrails 22mexecutable, this flag will create a 1mbin/rails 22mexecutable + that ensures that all referred dependencies will be resolved + using the bundled gems. + + 1m--clean0m + On finishing the installation Bundler is going to remove any + gems not present in the current Gemfile(5). Don't worry, gems + currently in use will not be removed. + + 1m--deployment0m + In 4mdeployment24m 4mmode24m, Bundler will 'roll-out' the bundle for pro- + duction or CI use. Please check carefully if you want to have + this option enabled in your development environment. + + 1m--redownload0m + Force download every gem, even if the required versions are + already available locally. + + 1m--frozen0m + Do not allow the Gemfile.lock to be updated after this install. + Exits non-zero if there are going to be changes to the Gem- + file.lock. + + 1m--full-index0m + Bundler will not call Rubygems' API endpoint (default) but down- + load and cache a (currently big) index file of all gems. Perfor- + mance can be improved for large bundles that seldom change by + enabling this option. + + 1m--gemfile=0m + The location of the Gemfile(5) which Bundler should use. This + defaults to a Gemfile(5) in the current working directory. In + general, Bundler will assume that the location of the Gemfile(5) + is also the project's root and will try to find 1mGemfile.lock 22mand + 1mvendor/cache 22mrelative to this location. + + 1m--jobs=[]22m, 1m-j[]0m + The maximum number of parallel download and install jobs. The + default is 1m122m. + + 1m--local0m + Do not attempt to connect to 1mrubygems.org22m. Instead, Bundler will + use the gems already present in Rubygems' cache or in 1mven-0m + 1mdor/cache22m. Note that if a appropriate platform-specific gem + exists on 1mrubygems.org 22mit will not be found. + + 1m--no-cache0m + Do not update the cache in 1mvendor/cache 22mwith the newly bundled + gems. This does not remove any gems in the cache but keeps the + newly bundled gems from being cached during the install. + + 1m--no-prune0m + Don't remove stale gems from the cache when the installation + finishes. + + 1m--path=0m + The location to install the specified gems to. This defaults to + Rubygems' setting. Bundler shares this location with Rubygems, + 1mgem install ... 22mwill have gem installed there, too. Therefore, + gems installed without a 1m--path ... 22msetting will show up by + calling 1mgem list22m. Accordingly, gems installed to other locations + will not get listed. + + 1m--quiet0m + Do not print progress information to the standard output. + Instead, Bundler will exit using a status code (1m$?22m). + + 1m--retry=[]0m + Retry failed network or git requests for 4mnumber24m times. + + 1m--shebang=0m + Uses the specified ruby executable (usually 1mruby22m) to execute the + scripts created with 1m--binstubs22m. In addition, if you use 1m--bin-0m + 1mstubs 22mtogether with 1m--shebang jruby 22mthese executables will be + changed to execute 1mjruby 22minstead. + + 1m--standalone[=]0m + Makes a bundle that can work without depending on Rubygems or + Bundler at runtime. A space separated list of groups to install + has to be specified. Bundler creates a directory named 1mbundle0m + and installs the bundle there. It also generates a 1mbun-0m + 1mdle/bundler/setup.rb 22mfile to replace Bundler's own setup in the + manner required. Using this option implicitly sets 1mpath22m, which + is a [remembered option][REMEMBERED OPTIONS]. + + 1m--system0m + Installs the gems specified in the bundle to the system's + Rubygems location. This overrides any previous configuration of + 1m--path22m. + + 1m--trust-policy=[]0m + Apply the Rubygems security policy 4mpolicy24m, where policy is one + of 1mHighSecurity22m, 1mMediumSecurity22m, 1mLowSecurity22m, 1mAlmostNoSecurity22m, + or 1mNoSecurity22m. For more details, please see the Rubygems signing + documentation linked below in 4mSEE24m 4mALSO24m. + + 1m--with=0m + A space-separated list of groups referencing gems to install. If + an optional group is given it is installed. If a group is given + that is in the remembered list of groups given to --without, it + is removed from that list. + + 1m--without=0m + A space-separated list of groups referencing gems to skip during + installation. If a group is given that is in the remembered list + of groups given to --with, it is removed from that list. + +1mDEPLOYMENT MODE0m + Bundler's defaults are optimized for development. To switch to defaults + optimized for deployment and for CI, use the 1m--deployment 22mflag. Do not + activate deployment mode on development machines, as it will cause an + error when the Gemfile(5) is modified. + + 1. A 1mGemfile.lock 22mis required. + + To ensure that the same versions of the gems you developed with and + tested with are also used in deployments, a 1mGemfile.lock 22mis + required. + + This is mainly to ensure that you remember to check your 1mGem-0m + 1mfile.lock 22minto version control. + + 2. The 1mGemfile.lock 22mmust be up to date + + In development, you can modify your Gemfile(5) and re-run 1mbundle0m + 1minstall 22mto 4mconservatively24m 4mupdate24m your 1mGemfile.lock 22msnapshot. + + In deployment, your 1mGemfile.lock 22mshould be up-to-date with changes + made in your Gemfile(5). + + 3. Gems are installed to 1mvendor/bundle 22mnot your default system loca- + tion + + In development, it's convenient to share the gems used in your + application with other applications and other scripts that run on + the system. + + In deployment, isolation is a more important default. In addition, + the user deploying the application may not have permission to + install gems to the system, or the web server may not have permis- + sion to read them. + + As a result, 1mbundle install --deployment 22minstalls gems to the 1mven-0m + 1mdor/bundle 22mdirectory in the application. This may be overridden + using the 1m--path 22moption. + + + +1mSUDO USAGE0m + By default, Bundler installs gems to the same location as 1mgem install22m. + + In some cases, that location may not be writable by your Unix user. In + that case, Bundler will stage everything in a temporary directory, then + ask you for your 1msudo 22mpassword in order to copy the gems into their + system location. + + From your perspective, this is identical to installing the gems + directly into the system. + + You should never use 1msudo bundle install22m. This is because several other + steps in 1mbundle install 22mmust be performed as the current user: + + o Updating your 1mGemfile.lock0m + + o Updating your 1mvendor/cache22m, if necessary + + o Checking out private git repositories using your user's SSH keys + + + + Of these three, the first two could theoretically be performed by + 1mchown22ming the resulting files to 1m$SUDO_USER22m. The third, however, can + only be performed by invoking the 1mgit 22mcommand as the current user. + Therefore, git gems are downloaded and installed into 1m~/.bundle 22mrather + than $GEM_HOME or $BUNDLE_PATH. + + As a result, you should run 1mbundle install 22mas the current user, and + Bundler will ask for your password if it is needed to put the gems into + their final location. + +1mINSTALLING GROUPS0m + By default, 1mbundle install 22mwill install all gems in all groups in your + Gemfile(5), except those declared for a different platform. + + However, you can explicitly tell Bundler to skip installing certain + groups with the 1m--without 22moption. This option takes a space-separated + list of groups. + + While the 1m--without 22moption will skip 4minstalling24m the gems in the speci- + fied groups, it will still 4mdownload24m those gems and use them to resolve + the dependencies of every gem in your Gemfile(5). + + This is so that installing a different set of groups on another machine + (such as a production server) will not change the gems and versions + that you have already developed and tested against. + + 1mBundler offers a rock-solid guarantee that the third-party code you are0m + 1mrunning in development and testing is also the third-party code you are0m + 1mrunning in production. You can choose to exclude some of that code in0m + 1mdifferent environments, but you will never be caught flat-footed by0m + 1mdifferent versions of third-party code being used in different environ-0m + 1mments.0m + + For a simple illustration, consider the following Gemfile(5): + + + + source 'https://rubygems.org' + + gem 'sinatra' + + group :production do + gem 'rack-perftools-profiler' + end + + + + In this case, 1msinatra 22mdepends on any version of Rack (1m>= 1.022m), while + 1mrack-perftools-profiler 22mdepends on 1.x (1m~> 1.022m). + + When you run 1mbundle install --without production 22min development, we + look at the dependencies of 1mrack-perftools-profiler 22mas well. That way, + you do not spend all your time developing against Rack 2.0, using new + APIs unavailable in Rack 1.x, only to have Bundler switch to Rack 1.2 + when the 1mproduction 22mgroup 4mis24m used. + + This should not cause any problems in practice, because we do not + attempt to 1minstall 22mthe gems in the excluded groups, and only evaluate + as part of the dependency resolution process. + + This also means that you cannot include different versions of the same + gem in different groups, because doing so would result in different + sets of dependencies used in development and production. Because of the + vagaries of the dependency resolution process, this usually affects + more than the gems you list in your Gemfile(5), and can (surprisingly) + radically change the gems you are using. + +1mTHE GEMFILE.LOCK0m + When you run 1mbundle install22m, Bundler will persist the full names and + versions of all gems that you used (including dependencies of the gems + specified in the Gemfile(5)) into a file called 1mGemfile.lock22m. + + Bundler uses this file in all subsequent calls to 1mbundle install22m, which + guarantees that you always use the same exact code, even as your appli- + cation moves across machines. + + Because of the way dependency resolution works, even a seemingly small + change (for instance, an update to a point-release of a dependency of a + gem in your Gemfile(5)) can result in radically different gems being + needed to satisfy all dependencies. + + As a result, you 1mSHOULD 22mcheck your 1mGemfile.lock 22minto version control, + in both applications and gems. If you do not, every machine that checks + out your repository (including your production server) will resolve all + dependencies again, which will result in different versions of + third-party code being used if 1many 22mof the gems in the Gemfile(5) or any + of their dependencies have been updated. + + When Bundler first shipped, the 1mGemfile.lock 22mwas included in the 1m.git-0m + 1mignore 22mfile included with generated gems. Over time, however, it became + clear that this practice forces the pain of broken dependencies onto + new contributors, while leaving existing contributors potentially + unaware of the problem. Since 1mbundle install 22mis usually the first step + towards a contribution, the pain of broken dependencies would discour- + age new contributors from contributing. As a result, we have revised + our guidance for gem authors to now recommend checking in the lock for + gems. + +1mCONSERVATIVE UPDATING0m + When you make a change to the Gemfile(5) and then run 1mbundle install22m, + Bundler will update only the gems that you modified. + + In other words, if a gem that you 1mdid not modify 22mworked before you + called 1mbundle install22m, it will continue to use the exact same versions + of all dependencies as it used before the update. + + Let's take a look at an example. Here's your original Gemfile(5): + + + + source 'https://rubygems.org' + + gem 'actionpack', '2.3.8' + gem 'activemerchant' + + + + In this case, both 1mactionpack 22mand 1mactivemerchant 22mdepend on 1mactivesup-0m + 1mport22m. The 1mactionpack 22mgem depends on 1mactivesupport 2.3.8 22mand 1mrack ~>0m + 1m1.1.022m, while the 1mactivemerchant 22mgem depends on 1mactivesupport >= 2.3.222m, + 1mbraintree >= 2.0.022m, and 1mbuilder >= 2.0.022m. + + When the dependencies are first resolved, Bundler will select + 1mactivesupport 2.3.822m, which satisfies the requirements of both gems in + your Gemfile(5). + + Next, you modify your Gemfile(5) to: + + + + source 'https://rubygems.org' + + gem 'actionpack', '3.0.0.rc' + gem 'activemerchant' + + + + The 1mactionpack 3.0.0.rc 22mgem has a number of new dependencies, and + updates the 1mactivesupport 22mdependency to 1m= 3.0.0.rc 22mand the 1mrack 22mdepen- + dency to 1m~> 1.2.122m. + + When you run 1mbundle install22m, Bundler notices that you changed the + 1mactionpack 22mgem, but not the 1mactivemerchant 22mgem. It evaluates the gems + currently being used to satisfy its requirements: + + 1mactivesupport 2.3.80m + also used to satisfy a dependency in 1mactivemerchant22m, which is + not being updated + + 1mrack ~> 1.1.00m + not currently being used to satisfy another dependency + + Because you did not explicitly ask to update 1mactivemerchant22m, you would + not expect it to suddenly stop working after updating 1mactionpack22m. How- + ever, satisfying the new 1mactivesupport 3.0.0.rc 22mdependency of action- + pack requires updating one of its dependencies. + + Even though 1mactivemerchant 22mdeclares a very loose dependency that theo- + retically matches 1mactivesupport 3.0.0.rc22m, Bundler treats gems in your + Gemfile(5) that have not changed as an atomic unit together with their + dependencies. In this case, the 1mactivemerchant 22mdependency is treated as + 1mactivemerchant 1.7.1 + activesupport 2.3.822m, so 1mbundle install 22mwill + report that it cannot update 1mactionpack22m. + + To explicitly update 1mactionpack22m, including its dependencies which other + gems in the Gemfile(5) still depend on, run 1mbundle update actionpack0m + (see 1mbundle update(1)22m). + + 1mSummary22m: In general, after making a change to the Gemfile(5) , you + should first try to run 1mbundle install22m, which will guarantee that no + other gem in the Gemfile(5) is impacted by the change. If that does not + work, run bundle update(1) 4mbundle-update.1.html24m. + +1mSEE ALSO0m + o Gem install docs + 4mhttp://guides.rubygems.org/rubygems-basics/#installing-gems0m + + o Rubygems signing docs 4mhttp://guides.rubygems.org/security/0m + + + + + + + October 2018 BUNDLE-INSTALL(1) -- cgit v1.2.3