docs.rubygems.org recent changes

Eric Hodel: "unpack" -- Unpack an installed gem to the current directory

2010-02-12T06:13:28Z

(Not in version 0.7.)

The unpack command creates a private copy of the named gem’s contents into a
new directory. This enables you to examine the contents without interfering
with the gem repository.

You can only unpack gems that you have installed, and you must specify the gem
name exactly.

Usage

Usage: gem unpack GEMNAME [options]

  Options:
    -v, --version VERSION            Specify version of gem to unpack

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME       Name of the gem to unpack

  Summary:
    Unpack an installed gem to the current directory

  Defaults:
    --version '> 0'

Examples

$ gem unpack rake
Unpacked gem: 'rake-0.4.3'

$ ls rake-0.4.3/
CHANGES  MIT-LICENSE  README  Rakefile  TODO  bin  doc  install.rb  lib  test

$ gem unpack wazoo
ERROR:  Gem 'wazoo' not installed.

Eric Hodel: "uninstall" -- Uninstalling a gem

2010-02-12T06:13:20Z

The uninstall will uninstall the named gem. If multiple versions of a
gem are installed, you will be prompted to select a single one, or all
of them.

Usage

Usage: gem uninstall GEMNAME [options]

  Options:
    -a, --[no-]all                   Uninstall all matching versions
    -i, --[no-]ignore-dependencies   Ignore dependency requirements while uninstalling
    -x, --[no-]executables           Uninstall applicable executables without confirmation
    -v, --version VERSION            Specify version of gem to uninstall

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME   name of gem to uninstall

  Summary:
    Uninstall a gem from the local repository

  Defaults:
    --version '> 0' --no-force

Examples

The following uninstalls the only copy of copland.

$ gem uninstall copland
Attempting to uninstall gem 'copland'
Successfully uninstalled copland version 0.3.0

The following uninstalls all the installed versions of the rake gem.
Since rake is an application, it has a ApplicationStub installed. The
uninstall removes the stub as well.

$ sudo gem uninstall rake
Attempting to uninstall gem 'rake'

Select RubyGem to uninstall:
 1. rake-0.3.2
 2. rake-0.4.0
 3. All versions
> 3
Successfully uninstalled rake version 0.3.2
Successfully uninstalled rake version 0.4.0
WARNING:  About to remove executables and scripts for: rake
Proceed? [Y/n]  y
Removing rake

Eric Hodel: "specification" -- Extract the Gem::Specification from a gem file

2010-02-12T06:13:13Z

The specification command will extract the Gem::Specification from a
gem file and write to standard output in YAML format.

Usage

Usage: gem specification GEMFILE [options]

  Options:
    -v, --version VERSION            Specify version of gem to examine
    -l, --local                      Restrict operations to the LOCAL domain (default)
    -r, --remote                     Restrict operations to the REMOTE domain
    -b, --both                       Allow LOCAL and REMOTE operations
        --all                        Output specifications for all versions of the gem

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMFILE       Name of a .gem file to examine

  Summary:
    Display gem specification (in yaml)

  Defaults:
    --local --version '(latest)'

Examples

Here is the specification from rake 0.4.1.

$ gem spec rake -v 0.4.1
--- !ruby/object:Gem::Specification 
rubygems_version: "0.6"
name: rake
version: !ruby/object:Gem::Version 
  version: 0.4.1
date: 2004-07-02 01:08:54.678603 -04:00
platform: 
summary: Ruby based make-like utility.
require_paths: 
  - lib
files: 
  - install.rb
  - CHANGES
  - Rakefile
  - README
  - TODO
  - MIT-LICENSE
  - bin/rake
  - lib/rake.rb
  - lib/rake/clean.rb
  ......

Eric Hodel: "search" -- List gems containing a string

2010-02-12T06:13:05Z

gem search will list all gems whose name contains the given
(case-insensitive) string. If no string is provided, all gems will be listed.

Usage

Usage: gem search [STRING] [options]

  Options:
    -d, --[no-]details               Display detailed information of gem(s)
    -l, --local                      Restrict operations to the LOCAL domain (default)
    -r, --remote                     Restrict operations to the REMOTE domain
    -b, --both                       Allow LOCAL and REMOTE operations

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    STRING   fragment of gem name to look for

  Summary:
    Display all gems whose name contains STRING

  Defaults:
    --local --no-details

Examples

List all remote gems containing “log” in their name.

$ gem search -r log

*** REMOTE GEMS ***

log4r (1.0.5)
    Log4r is a comprehensive and flexible logging library for Ruby.

rublog (0.8.0)
    RubLog is a simple web log, based around the idea of displaying a
    set of regular files in a log-format.

