= Packaging with rpa-base

bla bla why do so, the old idea of letting upstream developers hack their sw.
while we work on the packages, etc...

= Overall process

When installing a port, rpa-base performs the following:
* download the port sources (.rps) and unpack on a temp dir
* run their install.rb:
  * run a number of tasks, specified in terms of "helpers" in the install.rb;
    there a default lists of tasks to be done for different sort of packages
    (pure Ruby lib, application, etc). 
  * In the process, files are installed to a temporary dir; then a
    binary package (.rpa) is generated by packing those files together
    with the associated metadata (description, requirements, digests, file
    lists, etc)
  ==> at this point, there's a .rpa package for the port we want to install
* unpack the .rpa package. This is done atomically, by taking a snapshot of
  the previous package state (i.e. we repackage the corresponding files in our
  FS) and rolling back if something goes wrong. Conflicts with unmanaged files
  are detected and handled gracefully.


= Overview of a rpafied install.rb

Let's look at the install.rb for types:

require 'rpa/install'

class Install_types < RPA::Install::PureRubyLibrary
    name "types"
    version "0.1.80-1"
    classification Library.Development
    description <<EOF
A library to perform runtime type checking in Ruby

types allows you to specify method signatures. You can give a list of
acceptable classes for each parameter, perform respond_to? tests or
enforce more complex constraints based on set operations (union,
intersection).
EOF
end


the install.rb is purely "declarative", there's seemingly no direct method
calls to trigger any action at that point. This is because there's 2 ways the
install.rb can be invoked:
 * it can be loaded by rpa when you do  rpa install foo
 * you can run it directly if you unpack the port's sources
 
There's some magic with Class#inherited to make sure that the mere act of
subclassing tells the system that something is about to be installed.

There's 3 types of installers atm. (see rpa/install.rb):
PureRubyLibrary, Application, FullInstaller. The installers are
little more than containers for default lists of tasks; for instance,
FullInstaller has a task to build extensions, but PureRubyLibrary
doesn't.

A note on the name of the installer class: to avoid name clashes, the
installer class for por xxx should be Install_xxx (for foo-bar,
Install_foo_bar, etc).

The things in the class body specify the metadata for the package about to be
built. They are quite obvious.

== Specifying metadata:
  name "portname"
      lowercase, hyphens ok
  version "0.1.2-3"  
      this is validated (only some are valid)
      the -3 part indicates "revision 3 of the port" (i.e.
      3rd revision of 0.1.2 done by RPA)
  requires "foo", "bar", "baz"   
      all these ports need to be installed in order for this to one to work.
      Note that the version numbers are not specified, cause this will
      *always* mean "the latest foo, bar and baz available IN THIS RPA
      RELEASE". Since APIs are stable within a RPA release, it works.
  build_requires "foo", "bar"
      these packages have to be installed before we try to build this one; for
      instance if the docs are generated using redcloth, you'll want to have
      this installed before the .rpa is made
 classification Library.Development
      note that Library.Development is a Ruby constant: this self-validates,
      since if you tried a non-existent classification (in the "official"
      hierarchy, rpa/classification.rb), Ruby would complain about a missing
      constant
 description "some text"
      I normally favor a 1 line short desc, followed by a blank line, and the
      real desc thereafter. rpa-base might enforce this in the future

== Building phases

So far so good, we've seen how to specify metadata, but how do we tell what
has to be done? The reason why there's seemingly no "action code" in most
install.rb files is that if you choose the base installer class correctly, the
default tasks do most of the stuff that needs to be done if the source
directory layout is the typical one (lib/ ext/ test/ examples/ etc).

However, sometimes you'll want to specify tasks. Before getting to that point,
we have to introduce the package building phases

Instead of using a linear list of tasks, the tasks are divided into 4 phases:
prebuild. build, install, postinstall (NOTE: more phases might be added if
needed). The .rpa is generated in the install phase (digests, file lists, etc
are also built at that time). In general, you want to copy files around, etc in
the build phase.

== Tasks and helpers

In order to specify a task to be run in some phase, you do something like 

 build do 
     installexamples "samples"
     # more helpers can be used here, 1 helper == 1 easy way to define 1 task
 end

You can use skip_default SomeHelperClass to remove a task from the default
list:
  install { skip_default RunUnitTests }

Let's take a look at fxruby's install.rb:

require 'rpa/install'

class Install_fxruby < RPA::Install::FullInstaller
    name "fxruby"
    version "1.0.29-1"
    classification Application.Devel
    build do
        installdocs %w[README ChangeLog LICENSE README.win32.txt index.html]
    end
    install{ skip_default RunUnitTests }
    description <<EOF
Ruby bindings for FOX
EOF
end

RPA::Helper::Installdocs is a helper class that copies the documentation to
the appropriate place (normally share/rpax.y/doc/portname/ under the tempdir). 
There's some heavy meta-programming to allow you to initialize the task with a
simple call to "installdocs": that creates a Installdocs task object, and adds
it to the list of tasks in the build phase.

Most helpers take no arguments, but those are not the ones you'll use
manually; the helpers that do are normally used to copy files around, and they
have the following syntax:

 installwhatever <array of filenames or dirname> [, "dest subdir name"]

for instance

 installdocs "htmldocs", "html"

would copy the docs under "htmldocs" to share/doc/rpax.y/doc/portname/html
The following is very common:

 installdocs %[README ChangeLog]

this will copy the files given in the array to the default docdir.

The installwhatever helpers have different default source and dest. dirs. Some
examples:

 installexamples      examples/    ==>    examples/  under docdir
 installdocs          doc/         ==>    doc dir
 installtests         test/        ==>    lib/ruby/rpa0.0/tests/portname
 installextensions    .so's in ext/*  ==> appropriate place ;)
 installmodules       lib/         ==> lib/ruby/site_ruby and RPA's private
                                       area in lib/ruby/rpax.y
 installexecutables   bin/         ==>    bin/
 installdata          data/        ==>    share/data/portname/

== Replacing default tasks

The first time you do use a helper, it will override the default one if it was
already in the list.

== Ordering of the tasks

The default list of tasks defines also a default ordering. For instance, in
FullInstaller buildextensions will always be run before installextensions
(anything else would make no sense). If the task you're adding wasn't
originally in the default list, it will be placed at the end of the current
phase (be careful).

== Arbitrary tasks

There's a generic  task  helper. You pass it a block which will be run.
Those tasks will be added at the end of the phase they're defined in.

Example from ri-rpa's install.rb

    build do
        task do 
            dest = File.join("rpa", @dest, "share", "ri-rpa")
            @fileops.mkdir_p dest, :mode => 0755
            @fileops.cp_r "data", dest
            Find.find(dest) do |d|
                @fileops.rm_rf d if d =~ /.svn/ 
            end
        end
    end

note that this wouldn't be needed now, cause there's a installdata helper, so 
just
  installdata
would do the trick.