ppm(3)

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:PACKAGESO.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, operat
ing 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 infor mation 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 loca
tion will become the default PPD location for this
package.

During an installation, the following actions are per
formed:

- 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 cre

ated 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 infor

mation.
- 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 cur
rently 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 'loca
tion' 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 expres
sion '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. 'loca
tion' 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 func
tion 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 pre
viously returned by a call to GetPPMOptions().

EXAMPLES

PPM::AddRepository("repository" => 'ActiveState', "loca
tion" => "http://www.ActiveState.com/packages", "save" =>
1);

Adds a repository to the list of available reposito
ries, and saves it in the PPM options file.

PPM::InstallPackage("package" => 'http://www.ActiveS
tate.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 soft
ware 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 loca
tion is searched.

PPM::VerifyPackage("package" => 'foo', "location" =>
'P:PACKAGES', "upgrade" => true);

Compares the currently installed version of the soft
ware 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.ActiveS
tate.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 access
ing 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 PPM::XML::PPD. 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 cir
cumstances should never require modification other
than by PPM itself. For more information on this
file, refer to PPM::XML::PPMConfig.

AUTHOR

Murray Nesbitt, <murray@cpan.org>

SEE ALSO

PPM::XML::PPMConfig .