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

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 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 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 --depth or -d 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 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: 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

Rolls is distributed under the same terms as Ruby.

See the LICENSE file details.