Ruby Packaging Standard, 0.5-draft

The aim of this document is two-fold. First, to specify a common structure of how a Ruby package distributed as source (that is, but not limited to, development directories, version-controlled repositories, .tar.gz, Gems, …) should conform to.

Second, to document common and proven ways to structure Ruby packages, and to point out certain anti-patterns that sneaked into common use. It is by intent not to innovate.

(See RFC 2119 for use of MUST, SHOULD, SHALL.)


Project names SHOULD only contain underscores as separators in their names.

If a project is an enhancement, plugin, extension, etc. for some other project it SHOULD contain a dash in the name between the original name and the project’s name.

File names and directory structure SHOULD correspond like this:

Library: foo-bar
Directory: lib/foo/bar
Namespace: Foo::Bar

Library: foo_bar
Directory: lib/foo_bar
Namespace: FooBar

Library files

Library code MUST reside in lib/.

Libraries SHOULD use a directory as namespace, e.g. lib/foo.rb and lib/foo/**. (And, see above, thus limit their code to a module Foo.)

Libraries SHOULD NOT require code of the project that are outside of lib/.

Libraries MUST NOT require 'rubygems' or modify the $LOAD_PATH, unless they are specifically made for doing that (e.g. package managers).

Ruby library files MUST end with .rb.

Library files SHOULD be installed with mode 0644.


Executables MUST reside in bin/.

Ruby executables SHOULD have a shebang line using env:

#!/usr/bin/env ruby

Executables SHOULD NOT require code of the project that are outside of lib/.

Executables SHOULD NOT require 'rubygems' or modify the $LOAD_PATH.

Executable files SHOULD NOT end with .rb.

Executable files SHOULD be installed with mode 0755.


Extensions are directories which contain a extconf.rb.

Extensions SHOULD reside in ext/.

Extensions SHOULD be buildable with ruby extconf.rb; make.

Files ending with .so, .dylib, .bundle, .dll, .exe are considered compiled extensions to be installed.

Extensions SHOULD be installed into an architecture-specific directory.

Data files

Data files and resources of the project belong to data/$projectname.

Data files SHOULD be found at runtime using:

require 'rbconfig'
require 'rbconfig/datadir'
path = Config.datadir('$projectname')

XXX find a way to make this work from checkouts, and with several package management mechanisms being used.


Tests SHOULD reside in test/ or spec/.