core.xars

XAR archives

The XP framework comes with a facility to bundle classes and resources into archives - called XARs. They are the rough equivalent of Unix TAR archives, Java's JAR archives and PHP's PHAR archives.

Class loading support

XAR archives can be added to the class path just like directories:

  include_path=".:/home/thekid/classes:/usr/local/xp/5.6.6/xp-rt-5.6.6.xar"

This setting will make the class loader search for classes in:

• The current directory (".")
• The directory /home/thekid/classes
• The archive /usr/local/xp/5.6.6/xp-rt-5.6.6.xar

To register a XAR archive at runtime, use the following sourcecode:

<?php
  with ($f= new File('/home/thekid/lib', 'de-thekid.xar')); {
    ClassLoader::registerLoader(new ArchiveClassLoader(new Archive($f)));
  }
?>

For further details on class loading see here.

The xar utility

To work with xar archives, the XP framework comes along with the xar command line utility.

Creating archives

To create xar archive containing all the files inside a given directory, use the following:

  $ cd /home/thekid/classes
  $ ls *
    /home/thekid/classes/de:
    thekid
  
  # Add all files in de/ (recursively)
  $ xar cvf de-thekid.xar de
  
  # All files in de/ *and* a single other file
  $ xar cvf de-thekid.xar de META-INF/manifest.ini

Note: For convenience, well-known version-control directories (.svn, CVS) are excluded by default!

Listing an archive's contents

The files contained in an archive can be listed as follows:

  $ xar tvf de-thekid.xar
     2.055 de/thekid/scriptlet/state/HomeState.class.php
     1.091 de/thekid/auth/Authenticator.class.php
    14.656 de/thekid/auth/impl/DatabaseAuthenticator.class.php

Extracting

To extract files from an archive to the current working directory:

  # Extract all files
  $ xar xvf de-thekid.xar
  
  # Extract only a single file
  $ xar xvf de-thekid.xar de/thekid/auth/Authenticator.class.php

  # Extract all files inside de/thekid/auth (recursively)
  $ xar xvf de-thekid.xar de/thekid/auth

Note: Files and directories are created if necessary. Existing files are overwritten without inquiry!

Viewing files inside an archive

Showing archives files' contents is like extracting them, with the difference that nothing will be written to the filesystem.

  $ xar svf de-thekid.xar de/thekid/auth/Authenticator.class.php
    == de/thekid/auth/Authenticator.class.php ==
    <?php
      interface Authenticator {
        // ...
      }
    ?>

History

XARs as a core concept were first introduced in October 2006 - see http://xp-framework.net/rfc/0074 for details.