diff options
author | wycats <wycats@gmail.com> | 2010-08-15 18:32:35 -0700 |
---|---|---|
committer | wycats <wycats@gmail.com> | 2010-08-15 19:46:13 -0700 |
commit | 702e7aac1e29492604487c52c807f63de2aba193 (patch) | |
tree | ab7c8db770ed85511ee142d555408d9ebd0d5c51 /man | |
parent | 93939761bc2ce5a6dffa5c849aac9a56f5a1401a (diff) | |
download | bundler-702e7aac1e29492604487c52c807f63de2aba193.tar.gz |
Add bundle config and bundle exec
Diffstat (limited to 'man')
-rw-r--r-- | man/bundle-config.ronn | 90 | ||||
-rw-r--r-- | man/bundle-exec.ronn | 98 |
2 files changed, 188 insertions, 0 deletions
diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn new file mode 100644 index 00000000..50408723 --- /dev/null +++ b/man/bundle-config.ronn @@ -0,0 +1,90 @@ +bundle-config(1) -- Set bundler configuration options +===================================================== + +## SYNOPSIS + +`bundle config` [<name> [<value>]] + +## DESCRIPTION + +This command allows you to interact with bundler's configuration system. +Bundler retrieves its configuration from the local application (`app/.bundle/config), +environment variables, and the user's home directory (`~/.bundle/config), +in that order of priority. + +Executing `bundle config` with no parameters will print a list of all +bundler configuration for the current bundle, and where that configuration +was set. + +Executing `bundle config <name>` will print the value of that configuration +setting, and where it was set. + +Executing `bundle config <name> <value>` will set that configuration to the +value specified for all bundles executed as the current user. The configuration +will be stored in `~/.bundle/config`. + +## BUILD OPTIONS + +You can use `bundle config` to give bundler the flags to pass to the gem +installer every time bundler tries to install a particular gem. + +A very common example, the `mysql` gem, requires Snow Leopard users to +pass configuration flags to `gem install` to specify where to find the +`mysql_config` executable. + + gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config + +Since the specific location of that executable can change from machine +to machine, you can specify these flags on a per-machine basis. + + bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config + +After running this command, every time bundler needs to install the +`mysql` gem, it will pass along the flags you specified. + +## CONFIGURATION KEYS + +Configuration keys in bundler have two forms: the canonical form and the +environment variable form. + +For instance, passing the `--without` flag to `bundle install(1)` prevents +Bundler from installing certain groups specified in the `Gemfile(1)`. Bundler +persists this value in `app/.bundle/config` so that calls to `Bundler.setup` +do not try to find gems from the `Gemfile` that you didn't install. Additionally, +subsequent calls to `bundle install(1)` remember this setting and skip those +groups. + +The canonical form of this configuration is `"without"`. To convert the canonical +form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The +environment variable form of `"without"` is `BUNDLE_WITHOUT`. + +## LIST OF AVAILABLE KEYS + +The following is a list of all configuration keys and their purpose. You can +learn more about their operation in `bundle install(1)`. + +* `path` (`BUNDLE_PATH`): + The location on disk to install gems. Defaults to `$GEM_HOME` in development + and `vendor/bundler` when `--deployment` is used +* `frozen` (`BUNDLE_FROZEN`): + Disallow changes to the `Gemfile`. Defaults to `true` when `--deployment` + is used. +* `without` (`BUNDLE_WITHOUT`): + A `:`-separated list of groups whose gems bundler should not install +* `bin` (`BUNDLE_BIN`): + Install executables from gems in the bundle to the specified directory. + Defaults to `false`. +* `gemfile` (`BUNDLE_GEMFILE`): + The name of the file that bundler should use as the `Gemfile`. This location + of this file also sets the root of the project, which is used to resolve + relative paths in the `Gemfile`, among other things. By default, bundler + will search up from the current working directory until it finds a + `Gemfile`. + +In general, you should set these settings per-application by using the applicable +flag to the `bundle install(1)` command. + +You can set them globally either via environment variables or `bundle config`, +whichever is preferable for your setup. If you use both, environment variables +will take preference over global settings. + diff --git a/man/bundle-exec.ronn b/man/bundle-exec.ronn new file mode 100644 index 00000000..b2fe9a25 --- /dev/null +++ b/man/bundle-exec.ronn @@ -0,0 +1,98 @@ +bundle-exec(1) -- Execute a command in the context of the bundle +================================================================ + +## SYNOPSIS + +`bundle exec` <command> + +## DESCRIPTION + +This command executes the command, making all gems specified in the +`Gemfile(5)` available to `require` in Ruby programs. + +Essentially, if you would normally have run something like +`rspec spec/my_spec.rb`, and you want to use the gems specified +in the `Gemfile(5)` and installed via `bundle install(1)`, you +should run `bundle exec rspec spec/my_spec.rb`. + +Note that `bundle exec` does not require that an executable is +available on your shell's `$PATH`. + +## BUNDLE INSTALL --BINSTUBS + +If you use the `--binstubs` flag in `bundle install(1)`, Bundler will +automatically create a directory (which defaults to `app_root/bin`) +containing all of the executables available from gems in the bundle. + +After using `--binstubs`, `bin/rspec spec/my_spec.rb` is identical +to `bundle exec rspec spec/my_spec.rb`. + +## ENVIRONMENT MODIFICATIONS + +`bundle exec` makes a number of changes to the shell environment, +then executes the command you specify in full. + +* make sure that it's still possible to shell out to `bundle` + from inside a command invoked by `bundle exec` (using + `$BUNDLE_BIN_PATH`) +* put the directory containing executables (like `rails`, `rspec`, + `rackup`) for your bundle on `$PATH` +* make sure that if bundler is invoked in the subshell, it uses + the same `Gemfile` (by setting `BUNDLE_GEMFILE`) +* add `-rbundler/setup` to `$RUBYOPT`, which makes sure that + Ruby programs invoked in the subshell can see the gems in + the bundle + +It also modifies Rubygems: + +* disallow loading additional gems not in the bundle +* modify the `gem` method to be a no-op if a gem matching + the requirements is in the bundle, and to raise a + `Gem::LoadError` if it's not +* Define `Gem.refresh` to 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 +* Override `Gem.bin_path` to use the gems in the bundle, + making system executables work +* Add all gems in the bundle into Gem.loaded_specs + +## RUBYGEMS PLUGINS + +At present, the Rubygems plugin system requires all files +named `rubygems_plugin.rb` on the load path of _any_ installed +gem when any Ruby code requires `rubygems.rb`. This includes +executables installed into the system, like `rails`, `rackup`, +and `rspec`. + +Since Rubygems plugins can contain arbitrary Ruby code, they +commonly end up activating themselves or their dependencies. + +For instance, the `gemcutter 0.5` gem depended on `json_pure`. +If you had that version of gemcutter installed (even if +you _also_ had a newer version without this problem), Rubygems +would activate `gemcutter 0.5` and `json_pure <latest>`. + +If your `Gemfile(5)` also contained `json_pure` (or a gem +with a dependency on `json_pure`), the latest version on +your system might conflict with the version in your +`Gemfile(5)`, or the snapshot version in your `Gemfile.lock`. + +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 `gemcutter` +gem) 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 (`gem uninstall gem_name`). |