RPS-SPEC

= Ruby Packaging Standard

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.)

== Library files

Library code MUST reside in lib/.

Libraries SHOULD use a directory as namespace, e.g. lib/foo.rb and lib/foo/**.

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

Libraries MUST not require 'rubygems' or modify the $LOAD_PATH.

Ruby library files MUST end with .rb.

Library files SHOULD be installed with mode 0644.

== Executables

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,
unless they are specifically made for doing that (e.g. package managers).

Executable files SHOULD NOT end with .rb.

Executable files SHOULD be installed with mode 0755.

== Extensions

Extensions are directories which contain a extconf.rb.

Extensions SHOULD reside in ext/.

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

XXX How to install, how to find out what was built.

== Data files

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

XXX Or data/<projectname>?

XXX Where to install to, how to find out that place from the program?

== Tests

Tests SHOULD reside in test/ or spec/.

== History

09apr2010: First initial draft.
10apr2010: Fix binary permissions.
10apr2010: Add data files.