2. Using RubyGems
This chapter gives examples of the most common user opertions performed with the gem command. See the gem Command Reference manual for details about particular gem commands.
Versioning is a pretty basic concept in RubyGems. You might want to glance at the Specifying Versions chapter for a better understanding of how versions work with RubyGems.
When you run
gem query --remote # shortcut: gem q -R
you see will a detailed list of all the gems on the remote server.
Sample output (heavily abbreviated):
*** 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. BlueCloth (0.0.4, 0.0.3, 0.0.2) BlueCloth is a Ruby implementation of Markdown, a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). captcha (0.1.2) Ruby/CAPTCHA is an implementation of the 'Completely Automated Public Turing Test to Tell Computers and Humans Apart'. cardinal (0.0.4) Ruby to Parrot compiler. cgikit (1.1.0) CGIKit is a componented-oriented web application framework like Apple Computers WebObjects. This framework services Model-View-Controller architecture programming by components based on a HTML file, a definition file and a Ruby source. progressbar (0.0.3) Ruby/ProgressBar is a text progress bar library for Ruby. It can indicate progress with percentage, a progress bar, and estimated remaining time. rake (0.4.0, 0.3.2) Ruby based make-like utility.
The progressbar gem is a nice and simple utility that we will use to demonstrate further features.
When you run
gem query --remote --name-matches doom # shortcut: gem q -R -n doom
you will see a detailed list of matching gems on the remote server.
*** REMOTE GEMS *** ruby-doom (0.8, 0.0.7) Ruby-DOOM provides a scripting API for creating DOOM maps. It also provides higher-level APIs to make map creation easier.
When you run (as root, if appropriate and necessary)
gem install --remote progressbar # shortcut: gem i -r progressbar
the progressbar gem will be installed on your computer. Notice that you don’t need to specify the version, but you can if you want to. It will default to the last version available.
gem ins -r progressbar-0.0.3
gem ins -r progressbar --version '> 0.0.1'
In both cases, the output is simply:Attempting remote installation of ‘progressbar’ Successfully installed progressbar, version 0.0.3
RubyGems allows you to have multiple versions of a library installed and choose in your code which version you wish to use.
Useful extra options for installation are —gen-rdoc for generating the gem’s RDoc API documentation, and —run-tests to run the gem’s unit tests, if any.
Note too that when you remotely install a gem, it will download and install any specified dependencies. Try installing copland and see that it prompts you to accept log4r as well (if it’s not already installed).
When you run
gem specification progressbar # shortcut: gem spec progressbar
you will see all the details of the ’’progressbar’’ gem.
--- !ruby/object:Gem::Specification rubygems_version:"1.0\" name: progressbar version: !ruby/object:Gem::Version version: 0.0.3 date: 2004-03-20 20:03:00.679937 +11:00 platform: summary: "Ruby/ProgressBar is a text progress bar library for Ruby. It can indicate progress with percentage, a progress bar, and estimated remaining time." require_paths: - lib files: - sample/test.rb - lib/progressbar.rb - docs/progressbar.en.rd - docs/progressbar.ja.rd - ChangeLog autorequire: progressbar author: Satoru Takabayashi email: email@example.com homepage: http://namazu.org/~satoru/ruby-progressbar/
Some interesting information includes the author’s details, the version and description of the gem.
There is also important technical information for RubyGems to use this gem properly. This includes the list of files included, where to include files from, and what to require by default (more on this later).
If we’ve finished with progressbar, we can uninstall it.
gem uninstall progressbar
Successfully uninstalled progressbar version 0.0.3
If there are more than one version of a gem installed, the gem command will ask you which version to delete.
If there are other gems that depend upon the gem being uninstalled, and if there is no other way to satisfy that dependency, then the user will be will be given a warning and allowed to cancel the uninstall.
gem query --local # shortcut: 'gem q -L'
You’ve no doubt noticed the —local and —remote options on most of the command lines shown so far. If you don’t specify either of these, then gem will (usually) try ’’both’’ a local and remote operation. For example:gem ins rake # Attempt local installation; go remote if necessary gem list -b ^C # List all local AND remote gems beginning with “C”
You can run your own gem server. This means other people can (potentially) install gems ‘’from your computer’’. And as a side-effect of that, you can view your installed gems through your web browser. Just run
and point your browser to http://localhost:8808.
You’ll be able to view the documentation for each gem, as long as you asked for it to be generated when you installed it.
If you want to always generate RDoc documentation and run unit tests for each gem you install, then you can specify these command-line options in a config file (.gemrc in your home directory).
gem: --rdoc --test
There are other things you can achieve with a config file (RDoc parameters, GEMPATH settings). See `gem help env` for the details.
gem check —alien will report on any rogue (unmanaged) files in the RubyGems repository area.
gem check —verify progressbar will check that the installed ’’progressbar’’ gem is valid against its own checksum.