j
= setup.rb を使ったパッケージを作る
e
= Creating Packages with setup.rb
.

j
== シングルパッケージアーカイブを作る

「シングルパッケージアーカイブ」とは、以下のファイルが
一組だけ入ったプログラムパッケージのことです。

  * コマンド
  * Ruby ライブラリ
  * Ruby 拡張ライブラリ
  * その他のデータ

つまり普通のプログラムパッケージのことです。

シングルパッケージアーカイブを作るには、アーカイブを
以下のルールに従ってレイアウトしてください。
--
アーカイブのトップ/
  setup.rb
  bin/
      コマンド類
  lib/
      Ruby ライブラリ
  ext/
      拡張モジュール
  data/
      その他のデータ
--
bin lib ext data の下には各々インストールされるイメージそのままに
ファイルを配置します。例えば lib/tmail/header.rb というファイルを
置くと RUBYLIB/tmail/header.rb としてインストールされます。
bin/ lib/ などは中身が空のときには省略できます。

ext だけは配置ルールが少し特殊です。複数のファイルからひとつの共有
ライブラリ anyname.so ができるので、.so ができるべき場所にディレク
トリを作り、その中に必要なファイルを入れます。例えば
RUBYLIB/ARCH/tmail/parser.so が必要ならば、ディレクトリ
ext/tmail/parser/ を作ってその中に parser.c や extconf.rb depend
MANIFEST などを置きます。

[注意] setup.rb は MANIFEST があるディレクトリだけをコンパイル対象に
します。拡張モジュールのディレクトリには必ず MANIFEST を置いてください。
e
== Creating Single Package Archive

"Single Package Archive" means the archive which includes
only one PACKAGE.  "package" means one set of ruby scripts,
ruby extentions, commands, and data files.

setup.rb requires that the archive is structured like this:
--
PackageTop/
    setup.rb
    lib/
        (ruby scripts)
    ext/
        (ruby extentions)
    bin/
        (commands)
    data/
        (data files)
--
Each file/directories acts as below:

: setup.rb
    The installer. This file is included in this archive.
    Just copy it to your package.

: 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, 'data/' for any
    other data files.

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

    [WARNING] All extention source directories MUST include
    the file "MANIFEST".  setup.rb will complies directries
    only if the directries contains MANIFEST.
.

j
== マルチパッケージアーカイブを作る

setup.rb は複数のパッケージを一つのアーカイブにまとめて、それを
同時に扱うことができます。例えば依存関係のあるパッケージを全部
まとめて配布したりするのに使えます。

マルチパッケージアーカイブを作るには、まずトップに setup.rb と
ディレクトリ packages/ を作り、その下にパッケージ名のディレクトリ
を作ります。そしてその中にシングルパッケージアーカイブと同じ
ディレクトリツリーを配置します。つまり全体像は以下のようになります。
--
アーカイブのトップ/
    setup.rb
    packages/
        tmail/      # tmail パッケージ
            bin/
            lib/
            ext/
            data/
        raccrt/     # raccrt パッケージ
            bin/
            lib/
            ext/
            data/
        strscan/    # strscan パッケージ
            bin/
            lib/
            ext/
            data/
        amstd/      # amstd パッケージ
            bin/
            lib/
            ext/
            data/
--
packages/ の下にあるディレクトリ名がパッケージ名です。
このパッケージ名は setup.rb のヘルプメッセージに表示され、
インストールするパッケージを --with や --without でユーザが
選択するときに使われます。

またデフォルトだとパッケージはソート順にインストールされます。
順番を変更したいときは metaconfig API の declare_packages を
使ってください。

e
== Creating Multi-Package Archive

setup.rb can handle an archive which includes multiple PACKAGEs.

setup.rb requires the archive is structured as below:
--
PackageTop/
    setup.rb
    packages/         <--- fixed name
        tmail/        <--- tmail package
	    bin/
	    lib/
	    ext/
	    data/
        raccrt/       <--- raccrt package
	    bin/
	    lib/
	    ext/
	    data/
        strscan/      <--- strscan package
	    bin/
	    lib/
	    ext/
	    data/
        amstd/        <--- amstdd package
	    bin/
	    lib/
	    ext/
	    data/
--
.

j
== setup.rb の働き

ファイルを上記のとおり配置しておけばあとは setup.rb が自動的に
それなりの動作をしてくれます。具体的には、setup のときに以下の
ことを実行します。

  * bin/ 以下にあるファイルが #! で始まっていてかつ
    文字列 ruby を含む場合は #! 行を --ruby-path に置き換える
  * ext/ 以下の拡張モジュールをコンパイルする

install では以下のことを実行します。

  * bin/ 以下のファイルを --bin-dir にインストール
  * lib/ 以下の *.rb を --rb-dir にインストール
  * ext/ 以下の *.so を --so-dir にインストール
  * data/ 以下のファイルを --data-dir にインストール
.

j
== フックファイル

デフォルトの動作でもたいていの場合には通用します。しかし場合によっては
インストール時になにか特別な作業をしたいこともあるでしょう。その
場合は特別なファイルを置くことで動作を追加することができます。

たとえば setup のタイミングに lib/tmail/ でなにかをしたいとしたら、
lib/tmail/pre-setup.rb を作ってその中にやりたいことを書きます。
--
# pre-setup.rb