Eric Hodel: "rdoc" -- Generate the RDoc files for an installed gem

2010-02-12T06:12:59Z

gem rdoc will generate the RDoc files for an installed gem.
The files are put in the standard gem RDoc location so that
gem_server can find them.

Usage

Usage: gem rdoc [args] [options]

  Options:
        --all                        Generate RDoc documentation for all installed gems
    -v, --version VERSION            Specify version of gem to rdoc

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME          The gem to generate RDoc for (unless --all)

  Summary:
    Generates RDoc for pre-installed gems

  Defaults:
    --version '> 0.0.0'

Examples

The following command generates the RDoc files for the rake-0.5.4 gem.

traken$ sudo gem rdoc rake --version 0.5.4
Installing RDoc documentation for rake-0.5.4...

Eric Hodel: "query" -- Query for a list of gems

2010-02-12T06:12:52Z

gem query will list all gems matching a particular criteria.
The domain may be local, remote or both.

Usage

Usage: gem query [options]

  Options:
    -n, --name-matches REGEXP        Name of gem(s) to query on maches the provided REGEXP
    -d, --[no-]details               Display detailed information of gem(s)
    -l, --local                      Restrict operations to the LOCAL domain (default)
    -r, --remote                     Restrict operations to the REMOTE domain
    -b, --both                       Allow LOCAL and REMOTE operations

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Summary:
    Query gem information in local or remote repositories

  Defaults:
    --local --name-matches '.*' --no-details

Examples

To list all local gems with a digit in the gem name:

$ gem query -n '[0-9]' --local

*** LOCAL GEMS ***

jabber4r (0.7.0)
    Jabber4r is a pure-Ruby Jabber client library

log4r (1.0.5)
    Log4r is a comprehensive and flexible logging library for Ruby.

To list all remote gems that begin with the letter ‘m’:

$ gem query -R -n ^m

*** REMOTE GEMS ***

madeleine (0.6.1, 0.6)
    Madeleine is a Ruby implementation of Object Prevalence

midilib (0.8.0)
    MIDI file and event manipulation library

Eric Hodel: "list" -- List gems starting with a string

2010-02-12T06:12:38Z

gem list will list all gems whose name starts with the given
string. If no string is provided, all gems are listed.

Usage

Usage: gem list [STRING] [options]

  Options:
    -d, --[no-]details               Display detailed information of gem(s)
    -l, --local                      Restrict operations to the LOCAL domain (default)
    -r, --remote                     Restrict operations to the REMOTE domain
    -b, --both                       Allow LOCAL and REMOTE operations

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    STRING   start of gem name to look for

  Summary:
    Display all gems whose name starts with STRING

  Defaults:
    --local --no-details

Examples

List all remote gems starting with “a”.

$ gem list -r a

*** REMOTE GEMS ***

activerecord (0.8.4, 0.8.3, 0.8.2, 0.8.1, 0.8.0, 0.7.6, 0.7.5)
    Implements the ActiveRecord pattern for ORM.

arrayfields (3.3.0)
    Allow keyword access to arrays

List all gems, local and remote.

$ gem list --both

*** LOCAL GEMS ***

  ...

*** REMOTE GEMS ***

  ...

Eric Hodel: "install" -- Installing a gem

2010-02-12T06:12:28Z

gem install will install the named gem. It will
attempt a local installation (i.e. a .gem file in the current
directory), and if that fails, it will attempt to download and install
the most recent version of the gem you want.

If a gem is being installed remotely, and it depends on other gems
that are not installed, then gem will download and install those,
after you have confirmed the operation.

Usage

Usage: gem install GEMNAME [options]

  Options:
    -v, --version VERSION            Specify version of gem to install
    -l, --local                      Restrict operations to the LOCAL domain (default)
    -r, --remote                     Restrict operations to the REMOTE domain
    -b, --both                       Allow LOCAL and REMOTE operations
    -i, --install-dir DIR
    -d, --[no-]rdoc                  Generate RDoc documentation for the gem on install
    -f, --[no-]force                 Force gem to install, bypassing dependency checks
    -t, --[no-]test                  Run unit tests prior to installation
    -w, --[no-]wrappers              Use bin wrappers for executables
                                     Not available on dosish platforms
    -P, --trust-policy POLICY        Specify gem trust policy.
        --ignore-dependencies        Do not install any required dependent gems
    -y, --include-dependencies       Unconditionally install the required dependent gems

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME   name of gem to install

  Summary:
    Install a gem into the local repository

  Defaults:
    --both --version '> 0' --rdoc --no-force --no-test
    --install-dir /usr/local/lib/ruby/gems/1.8

