NAME

ppm - PPM (Perl Package Management)

SYNOPSIS

 use PPM;

 PPM::InstallPackage("package" => $package, "location" => $location, "root" => $root);
 PPM::RemovePackage("package" => $package, "force" => $force);
 PPM::VerifyPackage("package" => $package, "location" => $location, "upgrade" => $upgrade);
 PPM::QueryInstalledPackages("searchRE" => $searchRE, "searchtag" => $searchtag, "ignorecase" => $ignorecase);
 PPM::InstalledPackageProperties();

 PPM::ListOfRepositories();
 PPM::RemoveRepository("repository" => $repository, "save" => $save);
 PPM::AddRepository("repository" => $repository, "location" => $location, "save" => $save);
 PPM::RepositoryPackages("location" => $location);
 PPM::RepositoryPackageProperties("package" => $package, "location" => $location);
 PPM::RepositorySummary("location" => $location);

 PPM::GetPPMOptions();
 PPM::SetPPMOptions("options" => %options, "save" => $save);

DESCRIPTION

PPM is a group of functions intended to simplify the tasks of locating, installing, upgrading and removing software 'packages'. It can determine if the most recent version of a software package is installed on a system, and can install or upgrade that package from a local or remote host.

PPM uses files containing a modified form of the Open Software Distribution (OSD) specification for information about software packages. These description files, which are written in Extensible Markup Language (XML) code, are referred to as 'PPD' files. Information about OSD can be found at the W3C web site (at the time of this writing, http://www.w3.org/TR/NOTE-OSD.html). The modifications to OSD used by PPM are documented in PPM::ppd.

PPD files for packages are generated from POD files using the pod2ppd command.

USAGE

PPM::InstallPackage(``package'' => $package, ``location'' => $location, ``root'' => $root);

Installs the specified package onto the local system. 'package' may be a simple package name ('foo'), a pathname (P:\PACKAGES\FOO.PPD) or a URL (HTTP://www.ActiveState.com/packages/foo.ppd). In the case of a simple package name, the function will look for the package's PPD file at 'location', if provided; otherwise, it will use information stored in the PPM data file (see 'Files' section below) to locate the PPD file for the requested package. The package's files will be installed under the directory specified in 'root'; if not specified the default value of 'root' will be used.

The function uses the values stored in the PPM data file to determine the local operating system, operating system version and CPU type. If the PPD for this package contains implementations for different platforms, these values will be used to determine which one is installed.

InstallPackage() updates the PPM data file with information about the package installation. It stores a copy of the PPD used for installation, as well as the location from which this PPD was obtained. This location will become the default PPD location for this package.

During an installation, the following actions are performed:

    - the PPD file for the package is read
    - a directory for this package is created in the directory specified in
      <BUILDDIR> in the PPM data file.
    - the file specified with the <CODEBASE> tag in the PPD file is
      retrieved/copied into the directory created above.
    - the package is unarchived in the directory created for this package
    - individual files from the archive are installed in the appropriate
      directories of the local Perl installation.
    - perllocal.pod is updated with the install information.
    - if provided, the <INSTALL> script from the PPD is executed in the
      directory created above.
    - information about the installation is stored in the PPM data file.

PPM::RemovePackage(``package'' => $package, ``force'' => $force)

Removes the specified package from the system. Reads the package's PPD (stored during installation) for removal details. If 'force' is specified, even a package required by PPM will be removed (useful when installing an upgrade).

PPM::VerifyPackage(``package'' => $package, ``location'' => $location, ``upgrade'' => $upgrade)

Reads a PPD file for 'package', and compares the currently installed version of 'package' to the version available according to the PPD. The PPD file is expected to be on a local directory or remote site specified either in the PPM data file or in the 'location' argument. The 'location' argument may be a directory location or a URL. The 'upgrade' argument forces an upgrade if the installed package is not up-to-date.

The PPD file for each package will initially be searched for at 'location', and if not found will then be searched for using the locations specified in the PPM data file.

PPM::QueryInstalledPackages(``searchRE'' => $searchRE, ``searchtag'' => $searchtag, ``ignorecase'' => $ignorecase);

Returns a hash containing information about all installed packages. By default, a list of all installed packages is returned. If a regular expression 'searchRE' is specified, only packages matching it are returned. If 'searchtag' is specified, the pattern match is applied to the appropriate tag (e.g., ABSTRACT).

The data comes from the PPM data file, which contains installation information about each installed package.

PPM::InstalledPackageProperties();

Returns a hash with package names as keys, and package properties as attributes.

PPM::RepositoryPackages(``location'' => $location);

Returns a hash, with 'location' being the key, and arrays of all packages with package description (PPD) files available at 'location' as its elements. 'location' may be either a remote address or a directory path. If 'location' is not specified, the default location as specified in the PPM data file will be used.

PPM::ListOfRepositories();

Returns a hash containing the name of the repository and its location. These repositories will be searched if an explicit location is not provided in any function needing to locate a PPD.

PPM::RemoveRepository(``repository'' => $repository, ``save'' => $save);

Removes the repository named 'repository' from the list of available repositories. If 'save' is not specified, the change is for the current session only.

PPM::AddRepository(``repository'' => $repository, ``location'' => $location, ``save'' => $save);

Adds the repository named 'repository' to the list of available repositories. If 'save' is not specified, the change is for the current session only.

PPM::RepositoryPackageProperties(``package'' => $package, ``location'' => $location);

Reads the PPD file for 'package', from 'location' or the default repository, and returns a hash with keys being the various tags from the PPD (e.g. 'ABSTRACT', 'AUTHOR', etc.).

PPM::RepositorySummary(``location'' => $location);

Attempts to retrieve the summary file associated with the specified repository, or from all repositories if 'location' is not specified. The return value is a hash with the key being the repository, and the data being another hash of package name keys, and package detail data.

PPM::GetPPMOptions();

Returns a hash containing values for all PPM internal options ('IGNORECASE', 'CLEAN', 'CONFIRM', 'ROOT', 'BUILDDIR', 'DOWNLOADSTATUS').

PPM::SetPPMOptions(``options'' => %options, ``save'' => $save);

Sets internal PPM options as specified in the 'options' hash, which is expected to be the hash previously returned by a call to GetPPMOptions().

EXAMPLES

PPM::AddRepository(``repository'' => 'ActiveState', ``location'' => ``http://www.ActiveState.com/packages'', ``save'' => 1);: Adds a repository to the list of available repositories, and saves it in the PPM options file.
PPM::InstallPackage(``package'' => 'http://www.ActiveState.com/packages/foo.ppd');: Installs the software package 'foo' based on the information in the PPD obtained from the specified URL.
PPM::VerifyPackage(``package'' => 'foo', ``upgrade'' => true): Compares the currently installed version of the software package 'foo' to the one available according to the PPD obtained from the package-specific location provided in the PPM data file, and upgrades to a newer version if available. If a location for this specific package is not given in PPM data file, a default location is searched.
PPM::VerifyPackage(``package'' => 'foo', ``location'' => 'P:\PACKAGES', ``upgrade'' => true);: Compares the currently installed version of the software package 'foo' to the one available according to the PPD obtained from the specified directory, and upgrades to a newer version if available.
PPM::VerifyPackage(``package'' => 'PerlDB');: Verifies that package 'PerlDB' is up to date, using package locations specified in the PPM data file.
PPM::RepositoryPackages(``location'' => http://www.ActiveState.com/packages);: Returns a hash keyed on 'location', with its elements being an array of packages with PPD files available at the specified location.
%opts = PPM::GetPPMOptions();
$options{'CONFIRM'} = '0';
PPM::SetPPMOptions(``options'' => \%opts, ``save'' => 1);: Sets and saves the value of the option 'CONFIRM' to '0'.

ENVIRONMENT VARIABLES

HTTP_proxy: If the environment variable 'HTTP_proxy' is set, then it will be used as the address of a proxy for accessing the Internet. If the environment variables 'HTTP_proxy_user' and 'HTTP_proxy_pass' are set, they will be used as the login and password for the proxy server. If a proxy requires a certain User-Agent value (e.g. ``Mozilla/5.0''), this can be set using the 'HTTP_proxy_agent' environment variable.

FILES

package.ppd: A description of a software package, in Perl Package Distribution (PPD) format. More information on this file format can be found in the PPM::XML::PPD manpage. PPM stores a copy of the PPD it uses to install or upgrade any software package.
ppm.xml - PPM data file.: The XML format file in which PPM stores configuration and package installation information. This file is created when PPM is installed, and under normal circumstances should never require modification other than by PPM itself. For more information on this file, refer to the PPM::XML::PPMConfig manpage.

AUTHOR

Murray Nesbitt, <murray@ActiveState.com>