Debian ruby policy -draft- 
$Id: ruby-policy-memo.txt,v 1.5 2003-08-22 19:24:05 ukai Exp $

Unresolved
- who maintain -ruby package?
    ruby1.6's -ruby1.6  --> ruby-defaults
    ruby1.8's -ruby1.8  --> ruby-defaults
          new -ruby1.8  --> ruby-defaults?, -ruby1.6 maintainer?

    other               --> maintainer

- /usr/share/ruby
 > Currently, ruby upstream doesn't support such version independent module 
 > path /usr/share/ruby in $LOAD_PATH. Should we modify ruby 1.8 or later 
 > to support this?

 I think so, but I'm open to suggestions about it. It does IMO make
 packaging modules without C code much simpler. The downside is when a
 major incompatibility happens (i.e. code that works correctly on more
 than one version is impossible), but I believe this is a rare enough
 case to ignore (AFAIK it's never happened).

FIXME (in ruby-policy)

-----
* Ruby Packaging
** Versioning

Ruby version X.Y.Zは rubyX.Y.dsc から 
rubyX.Y, librubyX.Y, rubyX.Y-dev (version X.Y.Z-N)
としてパッケージにされる。

rubyX.Y は /usr/bin/rubyX.Y を提供する。
ruby が default version of ruby にsymlinkをはった /usr/bin/ruby を提供する。

Rational: alternatives として提供しない。
versionを気にせず#!/usr/bin/ruby と書きたい人は /usr/local/bin/ruby という
symlinkを作ってもらって #!/usr/local/bin/ruby と書くのを薦める。
packageにするものはversion依存を考慮して#! lineを書く。
- alternatives にしない方がよいと思われる理由のひとつ。
foo depends: rubyX.Y で rubyX.Y が default version of ruby の時、
fooの提供するプログラムが #!/usr/bin/ruby となっていて、system admin 
が ruby alternativesを別のにした時に問題が生じた場合に、それは
bug とみなされるのか?

librubyX.Y は /usr/lib/librubyX.Y.so.X.Y.Z (soname librubyX.Y.so.X.Y) および 
librubyX.Y.so.X.Y を提供する。また core となる moduleを /usr/lib/ruby/X.Y
にインストールする。

Note: libruby (1.6.x) は /usr/lib/libruby.so.* を提供している。

rubyX.Y-dev は /usr/lib/librubyX.Y.so を提供する。
また /usr/lib/ruby/X.Y/mkmf.rb, /usr/lib/ruby/X.Y/GNU-SYSTEM/*.{h,a} も
提供する。

Note: ruby-dev (1.6.x) は /usr/lib/libruby.so を提供している。

FIXME/TODO: header file は /usr/include/rubyX.Y にインストールすべきか?
mkmf.rb に要修正?

** module path

module path は $LOAD_PATH ($:) に以下の順番になるように設定されている。
 /usr/local/lib/site_ruby/X.Y		 (Config:CONFIG['sitelibdir'])
 /usr/local/lib/site_ruby/X.Y/GNU-SYSTEM (Config:CONFIG['sitearchdir'])
 /usr/local/lib/site_ruby		 (Config:CONFIG['sitedir'])
 /usr/lib/ruby/X.Y		(Config:CONFIG['rubylibdir'])
 /usr/lib/ruby/X.Y/GNU-SYSTEM	(Config:CONFIG['archdir'])
 .

FIXME/TODO: rubylibdir は /usr/share/ruby/X.Y にすべきか?

XXX: . を含むのはsecurity holeになりうるのか?

** Documentation

FIXME: とりあえず後回し?
  memo: http://www.topstudio.co.jp/~kmuto/d/?200307c&to=200307315#200307315
  - riのデータは更新がどうなっているのかわかりにくいのでrefeがいい?

* Locally installed module
** site directories, installation
以下のディレクトリをつかう

 /usr/local/lib/site_ruby/X.Y		 (Config:CONFIG['sitelibdir'])
			- arch indepdendent files
 /usr/local/lib/site_ruby/X.Y/GNU-SYSTEM (Config:CONFIG['sitearchdir'])
			- arch depdendent files
 /usr/local/lib/site_ruby		 (Config:CONFIG['sitedir'])
			- version independent files

* packaged modules
** directories

以下のディレクトリを使う

 /usr/lib/ruby/X.Y		(Config:CONFIG['rubylibdir'])
				- for arch independent files
 /usr/lib/ruby/X.Y/GNU-SYSTEM	(Config:CONFIG['archdir'])
				- for arch dependent files

必要に応じてupstreamがインストールするようにsubdirをきる。

** module package name

Ruby X.Y.Z 用の FOO/BAR を提供するモジュールは libFOO-BAR-rubyX.Y という
名前でパッケージングする。

次のいずれか
- libFOO-BAR-rubyX.Y が基本
- すでに-rubyというパッケージで存在しているものについては-rubyを用意して，sargeの後で削除するという方向にする
- woodyにないパッケージなら，-rubyはなし

(traditional) Ruby 1.6までは libFOO-BAR-ruby としていた。
ruby 1.8移行後は policy violation?
libFOO-BAR-ruby は depends: ruby (default version of ruby)ならば許可。
libFOO-BAR-ruby は depends: libFOO-BAR-rubyX.Y (for default version of ruby)
というメタパッケージでも可。

複数のバージョンで動きうるarch-indep moduleの場合
- for default version of ruby
-- libFOO-BAR-rubyX.Y (上記のルールに従う)
- for other versions
-- libFOO-BAR-rubyX'.Y' depends on libFOO-BAR-rubyX.Y でsymlink

** installation
** dependencies

libFOO-BAR-rubyX.Y は Depends: librubyX.Y

mod_rubyやerubyでも動くはずなので librubyX.Y に depends。
もちろん「#!/usr/bin/ruby」が必要なものについてはrubyX.Yにdependsする。4

Build-Depends(-Indep): に rubyX.Y-dev が必要。

*** architecture-independent module

architecture-independent module は Architecture: all で
/usr/lib/ruby/X.Y (Config:CONFIG['rubylibdir']) 以下に *.rb を
インストールする。

複数のバージョンで動きうるmoduleの場合は、必要に応じて
旧バージョンの rubylibdir で symlinkを張ったパッケージを作成してもよい。
そのパッケージは libFOO-BAR-rubyX'.Y' depends: libFOO-BAR-rubyX.Y で
作る。

*** binary module

binary module は Architecture: any で
/usr/lib/ruby/X.Y/GNU-SYSTEM (Config:CONFIG['archdir'])以下に
*.so 等をインストールする。

default version of ruby むけのパッケージングを最優先で。
それ以外のバージョンむけに関しては必要に応じて対応。
重要なパッケージに関しては、できるだけ多くのバージョンに対応することが
望ましい。
(TODO: 重要なパッケージとはどんなものか?)

*** automating ruby dependencies

dh_ruby が欲しいところ

TODO: incompatibility が生じて versioned depends したい時のために
rbconfig.rb あたりにそういう情報を含んでおいて rbconfig.rb から
${ruby:Depends} とかが生成できるようにしたほうがいいか?

* ruby program
** naming
default version of ruby に依存している ruby program のパッケージは
わかりやすい名前をつけてよい。

default version of ruby 以外の specific version of ruby に依存している 
ruby program のパッケージは
PROG-rubyX'.X' (rubyX'.Y'-PROG) のようなネーミングにする。

ruby program がメインでないパッケージ(ruby scriptを含んでいるだけの場合)
ネーミングに制約はない。

** script magic

ruby interpreter は /usr/bin/ruby としてalternativesにより実行できる
ので 一般的なruby scriptは

 #!/usr/bin/ruby

とする。(必要に応じて flagを設定する)
ruby interpreterのパスに依存するのが好ましくないと思われる場合は

 #!/usr/bin/env ruby

としてもよい。

明かに バージョンに依存するようなプログラムに関しては

 #!/usr/bin/rubyX.Y

のようにバージョン付パス名を使うこと。


** dependencies

 #!/usr/bin/rubyX.Y

の場合は Depends: rubyX.Y

 #!/usr/bin/ruby 

の場合は Depends: rubyX.Y か Depends: rubyX.Y | rubyX'.Y' とか。
ここで、rubyX.Y は default version of rubyで
それ以外の version に or depends してよい。

* embedded ruby?

[[Bug#:192523]]

* ruby 1.6 ->1.8 transition?
現在は 
  ruby: ruby 1.6.8 
  ruby1.8: ruby 1.8.0

となっていて、ruby 1.6.x 系列が、このpolicyに従っていない。

次のステップで移行していく。

ITP: ruby1.6
- ruby1.6 パッケージを ruby 1.6.8 で作る。
- 現行の ruby パッケージからの rename。
- まずは ruby1.6 を default version of ruby で作る。

FIXME: 今 ruby.dsc から作られている libFOO-ruby は libFOO-ruby1.6 にすべきか?
smooth upgradeのために-ruby depends -ruby1.6か?

ruby, libruby というdefault version of ruby をインストールするためのパッケージ ruby-defaults.dsc を作る。
- ruby policy はこのパッケージにいれておく。
       ruby 1.6.8-6 depends: ruby1.6 
       		(ruby-policy.{sgml,txt})
       libruby 1.6.8-6 depends: libruby1.6 
       		(README.Debianで ruby-policyはrubyにあることを記述)
       ruby-dev は作らない (必要ない)

FIXME: ruby 1.8 配布に含まれてしまった ext moduleの扱いをどうするか?
ruby1.8 は *-ruby1.8 というパッケージを作っており既存のライブラリとは
衝突しない。 ruby 1.8.x 用の ext moduleが ruby 1.8 とは別にリリースされた場合は
どうするべきか?

まずは
- 単独でリリースされるものなのかどうか
- 単独でリリースされた場合にupstreamはどう対応するのか
あたりを確認。
「これからもがんがん単独でリリースするよ」
ということであればrubyX.Yからは外す。

# upstreamへ開発が移行しないもの，まだ独立でリリースする可能性があるものは1.8から抜く? 
# install pathを細工してbuilt-inのやつは後から参照されるようにする?
# libFOO-BAR-ruby1.8 という naming はruby 1.8以外で配布されているものが使うことにしておいて ruby 1.8.n からビルドされる同等のパッケージには違う naming (libFOO-BAR-ruby1.8base とか? いいnamingがおもいつかない)にするとか。で libFOO-BAR-ruby1.8 と libFOO-BAR-ruby1.8base はconflicts & replaces する?
# もしくは、独立でリリースされても、それを ruby1.8.dsc の方につっこんでruby1.8 からビルドしちゃうとか? メンテが大変かな?
# Version番号が rubyとは独立についているようなものは別パッケージにする?
  例: rexmlとかは ruby1.8版は Version 2.7.1 らしい。
   この場合は librexml-ruby1.8 は ruby1.8からつくらず
   librexml-ruby1.8 2.7.1(-ruby1.8)-1 => 2.7.2-1 とかいう
   ように version up してもらうとか?

ちなみに -ruby maintainerは以下の通り
- piman: libtest-unit-ruby
- angdraug: libyaml-ruby
- oliver: librexml-ruby
- akira: libwebrick-ruby, libzlib-ruby, libopenssl-ruby, libstrscan-ruby, libiconv-ruby, drb -> libdrb-ruby1.8, xmlrpc4r -> libxmlrpc-ruby1.8
- New in ruby1.8: liberb-ruby1.8, libdl-ruby1.8, libbigdecimal-ruby1.8, libracc-runtime-ruby1.8(-ruby1.7)

以下のスケジュールを目途に ruby1.8 を default version of ruby とする。

# ruby1.6, ruby-defaults がinstalled
# old stable version にdependsしているパッケージに対して新しいバージョンでつくるようにbug report
# すべてdone or 7日間待った後に ruby1.8をdefault version of ruby にするようにしたruby-defaults を upload

次のRuby安定版が出るまでに ruby1.6 をアーカイブから削除する。

TODO: ruby 1.6 -> 1.8 のトラブルシューティングドキュメントがあるとよいかも。
migration howto

upstream changes: ftp://ftp.ruby-lang.org/pub/ruby/1.8/changes.1.8.0

TODO: ruby packaging manual というか best current practiceなドキュメントが
あるといいかも?
cdbs用に /usr/share/cdbs/1/class/ruby-distutils.mk とかできるとなおよし?

----
* 参考
- [http://www.debian.org/doc/packaging-manuals/perl-policy/ Debian perl policy]
- Debian python policy /usr/share/doc/python/python-policy.txt.gz

* メモ
- http://lists.debian.or.jp/debian-devel/200307/msg00030.html のスレッド
- http://lists.debian.org/debian-devel/2003/debian-devel-200308/msg00262.html のスレッド
- http://arika.org/diary/20030806.html#p02


[ruby]
 default version of ruby: ruby X.Y (ruby-X.Y.Z)
 other version of ruby:   ruby X'.Y' (ruby-X'.Y'.Z')

 package: ruby
 depends: rubyX.Y
 version: X.Y.Z-M
 source: ruby-defaults
	 default version of ruby
	 /usr/bin/ruby

 package: libruby
 depends: librubyX.Y
 version: X.Y.Z-M
 source: ruby-defaults
	 default version of libruby
	 dummy package for smooth upgrading

 package: rubyX.Y
 depends: librubyX.Y
 version: X.Y.Z-N
 source: rubyX.Y
	 specific version of ruby
	 /usr/bin/rubyX.Y

 package: libribyX.Y
 version: X.Y.Z-N
 source: rubyX.Y
	 specific version of libruby
	 /usr/lib/ruby/X.Y

 package: rubyX.Y-dev
 depends: librubyX.Y (= X.Y.Z-N)
 recommends: rubyX.Y
 version: X.Y.Z-N
 source: rubyX.Y
	 specific version of ruby-dev

[ruby script program]

 package: FOO (FOO-ruby, ruby-FOO?)
 depends: ruby (>= X.Y), ruby (<< X.(Y+1))
   ruby script for default version of ruby
   script magic	#!/usr/bin/ruby
		#!/usr/bin/env ruby
 or
 package: FOO (FOO-ruby, ruby-FOO?)
 depends: FOO-rubyX.Y
   dummy package for smooth upgrading

 package: FOO-rubyX.Y (or rubyX.Y-foo)
 depends: rubyX.Y
   script magic	#!/usr/bin/rubyX.Y
		#!/usr/bin/env rubyX.Y
   ruby script for specific version of ruby

[ruby module/library]

 package: libFOO-ruby
 depends: libFOO-rubyX.Y, libruby (>= X.Y), libruby (<< X.(Y+1))
   dummy package for smooth upgrading

 package: libFOO-rubyX.Y
 depends: librubyX.Y
 build-depends: rubyX.Y-dev
   /usr/lib/ruby/X.Y/FOO
    ruby modules for specific version of ruby

upgrading simulation

- default: 1.6

 ruby depends ruby1.6
 libruby depends libruby1.6
 ruby1.6
 libruby1.6
 ruby1.6-dev

 FOO depends ruby (>= 1.6), ruby (<< 1.7)

 BAR depends BAR-ruby1.6
 BAR-ruby1.6 depends ruby1.6

 libFOO-ruby depends libFOO-ruby1.6
 libFOO-ruby1.6 depends libruby1.6

- transition done: 1.6 -> default 1.8

 ruby depends ruby1.8
 libruby depends libruby1.8
 (ruby1.6)
 (libruby1.6)
 (ruby1.6-dev)
 ruby1.8
 libruby1.8
 ruby1.8-dev

 FOO depends ruby (>= 1.8), ruby (<< 1.9)

 BAR depends BAR-ruby1.8
 BAR-ruby1.8 depends ruby1.8

 libFOO-ruby depends libFOO-ruby1.8
 libFOO-ruby1.8 depends libruby1.8

 ruby、libruby が先に 1.8 になった場合
   depends ruby (>= 1.6), ruby (<< 1.7) とか
   depends libruby (>= 1.6), libruby (<< 1.7) を
   インストールしている人は ruby, libruby は upgradeされない

 depends ruby (>= 1.8), ruby (<< 1.9)とかが先にアップロードされた場合
    ruby 1.6.8-n のままなのでそれらはインストールされない

両方そろったときにupgradeされる


 (libruby1.6 & libFOO-ruby1.6) | (libruby1.8 & libFOO-ruby1.8)  
   
libFOO-ruby depends libruby1.6|libFOO-ruby1.8,libruby1.8|libFOO-ruby1.6,
		libFOO-ruby1.6|libFOO-ruby1.8,libruby1.6|libruby1.8
 architecture all only?