= ROLLING WITH RUBY

                  ____
              ,dP9CGG88@b,
            ,IP""YICCG888@@b,
           dIi   ,IICGG8888@b
          dCIIiciIICCGG8888@@b
  ________GCCIIIICCCGGG8888@@@________________
          GGCCCCCCCGGG88888@@@
          GGGGCCCGGGG88888@@@@...
          Y8GGGGGG8888888@@@@P.....
           Y88888888888@@@@@P......
           `Y8888888@@@@@@@P'......
              `@@@@@@@@@P'.......
                  """"........

* home: http://proutils.github.com/roll


== DESCRIPTION

Roll is a library manager for Ruby. With Rolls developers can run there
programs in real time --no install phase is required for one program
to depend on another. This makes it very easy to work on a set of
interdependent projects.


== HOW TO USE

=== Setting Up

To use roll regularly you first need to add it your RUBYOPT environment
variable.

  $ export RUBYOPT="-roll"

I suspect you will be using RubyGems too, in which case do:

  $ export RUBYOPT="-rubygems -roll"

To support executables you will also need to add a line to your startup
.bashrc (or equivalent) file.

  export PATH="$PATH:$(roll path)"

This will add the +bin+ locations of the programs encompassed by your
current roll environment.

(NOTE: The way bin paths are handled will probably change in the future
b/c it has some shortcomings.)

=== Preparing your Projects

For your projects to be detected by Rolls they must conform to a
minimal POM[http://proutils.github.com/pom] setup. In particular
the project must contain a +meta/+ directory with a +name+ and +version+
entry. That is the bare minimum for a project to to be loadable via
Rolls. Optionally you may provide a +loadpath+ entry if the load path 
is not the +lib/+ default, as well as a +released+ date entry.

(NOTE: +meta/+ can be named +.meta/+ if you would prefer to hide the
directory, though we recommend keeping it visible.)

Here are examples of Ruby Facets +meta/+ entries.

  $ cat facets/meta/name
  facets

  $ cat facets/meta/version
  2.8.0

  $ cat facets/meta/loadpath
  lib/core
  lib/more

  $ cat facets/meta/ruby
  1.8+

The +ruby+ entry informs Rolls of the particular implementations and versions
of Ruby the project should operate under successfully.
(NOTE: Rolls doesn't actually do anything with the ruby entry yet.)

Lastly, an +active+ entry can be set to +false+ to tell Rolls to skip the
project when searching for library files. See POM[http://proutils.github.com/pom]
for more information.


=== Library Management

Next you need to setup an roll *environment*. The default environment
is call +production+. You can add a library search location to it
using +roll in+. Eg.

  $ roll in /opt/ruby/

As a developer you will often want to use a +development+ environment.
To change or add and environment, modify the RUBYENV environment variable.

  $ export RUBYENV="development"

Then you can add the paths you want. For instance my development
environment is basically constructed like this:

  $ roll in ~/programs/proutils
  $ roll in ~/programs/rubyworks
  $ roll in ~/programs/thedeadly
  $ roll in ~/programs/transcode

By default these paths will be searched for POM conforming projects
up to a depth of three sub-directories. That's suitable for
most needs. You can specify the the depth explicitly with the 
<tt>--depth</tt> or <tt>-d</tt> option. For example, lets say you
just want to add a single ruby project to the current environment.
You can do so by navigating to the root directory of a project and
executing:

  $ roll in --depth 1

That's it. Your project is *READY-TO-ROLL*!


== LEARNING MORE

The above provides a brief overview of using roll. But there is more to
it. To get a deeper understanding of the system and how to use +roll+ to
it fullest extent, please visit http://proutils.github.org/roll/.


== HOW TO INSTALL

=== Manual Installation

You will need Ruby Setup, the standalone setup.rb script, in order
to install Roll. See: http://setup.rubyforge.org.

Once you have setup.rb, download the Roll tarball and install
it manually as follows:

  $ tar -xvzf roll-1.0.0
  $ cd roll-1.0.0
  $ sudo setup.rb all

On Windows, this last line needs to be 'ruby setup.rb all'.

=== RubyGems Installation

We strongly recommend installing Rolls manually b/c
Rolls is a peer to RubyGems. However, you can use Gems to
install it; and this is a convenient way to try it out.

  gem install roll

If you like Rolls, then later you can uninstall the gem and
install manually.


== BY THE WAY

Roll was RubyForge project #1004. She's been around a while! ;)


== LICENSE & COPYRIGHT

Roll, Copyright (c) 2006,2007 Thomas Sawyer

Rolls is distributed under the same terms as Ruby.

See the LICENSE file details.