A comprehensive guide to finding, creating and using Ruby resources called gems.
Specification Explained

platform determines for what platform the gem is meant. If you are just using pure Ruby, it can stay with this default. This flag becomes very important when you are shipping precompiled gems.

name, version, author, email and summary provide basic information about the gem and its author. This is how users can find out who is responsible for the code.

files defines the list of files that are to be included in the gem. The FileList command is provided by rake, which does two things that make life easier. First, it handles globs (*) and patterns meaning that you can grab a lot of files easily. It also understands that certain files should be excluded. By default, it excludes CVS, svn, bak and core files.

require_path is set to determine what directories should be searched for code. The value for this would change if you were building extensions in the ext.

autorequire designates which file will be loaded when require ipadmin is called in code. ipadmin.rb in this module handles requiring the other three libraries that ship with ipadmin.

test_files is a list of files that should be executed when the gem is installed if the user adds the -t argument to the gem install. This is a way to provide safety checks to make sure everything worked after the gem is installed.

has_rodc is a way to tell gem you have included rdoc tags in the code. If this flag is false or missing, gem will not generate documentation automatically.

extra_rdoc_files allows you to include other files in the documentation that is generated by gem. In this case, the README file is being linked into the document ion. If you had other documents, they could be listed here.

Because IPAdmin is a very simple project, it does not include one very useful command: add_dependency. If you build a gem that depends on another gem, this command allows these dependencies to be specified. You even can tie it to a version number in the same way you can with require_gem. When you install a gem that has a dependency, gem checks to see if it is met. If it is not met, gem offers to install it. To add a dependency on rake, you could add this to the spec definition:


Signing Gems

Thanks to a patch from Paul Duncan, the latest version of RubyGems (0.8.11) now has some features to support signing your gems using a public/private key. This introduces some new options for the gem specification (signing_key and cert_chain). This change also allows you to install gems in a high-security mode that will install only gems that are signed by trusted sources. Because the feature itself is very new, some pieces of infrastructure to make it useful in the greater scheme of things are missing—namely, an easy way to build up a chain of trust so that end users do not have to add certificates for every single gem author out there. That being said, these features might be useful if you want to control gems inside your network across a lot of servers. You could download them once and sign them with an internal certificate. Then, you could update all your servers by requesting gems from the server where you distribute these signed gems. Duncan has written a great overview of getting started with gem signing on the RubyGems Manuals site (see Resources).


Now that you have a gem, you probably want to share it. There are several ways to distribute your code. The simplest way is to host the file. When people want to install it, they can download the file and run gem in the same directory.

The second option is to host the project at RubyGems ships with RubyForge as the default source for gems. RubyForge even runs a special script so that once you upload your new gem to your account, it automatically is available to all users of RubyGems.

Assuming you do not want to use RubyForge, there are two options left to make it possible to distribute your gem via RubyGems. First, you need to run your own server. The easiest way to do that is to simply fire up gem_server. It automatically shares gems with anyone who connects to it.

The other option is to cd to a directory inside of the webroot of an existing Web server. Create a directory called gems, and copy all the gems you want to distribute into that directory.

Run the following command, and replace DIR with the full path to the directory above the gems directory. This creates yaml and yam.Z files:

generate_yaml_index.rb -d DIR

You need to re-run the script anytime you modify the gems you are serving. Keep in mind that if you use either of these options, your users have to add the --source URL_OF_YOUR_SITE to the gem install command. This allows gem to search that site for gems.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

the option --include-dependencies is the default

Jian Lin's picture

gem install rails --include-dependencies

can be

gem install rails



is now the default on the current gem 1.3.7


Anonymous's picture

Thank you for this article, posted on May 27, 2006 and still helping people!;)

nice stuff

Kanuverleih's picture

Thank You for another very interesting article.
It’s really good written and I fully agree with You
on main issue, btw. I must say that I really enjoyed
reading all of Your posts. It’s interesting to read ideas,
and observations from someone else’s point of view… it makes
you think more. So please try to keep up the great work all the time.