= 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
* worl: http://github.com/protuils/roll


== DESCRIPTION

Roll is a library manager for Ruby. With Rolls developers can run their
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 --without vendering. It also makes easy to
create isolated library environments. Yet Rolls does so efficiently
--there need only be a single copy of any given version of a library
on disc. And libraries can be stored anywhere. There is no special place
they must all reside. You simple tell Rolls where they are.

== STATUS

Rolls works fairly well. I have used it for development for years, so
on the whole it stays in working order. However it is still under
heavy development, so configuration is still subject to a fair bit
of change. The loading heuristics are quite advanced, which accounts
for the speed, but as a trade-off the first library that is not found
"early" can initilially slow the system as all of an environments
metadata if loaded.


== 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="-roll -rubygems"

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 a project to be detected by Rolls it must conform to a
minimal POM[http://proutils.github.com/pom] setup. Specifically
the project must have a <code>PACKAGE</code> file and it must
have at least one <code>lib/*.rb</code> file. In the future this
should become a little more flexible, but that is the bare minimum
for a project to to be loadable via Rolls as of v1.2. The only
exception is for Gem stores. If you point Rolls torwards a gems/
location it will attempt to parse the name and version from a
library's directory name (e.g. facets-2.8.4/). It does not read
the gemspec (that would be slow). So alternate loadpaths are not
supported for Gem stores at this time.

Also, note that #autoload will not work with Rolls. Ruby has a bug
that prevents #autoload from using any custom defined #require method.
(Why this has never been fixed is both annoying and frustrating
to say the least.)

See POM[http://proutils.github.com/pom] for more information about
the POM standard.

=== Library Management

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

  $ roll in /opt/ruby/

As a developer you will may want to setup a +development+ environment.
To change or add an environment use the +use+ command.

  $ roll use development

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

  $ roll in ~/programs/proutils
  $ roll in ~/programs/rubyworks
  $ roll in ~/programs/trans

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. You can roll in the 
current working directory by leaving off the path argument. 
If the current directory has a +VERSION+ file, a depth of +1+
will automatically be used.

  $ roll in

So that's it. You are *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 (Recommended)

First you need a copy of the roll tarball (or zip) archive.
You will find them here[http://github.com/proutils/roll/download].

  $ tar -xvzf roll-1.0.0

If you already have Ruby Setup installed on your system you can
use it to install Rolls (See: http://setup.rubyforge.org). 

  $ cd roll-1.0.0
  $ sudo setup.rb

Otherwise, Rolls includes a copy of Ruby Setup that you can
use.

  $ cd roll-1.0.0
  $ sudo script/setup.

On Windows, this last line needs to be 'ruby script/setup'.

=== 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
do a proper manual install.


== BY THE WAY

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


== LICENSE & COPYRIGHT

Roll/Rolls Copyright (c) 2006,2007 Thomas Sawyer

Rolls is distributed under the same terms as Ruby.

See the LICENSE file details.