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_rubyerubyǤưϤʤΤ librubyX.Y  depends
#!/usr/bin/rubyפɬפʤΤˤĤƤrubyX.Ydepends롣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-policyrubyˤ뤳Ȥ򵭽)
       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.8default 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

 rubylibruby  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?