diff options
author | Carlhuda <carlhuda@engineyard.com> | 2010-08-13 16:08:14 -0700 |
---|---|---|
committer | Carlhuda <carlhuda@engineyard.com> | 2010-08-13 16:08:14 -0700 |
commit | 6e2d9347be6bd07593377edba5fe4385882eddae (patch) | |
tree | 6966255ec3285a090e552067b2638e7ba1c1de23 /man | |
parent | 5bad31427af192df5ec97ccc69a2e4471bc6cdb0 (diff) | |
download | bundler-6e2d9347be6bd07593377edba5fe4385882eddae.tar.gz |
Move the man pages to the bundler repository and write a build task to convert them into roff and txt format.
Diffstat (limited to 'man')
-rw-r--r-- | man/bundle-install.ronn | 310 | ||||
-rw-r--r-- | man/bundle.ronn | 77 | ||||
-rw-r--r-- | man/gemfile.5.ronn | 254 |
3 files changed, 641 insertions, 0 deletions
diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn new file mode 100644 index 00000000..22234758 --- /dev/null +++ b/man/bundle-install.ronn @@ -0,0 +1,310 @@ +bundle-install(1) -- Install the dependencies specified in your Gemfile +======================================================================= + +## SYNOPSIS + +`bundle install` [--local] [--quiet] [--gemfile=GEMFILE] [--system] + [--deployment] [--frozen] [--path] + [--binstubs[=DIRECTORY]] [--without=GROUP1[ GROUP2...]] + +## DESCRIPTION + +Install the gems specified in your `Gemfile(7)`. If this is the first +time you run bundle install (and a `Gemfile.lock` does not exist), +bundler will fetch all remote sources, resolve dependencies and +install all needed gems. + +If a `Gemfile.lock` does exist, and you have not updated your `Gemfile`, +bundler will fetch all remote sources, but use the dependencies +specified in the `Gemfile.lock` instead of resolving dependencies. + +If a `Gemfile.lock` does exist, and you have updated your `Gemfile`, +bundler will use the dependencies in the `Gemfile.lock` for 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 [CONSERVATIVE UPDATING][]. + +## OPTIONS + +* `--gemfile=<gemfile>`: + The location of the `Gemfile` that bundler should use. This defaults + to a gemfile in the current working directory. In general, bundler + will assume that the location of the `Gemfile` is also the project + root, and will look for the `Gemfile.lock` and `vendor/cache` relative + to it. + +* `--path=<path>`: + The location to install the gems in the bundle to. This defaults + to the gem home, which is the location that `gem install` installs + gems to. This means that, by default, gems installed without a + `--path` setting will show up in `gem list`. This setting is a + [remembered option][REMEMBERED OPTIONS]. + +* `--system`: + Installs the gems in the bundle to the system location. This + overrides any previous [remembered][REMEMBERED OPTIONS] use of + `--path`. + +* `--without=<list>`: + A space-separated list of groups to skip installing. This is a + [remembered option][REMEMBERED OPTIONS]. + +* `--local`: + Do not attempt to connect to `rubygems.org`, instead using just + the gems located in `vendor/cache`. Note that if a more + appropriate platform-specific gem exists on `rubygems.org`, + this will bypass the normal lookup. + +* `--deployment`: + Switches bundler's defaults into [deployment mode][DEPLOYMENT MODE]. + +* `--binstubs[=<directory>]`: + Create a directory (defaults to `bin`) containing an executable + that runs in the context of the bundle. For instance, if the + `rails` gem comes with a `rails` executable, this flag will create + a `bin/rails` executable that ensures that all dependencies used + come from the bundled gems. + +## DEPLOYMENT MODE + +Bundler's defaults are optimized for development. To switch to +defaults optimized for deployment, use the `--deployment` flag. + +1. A `Gemfile.lock` is required. + + To ensure that the same versions of the gems you developed with + and tested with are also used in deployments, a `Gemfile.lock` + is required. + + This is mainly to ensure that you remember to check your + `Gemfile.lock` into version control. + +2. The `Gemfile.lock` must be up to date + + In development, you can modify your `Gemfile` and re-run + `bundle install` to [conservatively update][CONSERVATIVE UPDATING] + your `Gemfile.lock` snapshot. + + In deployment, your `Gemfile.lock` should be up-to-date with + changes made in your `Gemfile`. + +3. Gems are installed to `vendor/bundle` not your default system location + + In development, it's convenient to share the gems used in your + application with other applications and other scripts 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 permission to + read them. + + As a result, `bundle install --deployment` installs gems to + the `vendor/bundle` directory in the application. This may be + overridden using the `--path` option. + +## SUDO USAGE + +By default, bundler installs gems to the same location as `gem install`. + +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 `sudo` password in order to copy the gems into +their system location. + +From your perspective, this is identical to installing them gems +directly into the system. + +You should never use `sudo bundle install`. This is because several +other steps in `bundle install` must be performed as the current user: + +* Updating your `Gemfile.lock` +* Updating your `vendor/cache`, if necessary +* Checking out private git repositories using your user's SSH keys + +Of these three, the first two could theoretically be performed by +`chown`ing the resulting files to `$SUDO_USER`. The third, however, +can only be performed by actually invoking the `git` command as +the current user. + +As a result, you should run `bundle install` as the current user, +and bundler will ask for your password if it is needed to perform +the final step. + +## INSTALLING GROUPS + +By default, `bundle install` will install all gems in all groups +in your `Gemfile(7)`, except those declared for a different platform. + +However, you can explicitly tell bundler to skip installing +certain groups with the `--without` option. This option takes +a space-separated list of groups. + +While the `--without` option will skip _installing_ the gems in the +specified groups, it will still _download_ those gems and use them to +resolve the dependencies of every gem in your `Gemfile`. + +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. + +`Bundler offers a rock-solid guarantee that the third-party +code you are running in development and testing is also the +third-party code you are running in production. You can choose +to exclude some of that code in different environments, but you +will never be caught flat-footed by different versions of +third-party code being used in different environments.` + +For a simple illustration, consider the following `Gemfile`: + + source "http://rubygems.org" + + gem "sinatra" + + group :production do + gem "rack-perftools-profiler" + end + +In this case, `sinatra` depends on any version of Rack (`>= 1.0`, while +`rack-perftools-profiler` depends on 1.x (`~> 1.0`). + +When you run `bundle install --without production` in development, we +look at the dependencies of `rack-perftools-profiler` as 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 `production` group _is_ used. + +This should not cause any problems in practice, because we do not +attempt to `install` the 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 just the gems you list in your `Gemfile`, and can +(surprisingly) radically change the gems you are using. + +## REMEMBERED OPTIONS + +Some options (marked above in the [OPTIONS][] section) are remembered +between calls to `bundle install`, and by the Bundler runtime. + +For instance, if you run `bundle install --without test`, a subsequent +call to `bundle install` that does not include a `--without` flag will +remember your previous choice. + +In addition, a call to `Bundler.setup` will not attempt to make the +gems in those groups available on the Ruby load path, as they were +not installed. + +The settings that are remembered are: + +* `--deployment`: + At runtime, this remembered setting will also result in Bundler + raising an exception if the `Gemfile.lock` is out of date. + +* `--path`: + Subsequent calls to `bundle install` will install gems to the + directory originally passed to `--path`. The Bundler runtime + will look for gems in that location. You can revert this + option by running `bundle install --system`. + +* `--binstubs`: + Bundler will update the executables every subsequent call to + `bundle install`. + +* `--without`: + As described above, Bundler will skip the gems specified by + `--without` in subsequent calls to `bundle install`. The + Bundler runtime will also not try to make the gems in the + skipped groups available. + +## THE GEMFILE.LOCK + +When you run `bundle install`, Bundler will persist the full names +and versions of all gems that you used (including dependencies of +the gems specified in the `Gemfile`) into a file called `Gemfile.lock`. + +Bundler uses this file in all subsequent calls to `bundle install`, +which guarantees that you always use the same exact code, even +as your application 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`) can result in radically +different gems being needed to satisfy all dependencies. + +As a result, you `SHOULD` check your `Gemfile.lock` into version +control. 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 `any` of the gems in the `Gemfile` +or any of their dependencies have been updated. + +## CONSERVATIVE UPDATING + +When you make a change to the `Gemfile` and then run `bundle install`, +Bundler will update only the gems that you modified. + +In other words, if a gem that you `did not modify` worked before +you called `bundle install`, 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`: + + source "http://rubygems.org" + + gem "actionpack", "2.3.8" + gem "activemerchant" + +In this case, both `actionpack` and `activemerchant` depend on +`activesupport`. The `actionpack` gem depends on `activesupport 2.3.8` +and `rack ~> 1.1.0`, while the `activemerchant` gem depends on +`activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`. + +When the dependencies are first resolved, Bundler will select +`activesupport 2.3.8`, which satisfies the requirements of both +gems in your `Gemfile`. + +Next, you modify your `Gemfile` to: + + source "http://rubygems.org" + + gem "actionpack", "3.0.0.rc" + gem "activemerchant" + +The `actionpack 3.0.0.rc` gem has a number of new dependencies, +and updates the `activesupport` dependency to `= 3.0.0.rc` and +the `rack` dependency to `~> 1.2.1`. + +When you run `bundle install`, Bundler notices that you changed +the `actionpack` gem, but not the `activemerchant` gem. It +evaluates the gems currently being used to satisfy its requirements: + + * `activesupport 2.3.8`: + also used to satisfy a dependency in `activemerchant`, + which is not being updated + * `rack ~> 1.1.0`: + not currently being used to satify another dependency + +Because you did not explicitly ask to update `activemerchant`, +you would not expect it to suddenly stop working after updating +`actionpack`. However, satisfying the new `activesupport 3.0.0.rc` +dependency of actionpack requires updating one of its dependencies. + +Even though `activemerchant` declares a very loose dependency +that theoretically matches `activesupport 3.0.0.rc`, bundler treats +gems in your `Gemfile` that have not changed as an atomic unit +together with their dependencies. In this case, the `activemerchant` +dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`, +so `bundle install` will report that it cannot update `actionpack`. + +To explicitly update `actionpack`, including its dependencies +which other gems in the `Gemfile` still depend on, run +`bundle update actionpack` (see `bundle update(1)`). + +`Summary`: In general, after making a change to the `Gemfile`, you +should first try to run `bundle install`, which will guarantee that no +other gems in the `Gemfile` are impacted by the change. If that +does not work, run `bundle update(1)`. diff --git a/man/bundle.ronn b/man/bundle.ronn new file mode 100644 index 00000000..48ea209c --- /dev/null +++ b/man/bundle.ronn @@ -0,0 +1,77 @@ +bundle(1) -- Ruby Dependency Management +======================================= + +## SYNOPSIS + +`bundle` [--no-color] COMMAND [ARGS] + +## DESCRIPTION + +Bundler manages an `application's dependencies` through its entire life +across many machines systematically and repeatably. + +See [the bundler website](http://gembundler.com) for information on getting +started, and `Gemfile(7)` for more information on the `Gemfile` format. + +## OPTIONS + +* `--no-color`: + Prints all output without color + +## BUNDLE COMMANDS + +We divide `bundle` subcommands into primary commands and utilities. + +## PRIMARY COMMANDS + +* `bundle install(1)`: + Install the gems specified by the `Gemfile` or `Gemfile.lock` + +* `bundle update(1)`: + Update dependencies to their latest versions + +* `bundle package(1)`: + Package the .gem files required by your application into the + `vendor/cache` directory + +* `bundle exec(1)`: + Execute a script in the context of the current bundle + +* `bundle config(1)`: + Specify and read configuration options for bundler + +## UTILITIES + +* `bundle check(1)`: + Determine whether the requirements for your application are installed + and available to bundler + +* `bundle list(1)`: + Show all of the gems in the current bundle + +* `bundle show(1)`: + Show the source location of a particular gem in the bundle + +* `bundle console(1)`: + Start an IRB session in the context of the current bundle + +* `bundle open(1)`: + Open an installed gem in the editor + +* `bundle viz(1)`: + Generate a visual representation of your dependencies + +* `bundle init(1)`: + Generate a simple `Gemfile`, placed in the current directory + +* `bundle gem(1)`: + Create a simple gem, suitable for development with bundler + +## OBSOLOETE + +These commands are obsolete and should no longer be used + +* `bundle lock(1)` +* `bundle unlock(1)` +* `bundle cache(1)` + diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn new file mode 100644 index 00000000..a7152eeb --- /dev/null +++ b/man/gemfile.5.ronn @@ -0,0 +1,254 @@ +Gemfile(5) -- A format for describing gem dependencies for Ruby programs +======================================================================== + +## SYNOPSIS + +A `Gemfile` describes the gem dependencies required to execute associated +Ruby code. + +Place the `Gemfile` in the root of the directory containing the associated +code. For instance, in a Rails application, place the `Gemfile` in the same +directory as the `Rakefile`. + +## SYNTAX + +A `Gemfile` is evaluated as Ruby code, in a context which makes available +a number of methods used to describe the gem requirements. + +## SOURCES (#source) + +At the top of the `Gemfile`, add one line for each `Rubygems` source that +might contain the gems listed in the `Gemfile`. + + source "http://rubygems.org" + source "http://gems.github.com" + +Each of these _source_s `MUST` be a valid Rubygems repository. + +## GEMS (#gem) + +Specify gem requirements using the `gem` method, with the following arguments. +All parameters are `OPTIONAL` unless otherwise specified. + +### NAME (required) + +For each gem requirement, list a single _gem_ line. + + gem "nokogiri" + +### VERSION + +Each _gem_ `MAY` have one or more version specifiers. + + gem "nokogiri", ">= 1.4.2" + gem "RedCloth", ">= 4.1.0", "< 4.2.0" + +### REQUIRE AS (:require) + +Each _gem_ `MAY` specify its main file, which should be used when autorequiring +(`Bundler.require`). + + gem "sqlite3-ruby", :require => "sqlite3" + +This defaults to the name of the gem itself. For instance, these are identical: + + gem "nokogiri" + gem "nokogiri", :require => "nokogiri" + +### GROUPS (:group or :groups) + +Each _gem_ `MAY` specify membership in one or more groups. Any _gem_ that does +not specify membership in any group is placed in the `default` group. + + gem "rspec", :group => :test + gem "wirble", :groups => [:development, :test] + +The Bundler runtime allows its two main methods, `Bundler.setup` and +`Bundler.require`, 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 just the _default_ group + Bundler.require(:default) # identical + Bundler.require(:default, :test) # requires the _default_ and _test_ groups + Bundler.require(:test) # requires just the _test_ group + +The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should +not install with the `--without` option. To specify multiple groups to ignore, specify a +list of groups separated by spaces. + + bundle install --without test + bundle install --without development test + +After running `bundle install --without test`, bundler will remember that you excluded +the test group in the last installation. The next time you run `bundle install`, +without any `--without option`, bundler will recall it. + +Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"` +will setup all groups except for the ones you excluded via `--without` (since they +are obviously not available). + +Note that on `bundle install`, 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 versions of the same gems in different +groups. For more details, see [Understanding Bundler](http://gembundler.com/v1.0/understanding.html). + +### PLATFORMS (:platforms) + +If a gem should only be used in a particular platform or set of platforms, you can +specify them. Platforms are essentially identical to groups, except that you do not +need to use the `--without` install-time flag to exclude groups of gems for other +platforms. + +There are a number of `Gemfile` platforms: + + * `ruby`: + C Ruby (MRI) or Rubinius, but `NOT` Windows + * `ruby_18`: + _ruby_ `AND` version 1.8 + * `ruby_19`: + _ruby_ `AND` version 1.9 + * `mri`: + Same as _ruby_, but not Rubinius + * `mri_18`: + _mri_ `AND` version 1.8 + * `mri_19`: + _mri_ `AND` version 1.9 + * `jruby`: + JRuby + * `mswin`: + Windows + +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 (`bundle install`, `Bundler.setup`, +`Bundler.require`) behave exactly the same as if any groups not +matching the current platform were explicitly excluded. + +### GIT (:git) + +If necessary, you can specify that a gem is located at a particular +git repository. The repository can be public (`http://github.com/rails/rails.git`) +or private (`git@github.com:rails/rails.git`). If the repository is private, +the user that you use to run `bundle install` `MUST` have the appropriate +keys available in their `$HOME/.ssh`. + +Git repositories are specified using the `:git` parameter. The `group`, +`platforms`, and `require` options are available and behave exactly the same +as they would for a normal gem. + + gem "rails", :git => "git://github.com/rails/rails.git" + +A git repository `SHOULD` have at least one file, at the root of the +directory containing the gem, with the extension `.gemspec`. This file +`MUST` contain a valid gem specification, as expected by the `gem build` +command. It `MUST NOT` have any dependencies, other than on the files in +the git repository itself and any built-in functionality of Ruby or Rubygems. + +If a git repository does not have a `.gemspec`, 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 properly +integrate into your application. + +If a git repository does have a `.gemspec` for the gem you attached it +to, a version specifier, if provided, means that the git repository is +only valid if the `.gemspec` specifies a version matching the version +specifier. If not, bundler will print a warning. + + gem "rails", "2.3.8", :git => "git://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 `not` have a `.gemspec` for the gem you attached +it to, a version specifier `MUST` be provided. Bundler will use this +version in the simple `.gemspec` it creates. + +Git repositories support a number of additional options. + + * `branch`, `tag`, and `ref`: + You `MUST` only specify at most one of these options. The default + is `:branch => "master"` + * `submodules`: + Specify `:submodules => true` to cause bundler to expand any + submodules included in the git repository + +If a git repository contains multiple `.gemspecs`, each `.gemspec` +represents a gem located at the same place in the file system as +the `.gemspec`. + + |~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 `gem build name.gemspec` +and then installs the resulting gem. The `gem build` command, +which comes standard with Rubygems, evaluates the `.gemspec` in +the context of the directory in which it is located. + +### PATH (:path) + +You can specify that a gem is located in a particular location +on the file system. Relative paths are resolved relative to the +directory containing the `Gemfile`. + +Similar to the semantics of the `:git` option, the `:path` +option requires that the directory in question either contains +a `.gemspec` for the gem, or that you specify an explicit +version that bundler should use. + +Unlike `:git`, bundler does not compile C extensions for +gems specified as paths. + + gem "rails", :path => "vendor/rails" + +## BLOCK FORM OF GIT, PATH, GROUP and PLATFORMS + +The `:git`, `:path`, `:group`, and `:platforms` options may be +applied to a group of gems by using block form. + + git "git://github.com/rails/rails.git" do + gem "activesupport" + gem "actionpack" + end + + platforms :ruby do + gem "ruby-debug" + gem "sqlite3-ruby" + end + + group :development do + gem "wirble" + gem "faker" + end + +In the case of the `git` block form, the `:ref`, `:branch`, `:tag`, +and `:submodules` options may be passed to the `git` method, and +all gems in the block will inherit those options. + +## SOURCE PRIORITY + +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 `:path` or `:git`) + 2. For implicit gems (dependencies of explicit gems), any git or path + repository otherwise declared. This results in bundler prioritizing the + ActiveSupport gem from the Rails git repository over ones from + `rubygems.org` + 3. The sources specified via `source`, in the order in which they were + declared in the `Gemfile`. |