Examples

These examples show how GEMNAME can be specified:

This will install local ‘copland.gem’ or remote ‘copland-0.3.0’ (for
instance), but not a local file ‘copland-0.3.0’ gem.

gem install copland

This will install local ‘copland-0.2.0’ or remote ‘copland-0.2.0’.

gem install copland-0.2.0

This will only succeed if the local file exists. This will not resolve to a remote gem.

gem install copland-0.2.0.gem

  gem install --remote copland         # shortcut: gem ins -R copland
  gem install copland --version '> 0.2'
  gem install copland --gen-rdoc --run-tests
  gem install copland --install-stub

Here is an example session where a dependency is automatically
downloaded and resolved.

$ gem install copland
Attempting local installation of ''
Local gem file not found: copland.gem
Attempting remote installation of 'copland'
Install required dependency log4r? [Yn]   y
Successfully installed copland, version 0.3.0

Eric Hodel: "help" -- Provide help about gem commands

2010-02-12T06:12:13Z

gem help provides information about the syntax and options
available on the gem command.

Usage

Usage: gem help ARGUMENT [options]

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    commands      List all 'gem' commands
    examples      Show examples of 'gem' usage
    <command>     Show specific help for <command>

  Summary:
    Provide help on the 'gem' command

Eric Hodel: "environment" -- Display information about the gem environment

2010-02-12T06:12:00Z

Gems uses several paths and directories to perform its work. This
command will display the information the gem command has found.

Usage

Usage: gem environment [args] [options]

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    packageversion  display the package version
    gemdir          display the path where gems are installed
    gempath         display path used to search for gems
    version         display the gem format version
    remotesources   display the remote gem servers
    <omitted>       display everything

  Summary:
    Display RubyGems environmental information

Examples

$ gem environment
Rubygems Environment:
  - VERSION: 0.6 (0.6.1)
  - INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/1.8
  - GEM PATH:
     - /usr/local/lib/ruby/gems/1.8
  - REMOTE SOURCES:
     - http://gems.rubyforge.org

Eric Hodel: "dependency" -- List the dependencies of a gem

2010-02-12T06:11:52Z

The dependency command displays the declared dependencies of any install gem package.

Usage

Usage: gem dependency GEMNAME [options]

  Options:
    -v, --version VERSION            Specify version of gem to uninstall
    -r, --[no-]reverse-dependencies  Include reverse dependencies in the output
    -p, --pipe                       Pipe Format (name --version ver)

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME   name of gems to show

  Summary:
    Show the dependencies of an installed gem

  Defaults:
    --version '> 0' --no-reverse

Examples

Here is the dependencies of the Rails gem.

$ gem dependency rails -v 0.10.1
Gem rails-0.10.1
  Requires
    rake (>= 0.4.15)
    activesupport (= 1.0.1)
    activerecord (= 1.8.0)
    actionpack (= 1.5.1)
    actionmailer (= 0.7.1)
    actionwebservice (= 0.6.0)

Adding a --reverse-dependencies option adds the following bit of information:

$ gem dependency rails -v 0.10.1 --reverse-dependencies
Gem rails-0.10.1
  Requires
    rake (>= 0.4.15)
    activesupport (= 1.0.1)
    activerecord (= 1.8.0)
    actionpack (= 1.5.1)
    actionmailer (= 0.7.1)
    actionwebservice (= 0.6.0)
  Used by
    storycards-0.0.2 (rails (>= 0.7.0))

Finally, the --pipe option for the dependency command puts out the dependencies in a format that could be piped to another command.

$ gem dependency rails -v 0.10.1 --pipe
rake --version '>= 0.4.15'
activesupport --version '= 1.0.1'
activerecord --version '= 1.8.0'
actionpack --version '= 1.5.1'
actionmailer --version '= 0.7.1'
actionwebservice --version '= 0.6.0'

Eric Hodel: "contents" -- Display the files contained in an installed gem

2010-02-12T06:11:44Z

(new in version 0.8.11)

The contents command will list the full path names of all the files
contained in the gem.

Usage

Usage: gem contents [options]

  Options:
    -l, --list                       List the files inside a Gem
    -V, --version                    Specify version for gem to view
    -s, --spec-dir a,b,c             Search for gems under specific paths
    -v, --verbose                    Be verbose when showing status

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Summary:
    Disply the contents of the installed gems

Examples

The following command displays the files included in the Rake gem.

$ gem contents rake
traken$ gem inspect rake
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/install.rb
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/CHANGES
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/Rakefile
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/README
/usr/local/lib/ruby/gems/1.8/gems/rake-0.5.4.3/TODO
[... truncated ...]

