edit

RubyGems Deprecations

drbrain | Thu, 19 May 2011 01:03:47 GMT

Posted in Rubygems

I've been maintaining RubyGems a long, long time now. I believe my first release was 0.9.5 back at the end of 2007, four and a half years! In that time I've looked at pretty much every line of RubyGems. I know the history and intent behind most of the classes that exist in RubyGems and what purposes they served. (For more on that history watch my RubyConf 2010 presentation, History of RDoc and RubyGems.)

One thing I haven't done enough of in RubyGems is cleanup of the little things that make RubyGems easy to use as a library. While I've done some work to make it easier to use as a library I've ignored too many of the little things that make a polished library. Over the past several releases Ryan Davis has been driving these small cleanups to make RubyGems easier to use and maintain.

There are many things that are clumsy to do in RubyGems 1.7 and earlier due to poor encapsulation that are now clean, simple and intuitive in RubyGems 1.8.

Given a Gem::Specification, how do you activate it?

# RubyGems 1.8

spec.activate

# RubyGems 1.7 and older

Gem.activate spec.name, spec.version

Given a Gem::Specification, how do you determine various directories for files in the gem?

# RubyGems 1.8

spec.ri_dir
spec.cache_dir
spec.bin_dir
# etc.

# RubyGems 1.7 and older

File.join spec.installation_path, 'doc', 'ri'
File.join spec.installation_path, 'cache'
File.join spec.installation_path, 'gems', spec.full_name, 'bin'

How do you list the name of every gem you have installed?

# RubyGems 1.8

Gem::Specification.all_names

# RubyGems 1.7 and older

Gem.source_index.map { |_, s| s.full_name }

... and so on. While these look like trivial examples, the work underlying these changes is large. Also, note that for each of these examples the Ruby 1.7 and older code still works, but it will complain.

Deprecations

Gem::SourceIndex has been deprecated because it has no real purpose anymore. Back in the olden days before RubyGems 1.2 Gem::SourceIndex was used to determine which gems you could install (I cover this my RubyConf 2010 talk above). It got pressed into service as a local repository of gems as well, but since RubyGems 1.2 it's really become just a wrapper around a Hash.

Instead of keeping around the baggage of an ancient, mostly-useless Hash wrapper we've moved the important functionality into Gem::Specification as class methods. Now Gem::Specification behaves as an Enumerable container.

Gem::GemPathSearcher was used to figure out which files belonged to which gems so require 'rake' would activate the rake gem. Unfortunately its implementation was so complicated I could barely understand it let alone improve it.

Instead of keep around a complex, incomprehensible class we moved the functionality into Gem::Specification as well.

# RubyGems 1.8

spec = Gem::Specification.find_by_path 'rake'

# RubyGems 1.7 and older

spec = Gem.searcher.find 'rake'

Gem::Specification#default_executable has been deprecated as it was intended to be used for a feature that never was implemented. The idea behind it was a command like gem exec rake that would invoke the proper version of rake through RubyGems. Since this was never implemented we've deprecated the attribute.

In all, RubyGems releases since 1.4 have focused on cleaning up much of the historic cruft left behind after years of releases. We've properly encapsulated much of the functionality so it's implemented in a sensible place. Most of the deprecations we have made can be fixed by a single line change or running a single command.

Deprecation Warnings

I learned from the removal of #version_requirements that people will ignore deprecation warnings if you only output them once. When RubyGems 1.5 was released with the removal #version_requirements people were confused about why their Rails applications broke.

A single warning that prints every time you start your rails app and says Gem::Dependency#version_requirements is deprecated and will be removed on or after August 2010 can be swept under the rug, so for this release we decided to print warnings every time you use deprecated functionality.

Since we knew that users would need to update their gemspecs we provided the following instructions:

After installing RubyGems 1.8.0 you will see deprecations when loading your exsting gems. Run `gem pristine --all --no-extensions` to regenerate your gem specifications safely.

Currently RubyGems does not save the build arguments used to build gems with extensions. You will need to run `gem pristine gem_with_extension -- --build-arg` to regenerate a gem with an extension where it requires special build arguments.

These instructions were printed when you ran gem update --system and running the command would immediately solve the problem. They were also duplicated in my blog posts for the RubyGems 1.8.0, 1.8.1 and 1.8.2 (which also fixed a bug in gem pristine for some rvm users).

If you upgraded from RubyGems 1.7 to RubyGems 1.8.1 you may have missed the note about running gem pristine. We've changed our install process to print release notes from the version you're upgrading from to the version you're upgrading to.

The remaining deprecations should be rarely encountered as the deprecated functionality is rarely used outside RubyGems.

PS: If you write a library that interacts with RubyGems beyond require you should be on the RubyGems-developers mailing list. comments

Comments