Ruby Setup¶ ↑

Website / Guide / Issues / Source ( <img src=“https://secure.travis-ci.org/rubyworks/setup.png” /> )

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.

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 compile phase.

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

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 projects 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 all subcommand.

$ setup.rb all

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

$ setup.rb compile
$ setup.rb install

Where compile compiles any extensions and install copies project files to the appropriate places on your system.

For setup.rb to install a project’s documentation and library files properly it is best to supply it was basic information about the project. In particular, the name, version and loadpath (if not the default ‘lib`). This can be done either by creating a `.index` file for the project (see Indexer), or by adding .setup/name, .setup/version and .setup/loadpath to the project.

Setup.rb also supports two optional phases, config and test.

$ setup config

Configuration must be run before any other phase in order to be of used. Running ‘config` creates a `SetupConfig` file which you can then edit to make any adjustments neccessary to the installation. When finished editing this file, use setup.rb as before and your custom configuration will be used instead of the standard defaults.

$ setup.rb test

This will run tests if a test script is provided. It must be run after compile, 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 runner script, either. .setup/test.rb or .setup/test.sh. 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 --test or -t option.

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 ‘SetupReceipt’ file that is generated by the install process. If that file is deleted than you will not be able to uninstall. (You can usually get around this be reinstalling first though).

During the make phase, by-product files are typically 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 and associated wiki.

Setup.rb is copyrighted open source software.

Copyright (c) 2008 Rubyworks (BSD-2-Clause)

It can be modified and redistributed in accordance with the BSD-2-Clause license.

Setup.rb is a rewrite of the original setup.rb script by Minero Aoki.

Copyright (c) 2002 Minero Aoki (GNU LGPL 2.1+)

See LICENSE.txt and NOTICE.rdoc for details.