Limitations

Currently there is no way to specify the version of the gem you wish
to view.

Eric Hodel: "cleanup" -- Cleanup old versions in the repository

2010-02-12T06:11:35Z

(new in version 0.8.7)

This command will remove (uninstall) all the versions of a gem, except
for the latest one. If no gemname is given in the command line, cleanup will be run agains all installed gems.

Usage

Usage: gem cleanup [options]

  Options:
    -d, --dryrun

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME(s)   name of gem(s) to cleanup

  Summary:
    Cleanup old versions of installed gems in the local repository

  Defaults:
    --no-dryrun

Examples

$ gem cleanup
Rubygems Environment:
  - VERSION: 0.6 (0.6.1)
  - INSTALLATION DIRECTORY: /usr/local/lib/ruby/gems/1.8
  - GEM PATH:
     - /usr/local/lib/ruby/gems/1.8
  - REMOTE SOURCES:
     - http://gems.rubyforge.org

Eric Hodel: "check" -- Check installed gems for problems

2010-02-12T06:11:27Z

The check command is used to verify that a gem in is good working order.

Usage

Usage: gem check [options]

  Options:
    -v, --verify FILE                Verify gem file against its internal checksum
    -a, --alien                      Report 'unmanaged' or rogue files in the gem repository
    -t, --test                       Run unit tests for gem
    -V, --version                    Specify version for which to run unit tests

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Summary:
    Check installed gems

The verify option checks a gem file for corruption. If the file is
not exactly like it was built, verify will complain. (Note: This is a
simple integrity check. It is not checking for PGP like signatures).

The alien option checks an installed gem to see if any of the files
have been tampered with.

Examples

The following check is run against a valid rake gem file.

$ gem check -v pkg/rake-0.4.0.gem 
Verifying gem: 'pkg/rake-0.4.0.gem'

The following check shows that the rake gem file is invalid.

$ gem check -v pkg/rake-0.4.0.gem
Verifying gem: 'pkg/rake-0.4.0.gem'
ERROR:  pkg/rake-0.4.0.gem is invalid.

In this installation of ActiveRecord, the postgreSQL driver
has been locally patched after the gem was installed. This is how the alien
option reports it.

$ gem check --alien
Performing the 'alien' operation
madeleine-0.6 is error-free

madeleine-0.6.1 is error-free

rake-0.4.0 is error-free

rake-0.3.2 is error-free

copland-0.3.0 is error-free

sources-0.0.1 has 2 problems

iterator-0.5 is error-free

activerecord-0.8.1 has 2 problems
	lib/active_record/connection_adapters/postgresql_adapter.rb:
	installed file doesn't match original from gem

	/usr/local/lib/ruby/gems/1.8/cache/activerecord-0.8.1.gem:
	Unmanaged files in gem: ["lib/active_record/connection_adapters/postgresql_adapter.rb~"]


[... remaining output elided ...]

Eric Hodel: "cert" -- Support signing and managing signed gems

2010-02-12T06:11:18Z

The cert command manages the certificates needed to sign gems.

Usage

Usage: gem cert [options]

  Options:
    -a, --add CERT                   Add a trusted certificate.
    -l, --list                       List trusted certificates.
    -r, --remove STRING              Remove trusted certificates containing STRING.
    -b, --build EMAIL_ADDR           Build private key and self-signed certificate for EMAIL_ADDR.
    -C, --certificate CERT           Certificate for --sign command.
    -K, --private-key KEY            Private key for --sign command.
    -s, --sign NEWCERT               Sign a certificate with my key and certificate.

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Summary:
    Adjust RubyGems certificate settings.

See the chapter on signing
gems in the :Ruby Users
Guide":http://docs.rubygems.org/read/book/1 for details.

Examples

Build a private key and certificate for gemmaster@example.com.
Substitute your own email address for your own certificates.

$ gem cert --build gemmaster@example.com

Add a certificate to the list of trusted certificates. The trusted
certificate list will be consulted when installing signed gems.

$ gem cert --add gem-public_cert.pem

Sign a certificate with the specified key and certificate (note that
this modifies client_cert.pem!)

$ gem cert \
     -K /mnt/floppy/issuer-priv_key.pem \
     -C issuer-pub_cert.pem \
     --sign client_cert.pem

Eric Hodel: "build" -- Build a gem file from a specification

2010-02-12T06:11:07Z

The build command is used by developers to package their Ruby software
into a single gem file that can be distributed. The build command
requires a gemspec file to describe the metadata in the packge. You
can see a good example of using build in CreateAGemInTenMinutes.

