ActivePerl::PPM::InstallArea - Perl installation area
my $area = ActivePerl::PPM::InstallArea->new("site"); # or my $area = ActivePerl::PPM::InstallArea->new(prefix => "$ENV{HOME}/perl");
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
the ExtUtils::MakeMaker manpage.
An install area is divided into the following directories:
This is where architecture neutral modules go. Packages that are implemented in pure perl are installed here.
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
.
This is where architecture neutral programs go.
This is where architecture specific programs go. For ActivePerl this
will normally be the same as script
.
This is where configuration files go.
This is where Unix style manual pages describing programs go.
This is where Unix style manual pages describing modules go.
This is where HTML files go.
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:
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.
Returns the name. This returns the empty string for nameless InstallArea.
Returns the corresponding path.
Returns the list of directories to be pushed onto perl's @INC for the current install area.
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.
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.
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.
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 the ActivePerl::PPM::Package manpage object) with the following elements:
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.
The version identifier for the given package.
Who the current maintainer of the package is. Should normally be on the form "Givenname Lastname <user@example.com>".
A short sentence describing the purpose of the package.
Pick up files to install from the given blib style directory. The codebase directory of PPD packages is usually a tarball of this stuff.
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.
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.
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:
Only verify the given package.
Function called back for each file visited. The function is called with 3 arguments; the file name, expected md5 checksum and expected file mode.
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.
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 the ActivePerl::PPM::Package manpage for what field names are available.
Return an package object (see the ActivePerl::PPM::Package manpage) 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.
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.
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.
Returns TRUE if the package with the given name and version number is installed.
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.
Returns the list of names for the files that belong to the given package. In scalar context return the number of files.
Return the $id if the package that owns the given file, or undef
if
the file is not tracked by this install area.
Returns the .packlist file for the given package. See the ExtUtils::Packlist manpage.
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 the ExtUtils::Packlist manpage 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.
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
=> $boolIf TRUE don't try to update the package version from the version number of the module with the same name as the pacakge.
the ActivePerl::PPM::Package manpage, the ExtUtils::Packlist manpage.
none.