Category list

Recipe 18.4. Uninstalling a Gem

Problem

You want to remove an installed gem from your Ruby installation.

Solution

From the command line, use the gem uninstall command:

$ gem uninstall blinkenlights
	Attempting to uninstall gem 'blinkenlights'
	Successfully uninstalled blinkenlights version 0.0.2

From Ruby code, the most reliable way to uninstall a gem is to simulate a command-line invocation with the Gem::GemRunner class. This code installs a gem, then immediately removes it:

require 'rubygems'
	require 'rubygems/installer'
	require 'rubygems/remote_installer'
	Gem::RemoteInstaller.new.install('blinkenlights')

	require 'rubygems/gem_runner'
	require 'rubygems/doc_manager'
	Gem.manage_gems
	Gem::GemRunner.new.run(['uninstall', 'blinkenlights'])
	# Successfully uninstalled blinkenlights version 0.0.4

Uninstalling a gem can disrupt the normal workings of your Ruby programs, so I recommend you only uninstall gems from the command line. That way, there's less chance of a bug wiping out all your gems.

Discussion

Since rubygems can manage multiple installed versions of the same gem, you won't usually have to remove old copies of gems. There are three main reasons to remove gems:

You find out that a particular version of a gem is buggy , and you want to make sure it never gets used.
You want to save disk space.
You want to clean up the list of installed gems so that it's more obvious which gems you actually use.

If uninstalling a gem would leave another installed gem with an unmet dependency, you'll be told about the dependency and asked whether you want to go through with the uninstall anyway. You'll get this interactive prompt whether you run the gem uninstall command or whether you use the Gem::Uninstaller class from Ruby code.

Gem::Uninstaller.new('actionpack', {}).uninstall
	# You have requested to uninstall the gem:
	#        actionpack-1.8.1
	# actionmailer-0.9.1 depends on [actionpack (= 1.8.1)]
	# If you remove this gem, the dependency will not be met.
	# Uninstall anyway? [yN]

The sources gem is a special gem that tells rubygems to look for remotely installable gems at http://gems. rubyforge .org/ by default. If you uninstall this gem, you won't be able to install any more gems, except through complicated hacks of the classes in the Gem module. Just don't do it. Not even if you never plan to install any gems from rubyforge.org. Not even if you'd never thought of doing it until I brought it up in this recipe, and now you're curious .

You did it, didn't you? Now you'll have to reinstall rubygems by rerunning its setup.rb script.

Recipe 18.5. Reading Documentation for Installed Gems

Problem

You want to read the RDoc documentation for the gems you have installed. Although some gem projects provide human-written documentation like tutorials, the generated RDoc documentation isn't usually available online.

Solution

RDoc documentation isn't usually available online because when you install a gem, Ruby generates your very own HTML copy of the RDoc documentation and installs it along with the software. The documentation you need is probably already on your computer.

The simplest way to browse the documentation for your installed gems is to run the gem_server command, then visit http://localhost:8808/ . You'll see all your installed gems in a table form, and be able to browse the generated documentation of each gem that provides any.

Otherwise, you can find your Rubygems documentation directory, and browse the installed documentation with local filesystem tools.

Discussion

The generated rdoc for a gem is kept in the doc/ subdirectory of the base directory in which the gem was installed. For instance, on my computer, gems are installed in /usr/lib/ruby/gems/1.8/ . For every gem that has RDoc, the generated HTML documentation will be kept in the directory /usr/lib/ruby/gems/1.8/doc/[gem name ]/rdoc/ . If I were to install one particular gem to another directory, the documentation for the gem would be in a doc/ subdirectory of that directory.

Here's some code that prints out the location of the RDoc files for every installed gem. Unless you've installed specific gems in nonstandard locations, they'll all be in the doc/ subdirectory of Gem.dir . This code snippet also shows off some of the capabilities of Gem::DocManager , the Ruby class you can use to manipulate a gem's RDoc.

require 'rubygems'
	Gem.manage_gems

	def show_gem_rdoc
	  puts "Your generated docs are all probably in #{File.join(Gem.dir, "doc")}"

	  puts "Just to be safe, I'll print out every gem's RDoc location:"
	  specifications_dir = File.join(Gem.dir, 'specifications')
	  lacking_rdoc = []
	  Gem::SourceIndex.from_installed_gems(specifications_dir).each do path, spec
	    manager = Gem::DocManager.new(spec)
	    if manager.rdoc_installed?
	      doc_path = File.join(spec.installation_path, 'doc', spec.full_name)
	      puts " #{spec.full_name} => #{doc_path}"
	    else
	      lacking_rdoc << spec.full_name
	    end
	  end

	  unless lacking_rdoc.empty?
	    puts "\nThese installed gems have no RDoc installed:"
	    puts " #{lacking_rdoc.join("\n ")}"
	  end
	end

	show_gem_rdoc
	# Your generated RDoc is probably all in /usr/lib/ruby/gems/1.8/doc
	# Just to be safe, I'll print out every gem's RDoc location:
	#  flexmock-0.1.7 => /usr/lib/ruby/gems/1.8/doc/flexmock-0.1.7
	#  simple-rss-1.1 => /usr/lib/ruby/gems/1.8/doc/simple-rss-1.1
	#  classifier-1.3.0 => /usr/lib/ruby/gems/1.8/doc/classifier-1.3.0
	#  actionmailer-1.1.5 => /usr/lib/ruby/gems/1.8/doc/actionmailer-1.1.5
	# …
	#
	# These installed gems have no RDoc installed:
	#  Ruby-MemCache-0.0.1
	#  RedCloth-3.0.4
	#  sources-0.0.1
	# …

RDoc is generated for most gems whether or not the author was careful to add RDoc descriptions to all their Ruby code. At minimum, a gem's RDoc will list the classes and methods present in the gem, which is useful in a bare-bones way.

If you don't want to generate RDoc when you install a gem, pass in the --no-rdoc argument to the gem install command. The only real reason to do this is a concern for disk space.

The flip side of reading a gem's documentation is writing it. When you're writing your gemspec (see Recipe 18.6), you should set spec.has_rdoc = true . This will let the end user 's gem installer know that your gem was written with RDoc in mind. It doesn't do much except suppress a warning during the installation of your gem.