<yaaawn>

I needed one last act of folly before going to bed at 6:55 a.m., so
here it is.



	      rpkg - Ruby Package Management System 0.1


What
====

A multi-platform system for installation, removal, and browsing of
Ruby modules.



Why
===

Though RAA.succ promises wonderful web services, the phone bill on the
table over there intently stares at me, reminding me that browsing and
choosing packages offline can make life easier for a 33.6k user.

The Debian GNU/Linux package management system allows that and more.
I started out of curiosity to see what good there was in applying its
concepts to Ruby modules.  Two days later I woke up and realized I had
shamelessly plagiarized all the functionality I was able to.  And it
(mostly) worked.



How
===

User perspective - high level
-----------------------------

Package installation and update:

# rapt install samplepkg

Package removal:

# rapt remove samplepkg

Update database of remotely available packages:

# rapt update

Search in the available packages database:

$ rapt search keyword keyword keyword

Show package entries:

$ rapt show samplepkg foopkg



User perspective - medium level
-------------------------------

Package installation:

# rpkg --install samplepkg-0_1_1_all.rpk

Previously installed versions of the same package are kept if newer
and replaced if older than the one being installed.

Package removal:

# rpkg --remove samplepkg

Search for a file among installed packages:

$ rpkg --search '^reg[exp]'

List files belonging to an installed package:

$ rpkg --list-files samplepkg

Show package information (description, dependencies etc.):

$ rpkg --info samplepkg




Package maintainer perspective
------------------------------

Build a package:

$ rpkg --build samplepkg .

A package named <pkgname>-<version>_<arch>.rpk gets built in current
directory (gzipped tar).

The build directory must appear like this:

+ samplepkg/
|
+--+ doc/
|  |
|  +-- README
|  |
|  +-- index.html
|
+--+ lib/
|  | 
|  +-- sample.rb
|  |
|  +-- mod.rb
|
+--+ test/
|  |
|  +-- test_sample.rb
|
+--+ RUBY/
   |
   +-- control

The only mandatory content is RUBY/control.  doc, lib, and test are
optional and may contain sub-directories.  All other content is
ignored.

The content of doc, lib and test is mapped to the filesystem according
to rules specific to the platform.  For example, on GNU/Linux the
contents of lib/ are copied into /usr/local/lib/site-ruby/1.6/, the
contents of doc/ are copied into
/usr/local/lib/site-ruby/doc/<pkgname>/, the contents of test/ are
copied into /usr/local/lib/site-ruby/test/<pkgname>/.

The RUBY/control file appears like this:

Package: samplepkg
Version: 0.0.1-20020801
Section: misc
Priority: optional
Architecture: all
Depends: 
Conflicts: samplepkg-beta
Replaces: samplepkg-beta
Maintainer: Mr. Maintainer <foo / bar.co>
Source: 
Description: A sample package
 A sample package used for testing and developmental purposes only.
 .
 Even this description is not of much use, except showing that it
 must be indented with one space and no blank lines are allowed.

Currently, only the Package, Version, Architecture and Description
fields are used.



Repository maintainer perspective
---------------------------------

Packages are contained in a directory tree like this:

main:
admin/
comm/
devel/
doc/
editors/
graphics/
libs/
mail/
math/
misc/
net/
news/
science/
sound/
text/
utils/
web/

[...]

main/mail:

main/math:
foopkg_0_0_2-20020801_all.rpk

main/misc:
samplepkg_0_0_1-20020801_all.rpk

[...]

Not surprisingly, this tree mimics almost exactly Debian's, however
there is no restriction on it, except that the respective field
(Section) in packages' RUBY/control matches.

Branches could be devised like Debian's:

stable:
main/
contrib/

unstable:
main/
contrib/

The rpkg-scanpackages tool is run on the root dir and produces a
Packages file, which is just the RUBY/control from all packages dumped
together.  In the example above, rpkg-scanpackages would be run
separately on stable/main, stable/contrib, unstable/main, and
unstable/contrib.



Current limitations
===================

Only supports pure Ruby modules (i.e. no compiled extensions).

No integrity checks.

rapt only gets files from a local source.

File management relies on system commands (i.e. not really platform
independent).

Probably a lot more.



To do
=====

Find someone willing to co-develop (hint hint).

Arrangement for personal corners in the repository for snippet
exchange.

Messages telling the user what is going on during installation and
removal.

Remove all dependence on system command to run on all platforms.

Preinstallation scripts (e.g. for RDoc generation on the fly).

General cleaning and sweeping.

Remote sources via ftp and/or http.

(Much much) more testing.

Package signing.

Package and database integrity checks.

Choose better system directories and allow more source directories in
package building if needed.

Facilities for building binary-only, platform-targeted distributions
of compiled extensions.

Dependence checking.

Get some sleep.



Where to get it
===============

Temporarily on:

http://practicaltux.sourceforge.net/rpkg-0.1.tar.gz



License
=======

Same as Ruby.



IMPORTANT
=========

These programs are heavily experimental and should not be used for any
other purpose than testing and development.

These programs use system commands and, to test some of their
functionality, they have to be run as root.  I take *no*
responsibility if the research on cold fusion you've been working on
for your whole life suddenly vanishes in the cyberspace.  All I can
guarantee is that there is no `rm -rf' anywhere in the code...  at
least if I remember correctly (you know, I'm getting older---and
nastier).



How to help
===========

In whatever way you want, but especially:

I'm a total disaster when it comes to writing tests for programs that
deal with system resources.  The main program, in fact, doesn't come
with any.  If you are able to, I'm most grateful for any test case
(preferably written for Lapidary, just because that's what I
ordinarily use).

And, of course, take the source and cannibalize it to your heart's
content---that's all it is about.