ROLLING WITH RUBY

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

home: proutils.github.com/roll
worl: 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 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 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 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.

$ tar -xvzf roll-1.0.0

If you already have Ruby Setup installed on your system you can use it to install Rolls (See: 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

Rolls is distributed under the same terms as Ruby.

See the LICENSE file details.