# racc の文法ファイルをその場でコンパイル (普通、やらない)
system "racc #{srcdir_root + '/src/mp.y'} -o mailp.rb"

# require 'tmail' で tmail/ の中身を全部 require できるようにする
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'"
}
--
一般には、ディレクトリに入った直後に pre-TASK.rb を、
ディレクトリを出る直前に post-TASK.rb を実行します。
TASK の部分に使えるもの（フック可能なタスク）は
config setup install clean distclean の五つです。

またフックスクリプトの実行中に例外が起きた場合はインストーラ
全体が即座に失敗します。逆に言うと、処理失敗の時は例外を投げれば
よいということです。exit はしないでください。

またフックファイルの例で srcdir_root や curr_srcdir という
メソッドを使っていることに注意してください。setup.rb には、
作ったファイルだけを別のディレクトリに置く仕組みがある
（srcdir と objdir が区別されている）ので、カレントディレクトリから
読めばよいとは限りません。フックファイル中では以下のルールに従って
ください。
  * 読みこみは常に現在の srcdir (curr_srcdir) から行う。
  * 書きこみは常にカレントディレクトリに対して行う。

srcdir/objdir の仕組み
--
archive_top/                  srcdir は変更しないで
    ext/tmail/scanmail/
        MANIFEST
        depend
        extconf.rb
        scanmail.c

OBJ/                          対応する objdir に作ったものを置く
    ext/tmail/scanmail/
        Makefile
        scanmail.o
        scanmail.so
--
この場合 archive_top/ を「srcdir のルート」、
OBJ/ を「objdir のルート」と言います。
また archive_top/ext/tmail/scanmail/ を「カレント srcdir」、
OBJ/ext/tmail/scanmail/ を「カレント objdir」と呼びます。

こうしておくと、srcdir に対しては読み出ししか行われないので、
clean などしなくても常に srcdir を最小限のファイルのきれいな
状態に保てます。またマニアックなところでは複数のクロスコンパイルを
同時に行ったりもできるようになります。そこまでいかなくとも、
コンパイルオプションだけを変えていくつものバージョンを作ったりする
ことはあるでしょう。この仕組みはそのような場合に便利なのです。

srcdir/objdir 対応は絶対必要というわけではありませんが、対応して
おいて損はありません。

また curr_srcdir や srcdir_root など
フックファイル中で使える API については別ページの
<a href="hookapi.html">フック API リファレンス</a>
を参照してください。
e
== 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

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

If you write hooks, you should 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 also some
APIs to help your work. see
,<a href="hookapi.html">Hook Script APIs Reference Manual</a>
.

j
== メタコンフィグ

setup.rb では、config のタスクオプションを増やすことができます。
このために使うのが metaconfig ファイルです。

例えば、libc のパスを指定するための config オプション --libc と、
win32 サポートのオンオフを指定するためのオプション --win32 を
追加してみましょう。setup.rb を置くのと同じディレクトリに metaconfig
というファイルを作り、この中に以下のような Ruby スクリプトを書きます。
--
add_path_config 'libc', '/lib/libc.so', 'path to the C standard library'
add_bool_config 'win32', false, 'compile with Win32 support'
--
これで、パスを指定するオプション --libc と、真偽値を取る
オプション--win32 が追加されました。以下のように config
のときに使うことができます。
--
ruby setup.rb config --libc=/lib/libc-devel.so --win32
--
また setup.rb のヘルプメッセージにも自動的に表示されます。

metaconfig で使える API については
<a href="metaconfapi.html">metaconfig API リファレンスマニュアル</a>
を参照してください。
e
== metaconfig

You can add new config options by writing file "metaconfig".
metaconfig must be placed in the package-root directory.

Here is a simple example of metaconfig.
--
add_path_config 'libc', '/lib/libc.so', 'path to the C standard library'
add_bool_config 'win32', false, 'compile with Win32 support'
--
This script defined new config option --libc and --win32.

In 'metaconfig', you can use some APIs described in
,<a href="metaconfapi.html">metaconfig API Reference Manual</a>
.

j
== 以前のバージョンとの互換性

インストーラというものの特殊性を考え、
互換性はまったく保っていません。2.0 以前とは別物と思ってください。
前バージョンの動作が必要ならばそのバージョンを使いましょう。
以前のバージョンとは以下の点で非互換です。
  * ディレクトリ構造が完全に違う
  * PATHCONV がない
  * share/ → data/
  * フックの形式が違う
  * dryrun コマンドがない → --prefix 使ってインストールしてください。
e
== Backward Compatibility

I do not assure any backward compatibility for the setup.rb.
If you'd like old behavior, just use old version.
.

j
== ライセンスについて

setup.rb 自体は GNU Lesser General Public License (LGPL) version 2
に従って配布します。詳細はファイル LGPL を見てください。また、setup.rb
を使ってインストールするプログラムが LGPL である必要はありません。
e
== 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
while the installer is LGPLed one.
.

j
== インストールマニュアル

このアーカイブに含まれている Usage_*.txt は自由にコピー・編集
して自分のパッケージに使ってください。Copyright 表示が入って
いますが、これは単に自動化が楽だから入っているだけなので消しても
構いません。
e
== Installation Manual

You can freely copy/edit and/or distribute Usage_*.txt files
which are included in this archive.  I do not claim any rights
on them.  Removing my copyright is also OK.
.
