NAME

ActivePerl::PPM::PPD - Parser for PPD files

SYNOPSIS

  my $ppd = ActivePerl::PPM::Package->new_ppd('<SOFTPKG NAME="Foo">...</SOFTPKG>');

DESCRIPTION

This module adds the new_ppd constructor to the ActivePerl::PPM::Package class. This constructor parses PPD files and allow package objects to be initialized from these files. PPD is an XML based format that is used to describe PPM packages.

The following methods are added:

$ppd = ActivePerl::PPM::Package->new_ppd( $ppd_document, %opt )

$ppd = ActivePerl::PPM::Package->new_ppd( $parsed_ppd_hashref, %opt )

The constructor take a literal document as argument and will return and object representing the PPD. The method returns undef if $ppd_document does not contain the expected XML.

The following options are supported:

arch => $archname

The $archname should be specified to select attributes for a specific architecture where the PPD describes multiple implementations. The value noarch is the default and will only select implementation sections without any ARCHITECTURE restriction.

base => $base_uri

All URIs in the PPD will be made absolute with $base_uri as base.

rel_base => $base_uri

All URIs in the PPD will be made relative if they can be resolved from $base_uri. Only safe to use together with base which is applied first. If both base and rel_base are the same, they cancel each other out and the effect is the same as if none of them where specified.

PPD XML FORMAT