A yaml file containing the Gem::Specification object built by a
gemspec (instead of a gemspec file) may also be also be used with the
build command.

Usage

Usage: gem build GEMSPEC_FILE [options]

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMSPEC_FILE      name of gemspec file used to build the gem

  Summary:
    Build a gem from a gemspec

Examples

This example builds a the rake package from a gemspec file.

$ gem build rake.gemspec 
Attempting to build gem spec 'rake.gemspec'
  Successfully built RubyGem
  Name: rake
  Version: 0.4.0
  File: rake-0.4.0.gem

Of course, rake isn’t normally built from a gemspec. It uses a
special gem building task to build the gem directly from the rakefile.
See CreateAGemUsingRake for more details.

$ rake gem
(in /home/jim/working/rubyforge/rake)
  Successfully built RubyGem
  Name: rake
  Version: 0.4.0
  File: rake-0.4.0.gem

Eric Hodel: update -- Update your installed gems

2010-02-12T06:09:30Z

The update command will check the named gem (or all of your installed
gems if no name is given) and update each one to a newer version if
one is available.

Usage

Usage: gem update [options]

  Options:
    -i, --install-dir DIR
    -d, --[no-]rdoc                  Generate RDoc documentation for the gem on install
    -f, --[no-]force                 Force gem to install, bypassing dependency checks
    -t, --[no-]test                  Run unit tests prior to installation
    -w, --[no-]wrappers              Use bin wrappers for executables
                                     Not available on dosish platforms
    -P, --trust-policy POLICY        Specify gem trust policy.
        --ignore-dependencies        Do not install any required dependent gems
    -y, --include-dependencies       Unconditionally install the required dependent gems
        --system                     Update the RubyGems system software

  Common Options:
        --source URL                 Use URL as the remote source for gems
    -p, --[no-]http-proxy [URL]      Use HTTP proxy for remote operations
    -h, --help                       Get help on this command
        --config-file FILE           Use this config file instead of default
        --backtrace                  Show stack backtrace on errors
        --debug                      Turn on Ruby debugging

  Arguments:
    GEMNAME(s)   name of gem(s) to update

  Summary:
    Upgrade the named gem (or all installed gems) in the local repository

  Defaults:
    --rdoc --no-force --no-test
    --install-dir /usr/local/lib/ruby/gems/1.8

Examples

$ gem update
Upgrading installed gems...
Attempting remote upgrade of activerecord
Attempting remote installation of 'activerecord'
Successfully installed activerecord, version 0.8.4
Attempting remote upgrade of csbattery
Attempting remote installation of 'csbattery'
Successfully installed csbattery, version 0.2.2
All gems up to date

Eric Hodel: "which" -- locate library files

2010-02-12T06:08:21Z

gem which works much like the unix shell ‘which’ command. Given a include file reference, it will locate that file in ruby libraries and gem repositories and display the file path for the file.

For example, if you would like to know where the rake/testtask file might be located, just type:

$ gem which rake/testtask
/usr/local/lib/ruby/gems/1.8/gems/rake-0.4.15/lib/rake/testtask.rb

gem which will work with regular (non-gem) Ruby libraries as well.

$ gem which socket
/usr/local/lib/ruby/1.8/i686-linux/socket.so

See gem help which for usage information.

Eric Hodel: Installing RubyGems

2010-02-09T23:55:05Z

Get it from RubyForge (http://rubyforge.org/frs/?group_id=126) and run (as root, if appropriate and necessary)

ruby setup.rb

It’s easy. It installs the required library files and the gem command. This command gives us the power to do everything else in this document, except distribute gems (for now!).

Debian and Ubuntu: Debian and Ubuntu do not automatically include all the standard Ruby libararies in the basic Ruby package. As a result, you may need to ‘’apt-get’’ libyaml-ruby and libzlib-ruby before you can install rubygems. Additionally, you may need to install ruby-dev in order to install gems that have C extensions.

Ryan Davis: Building a gem

2010-01-26T23:15:39Z

This is a skimpy overview; see the DeveloperGuide for the real meat.

Let’s say we have a package called ’’mygem’’ which is at version 2.1.

Building a gem involves two steps:

creating a gem specification file (mygem.gemspec), which is Ruby code; and
running gem build mygem.gemspec to create the gem file (mygem-2.1.gem)

The specification contains Ruby code to create a Gem::Specification object, which defines all of the information we saw above in Looking at an installed gem.

The gem file contains everything needed to install itself on another computer, including the specification and all the file data.

See? Building a gem is very easy!

Note: rake (http://rake.rubyforge.org) is a big help in creating gem files in a project setting, where the version number is always changing, etc.