зеркало из https://github.com/github/ruby.git
402 строки
18 KiB
Plaintext
402 строки
18 KiB
Plaintext
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[=<directory>]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=<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=[<number>]22m, 1m-j[<number>]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=<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=[<number>]0m
|
|
Retry failed network or git requests for 4mnumber24m times.
|
|
|
|
1m--shebang=<ruby-executable>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[=<list>]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=[<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=<list>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=<list>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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
November 2018 BUNDLE-INSTALL(1)
|