setup.rb User Manual

What is setup.rb ?

setup.rb/install.rb is the installer for ruby scripts/extentions. You can automate installation and configuration of your program package by using this script. install.rb is the one for single library, setup.rb is the one for multi packages.

Usage from the real users' view

Overview

Just type 3 lines below. ("#" line may require root privilege)

$ ruby install.rb config
$ ruby install.rb setup
# ruby install.rb install

when setup.rb

$ ruby setup.rb config
$ ruby setup.rb setup
# ruby setup.rb install

Details

Usage of install.rb/setup.rb is:

ruby install.rb []
ruby install.rb  []

Global Options

-q,--quiet
suppress message outputs
--verbose
output messages verbosely (default)
-h,--help
prints help and quit
-v,--version
prints version and quit
--copyright
prints copyright and quit

Tasks

config
saves configurations
show
prints current configurations
setup
compiles extentions
install
installs files
clean
cleans created files

task options for config

--prefix=path
path prefix
--std-ruby=path
the directory for standard ruby libraries
--site-ruby=path
the directory for non-standard ruby libraries
--bin-dir=path
the directory for commands
--rb-dir=path
the directory for ruby scripts
--so-dir=path
the directory for ruby extentions
--data-dir=path
the directory for shared data
--ruby-path=path
path to set to #! line
--ruby-prog=path
the ruby program using for installation
--make-prog=name
the make program to compile ruby extentions
--rbconfig=path
your rbconfig.rb to load

In addition, setup.rb accepts these options:

--with=name,name...
package names that you want to install
--without=name,name...
package names that you do not want to install

[NOTE] You can pass options for extconf.rb like this:

ruby install.rb config -- --with-tklib=/usr/lib/libtk-jp.so.8.0

Options for install

--no-harm
only display what to do if given

Usage from the developpers' view

install.rb (single package installer)

install.rb can handle one set of ruby scripts, ruby extentions, commands, and data file. Call them a "package". install.rb requires that the archive is structured like this:

package-top/
    install.rb
    lib/
        ruby scripts
    ext/
        ruby extentions
    bin/
        commands
    data/
        data files

Each file/directories acts as below:

install.rb
The installer core. This file is included in this archive. Just copy it to the archive.
lib/, bin/, data/

These directories includes data files which are to be installed. This directory tree is mirrored to the target directory, from lib/ to RUBYLIB/, from bin/ to BINDIR/, from ext/ to RUBYLIB/ARCH/ ....

Use lib/ for ruby scripts, bin/ for commands, share/ for any other data files.

ext/

ext/ includes ruby extentions. If you want to install RUBYLIB/ARCH/someext.so, create a directory ext/someext/ and put source files into it.

[WARNING] Every extention source directory MUST includes "MANIFEST" file. install.rb will complies the only directory which includes MANIFEST file.

setup.rb (multiple package installer)

setup.rb can handle an archive which includes multiple packages. "package" means a set of install.rb's archive.

setup.rb requires this type of structure:

package-top/
    setup.rb
    packages/
        tmail/        (tmail package)
	    lib/
	    ext/
	    bin/
	    data/
        raccrt/       (raccrt package)
            :
        strscan/      (strscan package)
            :
        amstd/        (amstd package)
            :

Hooking tasks

You can hook any tasks, such as "config" "setup". For example, you want to make some files in lib/tmail/ when setup. Then create file "lib/tmail/pre-setup.rb" and put this:

# pre-setup.rb

# process grammer file
system "racc #{srcdir_root + '/src/mp.y'} -o mailp.rb"

# require all ruby scripts in this directory from _loadlib.rb.
list = Dir.glob(curr_srcdir + '/*.rb').collect {|n| File.basename(n) }
File.open( '_loadlib.rb', 'w' ) {|f|
  f.puts list.collect {|n| "require 'tmail/" + n + "'" }
}
File.open( '../tmail.rb', 'w' ) {|f|
  f.puts "require 'tmail/_loadlib'"
}

This file is evaluated on task "setup" in the directory, before processing any other thing. Acceptable hook file name is:

{pre,post}-{config,setup,install,clean}.rb

[NOTE] You can also put hook files in the top directory of archive and/or the type-root directory (bin/, lib/,...).

srcdir/objdir support

install.rb/setup.rb supports srcdir/objdir. In other words, you can compile everything out of the source directory.

If you write hooks, you should also supports srcdir/objdir system. When you read source code, read it from srcdir. When you write anything, write it to the current directory. There's some APIs to help your work:

srcfile(fname)
expands relational path FNAME which is in the current srcdir, into the absolute path.
srcexist?(fname)
true if there's a file entry FNAME in the current srcdir.
srcdirectory?(fname)
true if there's a directory FNAME in the current srcdir.
srcfile?(fname)
true if there's a file FNAME in the current srcdir.
srcentries(relpath = '.')
returns the list of file entiries in the directory "current srcdir + '/' + relpath"
srcfiles(relpath = '.')
returns the list of file names in the directory "current srcdir + '/' + relpath"
srcdirectories(relpath = '.')
returns the list of directory names in the directory "current srcdir + '/' + relpath"
curr_srcdir
the current srcdir
curr_objdir
the current objdir
srcdir_root
the root directory of srcdir. When the hook is called from setup.rb this method returns the top directory of the PACKAGE (ARCHIVE_TOP/packages/*/).
objdir_root
the root directory of objdir. When the hook is called from setup.rb this method returns the top directory of the PACKAGE (ARCHIVE_TOP/packages/*/).
config(key)
get configurations. (e.g. config('prefix') for --prefix)

License

GNU Lesser General Public License (LGPL) version 2. For details, see file "LGPL". NOTE: You CAN distribute your program under the any licenses you like. LGPL does not force you to make your programs LGPL if the installer is GPLed one.


Copyright (c) 2000,2001 Minero Aoki <aamine@loveruby.net>