Shipping an application with XP archives

at 2006-10-15 in Editorial by kiesel (0 comments)

Ever since, distributing XP applications to the "end user" could be quite a pain: you would've to tell people to install subversion on their servers, show them how to check out a copy of the XP framework with all it's millions of directories, let them put all required directories into their include_path - mostly there's more than one directory which needs to be included.
Then, whenever they want to upgrade the application, they need to update their checkout, exposing them to the danger of conflicts or incompatibilities in the classes API each time.

Now, with the arrival of XP class archives (which actually already exist for quite some time), this is a lot easier! Read on to see how shipping XP applications could be like in the future.

Let's have a look at the steps involved to create a shipping-ready application. We're shipping the dialog application in this example.

As a prerequisite, we need the xp package tools be installed in our environment. In order to do that, create a symlink somewhere in your search path that points to the shell script:

alex@boost:~/bin# ln -s ~/devel/xp.public/trunk/experiments/people/kiesel/php/cca/xppkg

xppkg will need the Unix command realpath to work, also the php binary must be available.

We confirm the availability by invoking the script:

alex@boost:~# xppkg 
Usage: /home/alex/bin/xppkg command [FILE ...]
* Command is one of: {ls|cat|diff|manifest|show-manifest}

* xppkg ls ARCHIVE
  Shows the contents of the XP archive given by FILENAME

* xppkg cat ARCHIVE FILENAME
  Shows the contents of the file FILENAME in the archive ARCHIVE

* xppkg diff|di [-v] ARCHIVE ARCHIVE
  Shows the differences between the two archives in svn diff style.
  If --verbose|-v is given, files with differences will be fed to
  the unix diff command.

* xppkg manifest|mf FILE
  Uses the file FILE as manifest file and creates a new .xar file
  with the directions from that file.

* xppkg show-manifest|smf ARCHIVE
  Shows the manifest information recorded for archive ARCHIVE

(Note: this tool requires the Unix realpath command and the php binary in the search path).

It's this article's target to create a single .tar.gz file at the end, so let's switch to the dialog application's project directory and do some preparative work:

alex@boost:~# cd devel/xp.public/trunk/ports/dist/www/dialog/
alex@boost:~/devel/xp.public/trunk/ports/dist/www/dialog# mkdir classes conf conf/manifest

The classes directory will be the place for our .xar class archive. conf often already exists, and manifest is the directory where we'll keep the packaging instruction files.
Creating suchs an instruction file is the next task. I'll name it dialog.ini and it looks like this:

[application]
name="Dialog Website"
short="dialog"
version="1.0"

[repository::core]
base="%TRUNK%/skeleton"
include="lang\.base\.php|lang|io|scriptlet|util|xml|sapi/scriptlet|sapi/cgi|peer|img"
exclude="xml/soap|xml/xmlrpc|xml/wddx|xml/uddi|util/profiling|peer/irc|peer/news|peer/mail"

[repository::dialog]
base="%TRUNK%/ports/classes"
include="de/thekid/dialog"

The [application] section contains some meta information about the project; each repository:: section control what files are being included in the archive, and from where.
We've got two repositories here which is due to the fact that there are two main paths that classes come from: skeleton and ports/classes - having more than one repository does not mean they'll not end up in one single .xar.

The include and exclude directives control which directories and files to include and which to exclude from the archive. Not giving any includes would result in an empty archive. You can see that there are quite many sub-packages exluded, eg. xml/soap and so on - this is not necessary; the archive can also contain all files in the framework - it'd just get bigger which has a impact on the "download size" of the tar.gz but not the execution or loading speed of your application. The rule of thumb is: Better include more classes than you absolutely need than to have a missing class which would break the application.

Now, let's roll the class archive:

alex@boost:~/devel/xp.public/trunk/ports/dist/www/dialog# xppkg manifest conf/manifest/dialog.ini 
=== Packaging application Dialog Website (xp-dialog-1.0)
=== Building file list ...
--- Adding repository::core
    Got 373 files in /mnt/home/alex/devel/xp.public/trunk/skeleton
--- Adding repository::dialog
    Got 23 files in /mnt/home/alex/devel/xp.public/trunk/ports/classes
=== Fastening package ...
=== Finished, package is xp-dialog-1.0.xar (1.348.075 bytes)

Looks good. If you're unsure whether a certain file has made it into the archive, just give it a look:

alex@boost:~/devel/xp.public/trunk/ports/dist/www/dialog# xppkg ls xp-dialog-1.0.xar 
Archive xp-dialog-1.0.xar contains:
     1.865 de/thekid/dialog/io/ProcessorTarget.class.php
     3.794 de/thekid/dialog/io/IndexCreator.class.php
[...]
       365 META-INF/MANIFEST.ini
================================================================================
 1.246.187 Total 397 files

The META-INF/MANIFEST.ini file contains the manifest file that was used to create that .xar. If you want to look at it, use the xppkg cat command.

Move the resulting xp-dialog-1.0.xar into the classes directory. The application must ship lang.base.php outside of the archive, so copy it into the doc_root directory (don't worry, there's nothing insecure about that).

At this point, there are all files required to setup dialog in this directory, either as a separate file or in the archive. All there's left is to roll the .tar.gz now. Let's get this last step done:

alex@boost:~/devel/xp.public/trunk/ports/dist/www/dialog# cd ..
alex@boost:~/devel/xp.public/trunk/ports/dist/www# tar czf xp-dialog-1.0.tar.gz --exclude=albums
--exclude=shots --exclude=.svn dialog/classes dialog/doc dialog/doc_root dialog/etc dialog/xsl 
alex@boost:~/devel/xp.public/trunk/ports/dist/www# ls -lh xp-dialog-1.0.tar.gz 
-rw-r--r--  1 alex  alex   462K Oct 15 19:18 xp-dialog-1.0.tar.gz

Hooray! We've made it. That's the application distribution file.

You can subscribe to the XP framework's news by using RSS syndication.

Shipping an application with XP archives

Subscribe

Categories

Related