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.

Similar to josh and jbarnette, I use this rbdev shell function to activate bin, lib, and ext dirs when I'm working on a project:

# develop out of the current directory.
rbdev() {
    local useful dir
    test -d ./bin && {
        useful=yes
        PATH="$(pwd)/bin:$PATH"
        echo "./bin on \$PATH"
    }
    test -d ./ext && {
        useful=yes
        for dir in ./ext/*
        do
            test -d "$dir" || continue
            RUBYLIB="$(pwd)/$dir:$RUBYLIB"
            export RUBYLIB
            echo "$dir on \$RUBYLIB"
        done
    }
    test -d ./lib && {
        useful=yes
        RUBYLIB="$(pwd)/lib:$RUBYLIB"
        export RUBYLIB
        echo "./lib on \$RUBYLIB"
    }
    test -z "$useful" && {
        echo "no ./lib or ./bin detected. help me help you."
        return 1
    }
}

When I'm working on e.g., RDiscount, I do something like:

$ cd ~/git/rdiscount
$ rbdev
./bin on $PATH
./ext on $RUBYLIB
./lib on $RUBYLIB

Not setting up the load path from executables has been a problem, though. People assume everything is broken when they get a LoadError + backtrace after checking out a project for the first time and running an executable. I really wish these techniques for setting up development environments would become common practice. I'm thinking a template HACKING file that explained basic environment prep would probably go a long way.

@chneukirchen Would you mind moving this discussion to ruby-talk? It's hard to quote and inline-reply to the various tangents here. And it's easy for questions to get lost in the noise. Also, I'm sure the vast number of Rubyists on ruby-talk would have valuable feedback on this spec. Thanks.

Please discuss now at:

• http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/361459
• ruby-talk:361459
• http://groups.google.com/group/comp.lang.ruby/browse_thread/thread/ab8b8725494fb492
• <871veavb1v.fsf@gmail.com>