- NAME
- SYNOPSIS
- DESCRIPTION
- SEE ALSO
- BUGS

# NAME

ActivePerl::PPM::InstallArea - Perl installation area

# SYNOPSIS

      my $area = ActivePerl::PPM::InstallArea->new("site");
      # or
      my $area = ActivePerl::PPM::InstallArea->new(prefix => "$ENV{HOME}/perl");

# DESCRIPTION

An `ActivePerl::PPM::InstallArea` object provide an interface to a Perl install area. Different install areas might have different protection policies and each contain a set of installed packages and modules. The concept is the same as `INSTALLDIRS` provided by ExtUtils::MakeMaker.

An install area is divided into the following directories:

lib

  This is where architecture neutral modules go. Packages that are implemented in pure perl are installed here.

archlib

  This is where architecture specific modules go. Packages that are implemented using XS code are installed here. For ActivePerl this will normally be the same as `lib`.

script

  This is where architecture neutral programs go.

bin

  This is where architecture specific programs go. For ActivePerl this will normally be the same as `script`.

etc

  This is where configuration files go.

man1

  This is where Unix style manual pages describing programs go.

man3

  This is where Unix style manual pages describing modules go.

html

  This is where HTML files go.

prefix

  This just provide a prefix for the install area as a whole. All paths above should be at or below `prefix`.

The following methods are provided:

$area = ActivePerl::PPM::InstallArea->new( $name )
$area = ActivePerl::PPM::InstallArea->new( %opts )

  Constructs a new `ActivePerl::PPM::InstallArea` object. If constructed based on $name, then the constructor might croak if no install area with the given name is known. The "perl" and "site" install areas are always available. Some perls might also have a "vendor" install area.

  Alternatively the directories to use can be specified directly by passing them as key/value pair %opts. Only `prefix` is mandatory. All other directories are derived from this, except for the `man*` directories will only set up if specified explicitly.

  The option `autoinit` will if TRUE make the install area call $self->initialize automatically when some method need access to the database.

$area->name

  Returns the name. This returns the empty string for nameless InstallArea.

$area->prefix
$area->archlib
$area->lib
$area->bin
$area->script
$area->man1
$area->man3
$area->html
$area->etc

  Returns the corresponding path.

$area->inc

  Returns the list of directories to be pushed onto perl's @INC for the current install area.

$area->initialized

  Returns TRUE if this area has been initialized. If `autoinit` was specified for the constructor, then this method might have the side effect of actually initializing the database, in which case this returns TRUE.

$area->initialize

  Set up the database used to track packages for the install area if not already set up. This invokes sync_db() if the database was created.

  Most methods will croak unless the install area has been initialized. Exceptions are name(), readonly(), initialized(), packages() and the directory accessors (like lib(), script(),...).

  The `autoinit` option can be specified for the constructor to make the database be automatically set up during the first method call that needs it.

$area->readonly

  Returns TRUE if it is not possible to install or remove packages from the area. This is usually caused by the user not having permission to modify the files of the area.

  This also returns TRUE for unintialized install areas.

$area->install( packages => [\%pkg1, \%pkg2, ...] )

  Install the given list of packages as one atomic operation. The function returns TRUE if all packages installed or FALSE if installation failed.

  Each package to be installed is described by a hash reference (or an ActivePerl::PPM::Package object) with the following elements:

  name => $name

    The name of the package. If a package with the given name is already installed, then it will replaced with the new package. This is the only mandatory attribute.

  version => $version

    The version identifier for the given package.

  author => $string

    Who the current maintainer of the package is. Should normally be on the form "Givenname Lastname <user@example.com>".

  abstract => $string

    A short sentence describing the purpose of the package.

  blib => $path

    Pick up files to install from the given blib style directory. The codebase directory of PPD packages is usually a tarball of this stuff.

  files => \%hash

    A hash describing files and directories to install. The keys are where to copy files from and the values are install locations. The install locations selects what type of directory to install into by prefixing them with an dir identifier followed by a colon. Example:

           files => {
              Foo => "archlib:Foo",
              "Bar.pm" => "lib:Bar.pm"
           }

    This will install the "Foo" directory into the archlib area and the "Bar.pm" module into the lib area.

$area->uninstall( $name )

  Removes the given package and its installed files. Croaks if no such package was installed in the first place. Uninstalling a package might break other packages that depended on features this package provided.

$area->verify( %opts )

  Verify that the files of the installed packages are still present and unmodified.

  In scalar context returns TRUE if all files where still found good. In array context return key/value pairs suitable for assignment to a hash. The `verified` value is the number of files checked. The `missing`, `modified`, `wrong_mode` tally the files found to be missing, modified or chmoded.

  The following options are recognized:

  package => $name

    Only verify the given package.

  file_cb => \&sub

    Function called back for each file visited. The function is called with 3 arguments; the file name, expected md5 checksum and expected file mode.

  badfile_cb => \&sub

    Function called back each time a bad file is found. The first argument is what kind of badness (same as the status keys in the return value), the second is the file name and the addtional info varies depending on kind.

$area->packages( @fields )

  Without arguments returns the sorted list of names of packages currently installed. In scalar context returns the number of packages installed, or `undef` if database has not been initialized.

  With arguments return a list of array references each one representing an installed package. The elements of each array are the fields requested. The list will be sorted by package name. See ActivePerl::PPM::Package for what field names are available.

$area->package( $id )
$area->package( $name )
$area->package( $name, sloppy => 1 )

  Return an package object (see ActivePerl::PPM::Package) for the given package. Returns `undef` if no such package is installed.

  If no package match the specified name exactly and `sloppy` is specified then search again ignoring case and even search for features provided that match name. The method will croak if this extended search end up matching multiple packages.

$area->package_id( $name )

  Returns the internal identifier for the given package. The package name much match exactly; case matters. Returns `undef` if no such package is installed. This is the cheapest way to check if a package is installed.

$area->package_id( $name, sloppy => 1 )

  Find package even if the name does not match exactly. The package will be found if the name match without regard to case or if it provide the given name as a feature. Will croak if multiple packages match.

$area->package_have( $name, $version )

  Returns TRUE if the package with the given name and version number is installed.

$area->feature_have( $feature )

  If one of the installed packages provide the given feature, then the feature version number is returned. The method returns `undef` if no package provide the given feature.

$area->package_files( $id )

  Returns the list of names for the files that belong to the given package. In scalar context return the number of files.

$area->file_owner( $path )

  Return the $id if the package that owns the given file, or `undef` if the file is not tracked by this install area.

$area->package_packlist( $id )

  Returns the .packlist file for the given package. See ExtUtils::Packlist.

$area->packlists

  Returns the list of packages that have .packlist files installed. In scalar context return a hash reference; the keys are package names and the values are full paths to the corresponding .packlist file. This will also pick up packages installed by other means that by PPM. See ExtUtils::Packlist for more information about these files. PPM does not use .packlist files to track the files installed by the packages it manage, but it keeps them in sync for other tools that manage modules.

$area->sync_db( %opt )

  Synchronize the state of the PPM database with what modules seems to be installed in the directories of the current install area. Packages where all files are gone will also be deleted from the PPM database.

  The following options are recognized:

  `keep_package_version` => $bool

    If TRUE don't try to update the package version from the version number of the module with the same name as the pacakge.

# SEE ALSO

ActivePerl::PPM::Package, ExtUtils::Packlist.

# BUGS

none.