= Ruby Setup

* http://protuils.github.com/setup
* http://github.com/protuils/setup


== INTRODUCTION

Every well practiced Rubyist is aware of Minero Aoki's ever +setup.rb+
script. It's how most of us used to install our Ruby programs before RubyGems
came along. And it's still mighty useful in certain scenarios, not the
least of which is the job of the distro package maintainer.

Ruby Setup converts setup.rb into a stand-alone application. No longer
requiring the distribution of the setup.rb script with every Ruby package.
Just instruct one's users to install Ruby Setup (gem install setup) and go
from there. As long as a project is setup.rb compliant, as most are,
then there is little to nothing it's developer must do.


=== IMPORTANT

There a couple very important difference between the old 3.4.1 verison
of the setup.rb and Ruby Setup.

* The directory convention 'conf' has been change to 'etc'.
* Multi-package project layouts are no longer supported.
* Metaconfig and Hooks are handled via singleton extensions.
* No longer supports versions of Ruby older than v1.6.3.
* The +setup+ phase has been renamed to the +make+ phase.

=== STATUS

Version 5 is a major re-engineering of setup.rb. Although it is fairly well
tested, as such, it should be considered betaware until it accumulates
enough use in the field. I will update this message when I feel a new status
has been achieved (likely accompanied by an updated release).


== INSTALLATION

The easy way to install is via RubyGems.

  $ sudo gem install setup

To install Setup manually you need to "boot-strap" it. Download the tarball,
and from the decompressed package directory run:

  $ ruby script/setup


== HOW TO USE

To use setup.rb, a project must conform to the setup.rb standard layout.
Please see the documentation on the website if you need to know more about
what this entails. Most project already follow the standard since it was
setup.rb that originally popularized most of the current layout conventions.
(Note that the on-line documentation is slightly out of sync with the latest
release.)

Usage is as simple as:

  $ setup.rb

This is the same as using the <tt>all</tt> subcommand.

  $ setup.rb all

And is equivalent to running the three main phases in sequence.

  $ setup.rb config
  $ setup.rb make
  $ setup.rb install

Where +config+ determines the configuration of your Ruby distribution,
+make+ compiles any extensions and +install+ copies project files to
the appropriate places on your system.

Setup.rb also supports two optional phases, +test+ and +document+.

  $ setup.rb test

This will run tests if a test script is provided. If should be run after
+make+, but before +install+. Because there are now a deverse selection
of testing tools available for Ruby, testing only happens if the developer
has provided a test run command script (eg. <tt>.setup/testrc.rb</tt>).
Keep in mind that testing may require support libraries such as RSpec,
Lemon, Bacon, QED or Cucumber. When using the +all+ command, you can
activate testing via the <tt>--test</tt> or <tt>-t</tt> option if desired.

The +document+ phase is used to generate ri documentation for a package.

  $ setup.rb document

This generates *ri* documents for the program and automatically
places the documentation in the appropriate system location. Documenting
is not part of the default sequence due to the way ri documentation is
handled by the +rdoc+ tool. It is not possible to uninstall it. So this
phase must be run seperate from the others. Please only use the +document+
command when you are ceratin that you want the documentation in your ri
system. (Hopefully this can be fixed in the near future.)

If you later decide you want to remove a program from your system, use
+uninstall+.

  $ setup.rb uninstall

This will remove all files previously installed via the setup.rb command.
Uninstalling is made possible by the 'InstalledFiles' file that is
generated by the install process. If that file is deleted than you
will not be able to uninstall. (You can get around this be reinstalling
first though).

During the make phase, by-product files are generally created.
You can clean up any of these by-products with:

  $ setup.rb clean

And restore them to their absolute pristine state with:

  $ setup.rb distclean

For further details on using +setup.rb+, or developing a project that can
take advantage of setup.rb's special features, please see the website.


== COPYRIGHTS

Copyright (c) 2008,2009 Thomas Sawyer

Copyright (c) 2002,2005 Minero Aoki

GNU LGPL, Lesser General Public License version 2.1.

For details of LGPL, see the COPYING file.



                                               7trans
                                  transfire@gmail.com
                           http://proutils.github.com


                                          Minero Aoki
                                  aamine@loveruby.net
                                http://i.loveruby.net