README.rdoc in roll-1.1.0 vs README.rdoc in roll-1.2.0

- old
+ new

@@ -13,20 +13,35 @@ `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 there +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. +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 @@ -34,11 +49,11 @@ $ export RUBYOPT="-roll" I suspect you will be using RubyGems too, in which case do: - $ export RUBYOPT="-rubygems -roll" + $ 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)" @@ -49,76 +64,61 @@ (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. +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. -(NOTE: +meta/+ can be named +.meta/+ if you would prefer to hide the -directory, though we recommend keeping it visible.) +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.) -Here are examples of Ruby Facets +meta/+ entries. +See POM[http://proutils.github.com/pom] for more information about +the POM standard. - $ 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 +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 often want to use a +development+ environment. -To change or add and environment, modify the RUBYENV environment variable. +As a developer you will may want to setup a +development+ environment. +To change or add an environment use the +use+ command. - $ export RUBYENV="development" + $ roll use development Then you can add the paths you want. For instance my development -environment is basically constructed like this: +environment is essentially constructed like this: $ roll in ~/programs/proutils $ roll in ~/programs/rubyworks - $ roll in ~/programs/thedeadly - $ roll in ~/programs/transcode + $ 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. 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: +<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 --depth 1 + $ roll in -That's it. Your project is *READY-TO-ROLL*! +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 @@ -126,43 +126,50 @@ it fullest extent, please visit http://proutils.github.org/roll/. == HOW TO INSTALL -=== Manual Installation +=== Manual Installation (Recommended) -You will need Ruby Setup, the standalone setup.rb script, in order -to install Roll. See: http://setup.rubyforge.org. +First you need a copy of the roll tarball (or zip) archive. +You will find them here[http://github.com/proutils/roll/download]. -Once you have setup.rb, download the Roll tarball and install -it manually as follows: - $ 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 all + $ sudo setup.rb -On Windows, this last line needs to be 'ruby setup.rb all'. +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 -install manually. +do a proper manual install. == BY THE WAY Roll was RubyForge project #1004. She's been around a while! ;) == LICENSE & COPYRIGHT -Roll, Copyright (c) 2006,2007 Thomas Sawyer +Roll/Rolls Copyright (c) 2006,2007 Thomas Sawyer Rolls is distributed under the same terms as Ruby. See the LICENSE file details.