roll

= 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 PACKAGE file and it must have at least one lib/*.rb 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 --depth or -d 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.