mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
e97741e12a
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@66710 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
178 lines
6.8 KiB
Text
178 lines
6.8 KiB
Text
BUNDLE-EXEC(1) BUNDLE-EXEC(1)
|
|
|
|
|
|
|
|
1mNAME0m
|
|
1mbundle-exec 22m- Execute a command in the context of the bundle
|
|
|
|
1mSYNOPSIS0m
|
|
1mbundle exec 22m[--keep-file-descriptors] 4mcommand0m
|
|
|
|
1mDESCRIPTION0m
|
|
This command executes the command, making all gems specified in the
|
|
[1mGemfile(5)22m][Gemfile(5)] available to 1mrequire 22min Ruby programs.
|
|
|
|
Essentially, if you would normally have run something like 1mrspec0m
|
|
1mspec/my_spec.rb22m, and you want to use the gems specified in the [1mGem-0m
|
|
1mfile(5)22m][Gemfile(5)] and installed via bundle install(1) 4mbundle-in-0m
|
|
4mstall.1.html24m, you should run 1mbundle exec rspec spec/my_spec.rb22m.
|
|
|
|
Note that 1mbundle exec 22mdoes not require that an executable is available
|
|
on your shell's 1m$PATH22m.
|
|
|
|
1mOPTIONS0m
|
|
1m--keep-file-descriptors0m
|
|
Exec in Ruby 2.0 began discarding non-standard file descriptors.
|
|
When this flag is passed, exec will revert to the 1.9 behaviour
|
|
of passing all file descriptors to the new process.
|
|
|
|
1mBUNDLE INSTALL --BINSTUBS0m
|
|
If you use the 1m--binstubs 22mflag in bundle install(1) 4mbundle-in-0m
|
|
4mstall.1.html24m, Bundler will automatically create a directory (which de-
|
|
faults to 1mapp_root/bin22m) containing all of the executables available
|
|
from gems in the bundle.
|
|
|
|
After using 1m--binstubs22m, 1mbin/rspec spec/my_spec.rb 22mis identical to 1mbun-0m
|
|
1mdle exec rspec spec/my_spec.rb22m.
|
|
|
|
1mENVIRONMENT MODIFICATIONS0m
|
|
1mbundle exec 22mmakes a number of changes to the shell environment, then
|
|
executes the command you specify in full.
|
|
|
|
o make sure that it's still possible to shell out to 1mbundle 22mfrom in-
|
|
side a command invoked by 1mbundle exec 22m(using 1m$BUNDLE_BIN_PATH22m)
|
|
|
|
o put the directory containing executables (like 1mrails22m, 1mrspec22m,
|
|
1mrackup22m) for your bundle on 1m$PATH0m
|
|
|
|
o make sure that if bundler is invoked in the subshell, it uses the
|
|
same 1mGemfile 22m(by setting 1mBUNDLE_GEMFILE22m)
|
|
|
|
o add 1m-rbundler/setup 22mto 1m$RUBYOPT22m, which makes sure that Ruby pro-
|
|
grams invoked in the subshell can see the gems in the bundle
|
|
|
|
|
|
|
|
It also modifies Rubygems:
|
|
|
|
o disallow loading additional gems not in the bundle
|
|
|
|
o modify the 1mgem 22mmethod to be a no-op if a gem matching the require-
|
|
ments is in the bundle, and to raise a 1mGem::LoadError 22mif it's not
|
|
|
|
o Define 1mGem.refresh 22mto be a no-op, since the source index is always
|
|
frozen when using bundler, and to prevent gems from the system
|
|
leaking into the environment
|
|
|
|
o Override 1mGem.bin_path 22mto use the gems in the bundle, making system
|
|
executables work
|
|
|
|
o Add all gems in the bundle into Gem.loaded_specs
|
|
|
|
|
|
|
|
Finally, 1mbundle exec 22malso implicitly modifies 1mGemfile.lock 22mif the lock-
|
|
file and the Gemfile do not match. Bundler needs the Gemfile to deter-
|
|
mine things such as a gem's groups, 1mautorequire22m, and platforms, etc.,
|
|
and that information isn't stored in the lockfile. The Gemfile and
|
|
lockfile must be synced in order to 1mbundle exec 22msuccessfully, so 1mbundle0m
|
|
1mexec 22mupdates the lockfile beforehand.
|
|
|
|
1mLoading0m
|
|
By default, when attempting to 1mbundle exec 22mto a file with a ruby she-
|
|
bang, Bundler will 1mKernel.load 22mthat file instead of using 1mKernel.exec22m.
|
|
For the vast majority of cases, this is a performance improvement. In a
|
|
rare few cases, this could cause some subtle side-effects (such as de-
|
|
pendence on the exact contents of 1m$0 22mor 1m__FILE__22m) and the optimization
|
|
can be disabled by enabling the 1mdisable_exec_load 22msetting.
|
|
|
|
1mShelling out0m
|
|
Any Ruby code that opens a subshell (like 1msystem22m, backticks, or 1m%x{}22m)
|
|
will automatically use the current Bundler environment. If you need to
|
|
shell out to a Ruby command that is not part of your current bundle,
|
|
use the 1mwith_clean_env 22mmethod with a block. Any subshells created in-
|
|
side the block will be given the environment present before Bundler was
|
|
activated. For example, Homebrew commands run Ruby, but don't work in-
|
|
side a bundle:
|
|
|
|
|
|
|
|
Bundler.with_clean_env do
|
|
`brew install wget`
|
|
end
|
|
|
|
|
|
|
|
Using 1mwith_clean_env 22mis also necessary if you are shelling out to a
|
|
different bundle. Any Bundler commands run in a subshell will inherit
|
|
the current Gemfile, so commands that need to run in the context of a
|
|
different bundle also need to use 1mwith_clean_env22m.
|
|
|
|
|
|
|
|
Bundler.with_clean_env do
|
|
Dir.chdir "/other/bundler/project" do
|
|
`bundle exec ./script`
|
|
end
|
|
end
|
|
|
|
|
|
|
|
Bundler provides convenience helpers that wrap 1msystem 22mand 1mexec22m, and
|
|
they can be used like this:
|
|
|
|
|
|
|
|
Bundler.clean_system('brew install wget')
|
|
Bundler.clean_exec('brew install wget')
|
|
|
|
|
|
|
|
1mRUBYGEMS PLUGINS0m
|
|
At present, the Rubygems plugin system requires all files named
|
|
1mrubygems_plugin.rb 22mon the load path of 4many24m installed gem when any Ruby
|
|
code requires 1mrubygems.rb22m. This includes executables installed into the
|
|
system, like 1mrails22m, 1mrackup22m, and 1mrspec22m.
|
|
|
|
Since Rubygems plugins can contain arbitrary Ruby code, they commonly
|
|
end up activating themselves or their dependencies.
|
|
|
|
For instance, the 1mgemcutter 0.5 22mgem depended on 1mjson_pure22m. If you had
|
|
that version of gemcutter installed (even if you 4malso24m had a newer ver-
|
|
sion without this problem), Rubygems would activate 1mgemcutter 0.5 22mand
|
|
1mjson_pure <latest>22m.
|
|
|
|
If your Gemfile(5) also contained 1mjson_pure 22m(or a gem with a dependency
|
|
on 1mjson_pure22m), the latest version on your system might conflict with
|
|
the version in your Gemfile(5), or the snapshot version in your 1mGem-0m
|
|
1mfile.lock22m.
|
|
|
|
If this happens, bundler will say:
|
|
|
|
|
|
|
|
You have already activated json_pure 1.4.6 but your Gemfile
|
|
requires json_pure 1.4.3. Consider using bundle exec.
|
|
|
|
|
|
|
|
In this situation, you almost certainly want to remove the underlying
|
|
gem with the problematic gem plugin. In general, the authors of these
|
|
plugins (in this case, the 1mgemcutter 22mgem) have released newer versions
|
|
that are more careful in their plugins.
|
|
|
|
You can find a list of all the gems containing gem plugins by running
|
|
|
|
|
|
|
|
ruby -rubygems -e "puts Gem.find_files('rubygems_plugin.rb')"
|
|
|
|
|
|
|
|
At the very least, you should remove all but the newest version of each
|
|
gem plugin, and also remove all gem plugins that you aren't using (1mgem0m
|
|
1muninstall gem_name22m).
|
|
|
|
|
|
|
|
November 2018 BUNDLE-EXEC(1)
|