Distributing Your Gems

Table of contents:

Problem

Youve packaged your software as a Ruby gem, but nobody knows about it. You want to make your gem easy to find and install, so that your genius does not go unrecognized.

Solution

The simplest solution (for you, at least) is to upload your .gem file to a web site or FTP site. Your users can download the .gem file, then install it by passing the filename into the gem install command:

	$ wget http://www.example.com/gems/my_gem-1.0.4.gem
	--10:40:10-- http://www.example.com/gems/my_gem-1.0.4.gem
	 => `my_gem-1.0.4.gem
	Resolving gems.example.com… 204.127.202.4
	Connecting to gems.example.com|204.127.202.4|:80… connected.
	HTTP request sent, awaiting response… 200 OK
	Length: 40,823 (40K) [text/plain]

	100%[====================================>] 40,823 46.96K/s

	10:40:11 (46.85 KB/s) - `my_gem-1.0.4.gem saved [40823/40823]

	$ gem install ./my_gem-1.0.4.gem
	Attempting local installation of ./my_gem-1.0.4.gem
	Successfully installed my_gem, version 1.0.4
	Installing RDoc documentation for my_gem-1.0.4…

If your gem has dependencies, the end user must separately install the dependencies before installing a downloaded gem, or the gem command will become confused and die. This will happen even if the user specifies the --include-dependencies flag:

	$ gem install --include-dependencies ./my_gem_with_dependency-1.0.0.gem
	Attempting local installation of ./my_gem_with_dependency.1.0.0.gem
	ERROR: Error installing gem ./my_gem_with_dependency-1.0.0.gem[.gem]:
	 my_gem_with_dependency requires my_dependency > 0.0.0

If you distribute your gem from a web site, be sure to set the homepage attribute in your gemspec file.

Discussion

Gems are usually distributed through HTTP. A web server might serve standalone .gem files intended for download by the end user, or it might also serve some metadata that allows the gem command to download and install gems on its own.

There are several ways of setting up gems for distribution. In general you must negotiate a tradeoff between the developers (your) convenience and the end users ease of installation. The Rubygems package makes it easy to install and manage third-party Ruby packages, but the developers of those packages have to jump through some hoops if they want to make the installation process as transparent as possible.

Simply uploading the raw gem files to your web site is the simplest solution from your point of view (assuming you already have a web site), but its less convenient for your users. This is especially true if your gem has dependencies. The most convenient solution for the end user is for you to upload your gem to the rubyforge.org site. Whenever you upload a .gem file to a project on this site, it is automatically mirrored to the canonical rubygems repository at http://gems.rubyforge.org/gems/. This is where the rubygems package looks for gems by default.

However, getting your gem onto rubyforge.org is more complicated than uploading a gem to your own web site. You must first sign up for a RubyForge account, giving the administrators your personal information. You must then submit a project (the name of the project should go into the rubyforge_project attribute in your gemspec) and have it approved by the site administrators.

Once your RubyForge project is set up, you can use the web interface to "create a new release" for your project, then upload your prebuilt gem to your projects file repository. Within a few minutes to a few hours, your gem will be mirrored to the main gem repository. From that point on, anybody with the rubygems package and Internet access can install your gem, along with any dependencies, simply by running gem install your_gem -include-dependencies. But for your smaller projects, the work you have to do to get to this point may seem like overkill

A compromise is to host the gem yourself on an existing web server, and also host the YAML metadata that lets the gem command locate, download, and install gems on its own. You can generate the YAML metadata with the generate_yaml_index.rb script that comes with the rubygems package. Put all your gems into a gems/ directory somewhere in your webspace, and pass in the parent of the gems/ directory as the --dir argument to generate_yaml_index.rb.

	$ cd ~/public_html/
	$ mkdir gems
	$ cp ~/mygem-1.0.0.gem gems/
	$ generate_yaml_index.rb --dir=~/public_html/ --verbose
	Building yaml file
	 … adding mygem-1.0.0
	Building yaml.Z file
	$ ls yaml*
	yaml yaml.Z

The yaml and yaml.Z files are intended for download by the various gem commands. Simply tell your users to pass in an appropriate --source argument to gem, and theyll be able to install gems from your web space just as they can from the canonical repository at RubyForge

The --source argument should correspond to the directory in your webspace that contains the yaml and yaml.Z files. For instance, if your ~/public_html/ directory in the example above corresponds to the URL http://www.example.com/~leonardr/, you should ask your users to install your gems with gem install --source=http://www.example.com/~leonardr/. Passing in a --source is more work than just getting everything from RubyForge, but once the user knows the URL, its not much more.

Note, however, that one invocation of the gem install command can only load gems from a single source. If you e hosting a gem that depends on other gems, you must assume the user has already installed the dependencies, or else provide copies of the dependency gems in the same gems/ directory as your own gems. If gem install is given a --source argument, it won know to look at gems.rubyforge.org as a backup.

If you don already have a web site, you can run a special web server that only serves gems. The rubygems package comes with an application called gem_server that acts as a web server providing copies of all the gems installed on your system. The best way to use this is as a private gem repository that distributes in-house Ruby gems throughout your team or organization.

Problem

Solution

Discussion

See Also