The PPM PPD is an XML based format used to describe PPM packages. The format is based on the now defunct OSD specification (http://www.w3.org/TR/NOTE-OSD). This shows an example of a minimal PPD document:

  <SOFTPKG NAME="Acme-Buffy" VERSION="1.3" DATE="2002-03-27">
    <AUTHOR>Leon Brocard (leon@astray.com)</AUTHOR>
    <ABSTRACT>
      An encoding scheme for Buffy the Vampire Slayer fans
    </ABSTRACT>
    <PROVIDE NAME="Acme::Buffy" VERSION="1.3"/>
    <IMPLEMENTATION>
      <CODEBASE HREF="i686-linux-thread-multi-5.8/Acme-Buffy.tar.gz"/>
      <ARCHITECTURE NAME="i686-linux-thread-multi-5.8"/>
    </IMPLEMENTATION>
  </SOFTPKG>

The following elements are used:

<ABSTRACT>...</ABSTRACT>

Content is a short statement describing the purpose of this package. No attributes. Parent must be a SOFTPKG element.

<ARCHITECTURE NAME="..."/>

The required attribute NAME should match $Config{archname}-$major_vers for the perl this package was compiled for. If this element is missing, it's the same as specifying <ARCHITECTURE NAME="noarch"/>. No content. Parent must be either SOFTPKG or IMPLEMENTATION.

Packages or implementations marked with "noarch" are assumed to installable on any architecture.

<AUTHOR>...</AUTHOR>

Content is the package author's name (with email address). No attributes. Parent must be a SOFTPKG element.

<CODEBASE HREF="..."/>

The required HREF attribute provides a URI where the binary package (the tared up blib tree) of the package can be obtained. The URI can be relative and is then resolved based on the URI of the PPD document. No content. Parent must be SOFTPKG or IMPLEMENTATION.

<DEPENDENCY NAME="..." VERSION="..."/>

Deprecated. Required attribute is NAME. Optional attribute is VERSION. No content. Element might be repeated any number of times. Parent must be an IMPLEMENTATION element.

This element expresses a dependency on another package with the given name and with the given version number or better. The other package must be installed for this package to work.

This element is still recommended for PPDs that are to be used by both PPM4 and PPM3 clients, as the PPM3 clients will ignore any REQUIRE elements provided. PPM4 clients regard DEPENDENCY the same as REQUIRE, but will simply ignore the VERSION provided.

<IMPLEMENTATION>...</IMPLEMENTATION>

No attributes. Optional container for ARCHITECTURE, DEPENDENCY, INSTALL, PROVIDE, REQUIRE, UNINSTALL elements. Parent must be SOFTPKG. There can be multiple instances of IMPLEMENTATION but they should each contain an ARCHITECTURE element that differ from each other.

<INSTALL EXEC="..." HREF="..."/>

<INSTALL EXEC="...">...</INSTALL>

Optional attributes are EXEC and HREF. Textual content can be included. Provides a script or commands to run after the blib files of the package have been installed, a so called post-install script. The script to run can either be provided inline or externally via HREF. If both are provided then only the HREF is used. Parent must be either SOFTPKG or IMPLEMENTATION.

If EXEC is provided, it gives the name of the interpreter to run the script. For historical reasons, if the script is not obtained via HREF then any occurences of double semicolon ";;" is replaced by newline before it is saved in a temporary file and passed as the first argument to the EXEC interpreter. The special value "PPM_PERL" ensures that the script runs with the same perl interpreter that runs PPM. The special value "SELF" make the script run as a self contained executable.

If EXEC is not provided, the commands of the script are passed to the system command interpreter (via system(3)) one by one. If the script was obtained via HREF, each line is considered a command. If the script was obtained from the content, then a double semicolon ";;" is used to separate commands.

When the script/command runs it uses the unpacked package tarball (obtained by downloading the CODEREF) as the working directory, and the following environment variables will be set:

PPM_ACTION

One of "install", "upgrade" or "uninstall".

PPM_INSTARCHLIB

The archlib directory of the current install area.

PPM_INSTLIB

The lib directory of the current install area.

PPM_INSTPACKLIST

The name of the installed .packlist file of the package.

PPM_INSTROOT

The prefix directory of the current install area.

PPM_NEW_VERSION

The version label of the package just installed.

PPM_PERL

The path to the perl that runs PPM.

PPM_PREV_VERSION

The version label that the package had before the upgrade started. This variable is only present when PPM_ACTION is "upgrade".

PPM_VERSION

The version of PPM currently running.

<PROVIDE NAME="..." VERSION="..."/>

Required attribute is NAME. Optional attribute is VERSION. No content. Element can be repeated any number of times. Parent must be either SOFTPKG or IMPLEMENTATION.

The NAME represents a feature that this package provides if installed. Any label goes. VERSION is a floating point number.

Packages containing perl modules should have one PROVIDE element for each module installed by the package. Module names that do not naturally contain double colon "::" should have "::" appended to them.

<REPOSITORY>...</REPOSITORY>

Element must be root if present. Container for a set of SOFTPKG elements. Optional attributes are ARCHITECTURE and BASE.

ARCHITECTECTURE provides the default for all contained SOFTPKG elements that do not have an explicit ARCHITECTECTURE element.

BASE overrides the base URI that the relative URIs of CODEBASE, INSTALL and UNINSTALL are resolved from. If BASE itself is relative, it is first resolved based on the URI of the PPD document.

The file name package.xml is commonly used for documents containing a REPOSITORY root.

<REPOSITORYSUMMARY>...</REPOSITORYSUMMARY>

Treated the same as REPOSITORY. Supported for backwards compatibility with old style package.lst files.

<REQUIRE NAME="..." VERSION="..."/>

Required attribute is NAME. Optional attribute is VERSION. No content. Element might be repeated any number of times. Parent must be either SOFTPKG or IMPLEMENTATION.

This element expresses a dependency on some other package that provides the feature given by NAME and with the given version number or better. A package that provides the given feature must be installed for this package to work.

<SOFTPKG NAME="..." VERSION="..." DATE="...">...</SOFTPKG>

Represents a package available for PPM to install. Container for all the other elements defined here (except REPOSITORY and REPOSITORYSUMMARY).

Required attributes are NAME and VERSION. Optional attribute is DATE.

The NAME and VERSION value can be any label. Older versions of this specification had a more strict definition of VERSION as a sequence of exactly 4 numbers in the range 0 to 65535 separated by comma. If such values are encountered then they are converted to "standard" format by replacing the commas with dots and trimming off ".0.0" or ".0".

The DATE attribute should use ISO 8601 formatted date (or datetime) stamps. That is "YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ssZ" format. See http://en.wikipedia.org/wiki/ISO_8601 for more information.

Parent must be REPOSITORY or REPOSITORYSUMMARY, or the SOFTPKG can be the document root. Content elements can be in any order.

Documents where SOFTPKG is root are normally stored in files with the .ppd extension.

<UNINSTALL EXEC="..." HREF="..."/>

<UNINSTALL EXEC="...">...</UNINSTALL>

Used for scripts that run just before the blib files of the package is uninstalled. The attributes and content are treated the same as for INSTALL and the same set of environment variables are availabe to the script.

The uninstall script runs with a new, clean temporary directory as its working directory. The directory and its content is removed after the script finishes.

Changes since PPM3

The PPD format has changed in PPM4. This section lists the differences:

• The format of the SOFTPKG/VERSION attribute has been relaxed. This attribute should now contain the version identifier as used for the original package. PPM will not be able to order packages based on this label.

• The SOFTPKG/DATE attribute has been introduced. This should be the release date of the package. For CPAN packages this should be the date when the package was uploaded to CPAN.

• Added REQUIRE and PROVIDE elements that are used to describe features that this package depends on and provides. The NAME attribute is required for both. The VERSION attribute is optional and should be a floating number. Features are assumed to be backwards compatible and a feature with a higher version number is regarded as better.

• The DEPENDENCY elements are deprecated. Use REQUIRE instead. If present they are mapped to REQUIRE but their VERSION attribute is ignored.

• The OS, OSVERSION, PROCESSOR, PERLCORE elements are deprecated and always ignored. Implementations are matched using the ARCHITECTURE element only.

• The TITLE element is deprecated and ignored. The SOFTPKG/NAME attribute is the title.

SEE ALSO

the ActivePerl::PPM::Package manpage, http://www.w3.org/TR/NOTE-OSD