leahneukirchen/RPS-SPEC

## RPS-SPEC
THIS DOCUMENT MOVED TO http://chneukirchen.github.com/rps/
AND http://github.com/chneukirchen/rps

= 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.
	THIS DOCUMENT MOVED TO http://chneukirchen.github.com/rps/
	AND http://github.com/chneukirchen/rps

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