Support for installing/removing extension packages.
Objects of this class represent an installed or installable
Foswiki Extension.
To the caller, the Package object carries the manifest of the package,
and provides methods for loading the manifest from an extension installer,
and for backing up, installing or removing an Extension from the Foswiki
installation.
The internal storage of the manifest is as a hash. The hash is populated
as two possible views:
- File View - lists the attributes of each file in the package
- Attachment View - list the files to be attached to each topic.
Pictorially,
- MANIFEST
-
{path/file.name}
Distributed filename root is Foswiki root.
-
{ci}
- Flag specifying if file should be checked into the revision control system
-
{perms}
- File permissions in Linux octal string format
-
{md5}
- MD5 checksum of file - optional
-
{web}
- Web/Subweb name if topic or attachment
-
{topic}
- Topic name if topic or attachment
-
{attach}
- Attachment name if attachment
-
{ATTACH}
-
{Web/Subweb/Topic}
- {AttachmentName} = Filename of the attachment.
ClassMethod
new(%options)
-
%options
- A hash of options for the installation
-
root
=> 'path' The root path of the Foswiki installation used for file operations - REQUIRED
-
module
=> 'name' Name of the package being installed - REQUIRED
-
repository
=> hash The source repository information, built from $Foswiki::cfg{ExtensionsRepositories}
-
DIR
=> 'dir' Directory containing expanded package, Used with EXPANDED => 1
-
EXPANDED
=> 0/1 Specify that archive file has already been expanded (for unit tests)
-
USELOCAL
=> 0/1 If local versions of _installer or archives are found, use them instead of download.
-
NODEPS
=> 0/1 Set if dependencies should not be installed. Default is to always install Foswiki dependencies. (CPAN and external dependencies are not handled by this module.)
-
SIMULATE
=> 0/1 Set to 1 if actions should be simulated - no file system modifications other than temporary files.
-
ENABLE
=> 0/1 Set to 0 to prevent extension from being enabled. Defaults to ENABLE => 1
- seen => \%seen Hash of modules already seen, to be installed.
-
CONTINUE
=> ... (FUTURE) ... continue processing after errors. Not implemented
ObjectMethod
finish()
Clean up the object, releasing any memory stored in it.
ObjectMethod
module()
Get module name.
ObjectMethod
repository()
Get repository.
ObjectMethod
option($name [, $value]))
Get or set the option associated with the object.
ObjectMethod
install($reporter) → ($boolean, \%plugins, \$cpanDeps)
Perform a full installation of the package, including all dependencies
and any required downloads from the repository.
A backup is taken before any changes are made to the file system.
Missing directories are created as required. The files are mapped into
non-standard locations by _mapTarget. If a file is
read-only, it is temporarily overridden and the mode of the file is
restored after the move.
Unless the noci flag is set in the manifest, files are "checked in"
by creating a Topic Meta object and using the Foswiki Meta API to save
the topic.
Returns a status (1 is good) and two hashes, one of installed plugins and
the other of required CPAN dependencies.
uninstall ( $reporter ) -> $status
Remove each file identified by the manifest. Also remove
any rcs "...,v" files if they exist. Note that directories
are NOT removed unless they are empty.
Pre and Post un-install handlers are run.
Returns a status (1 for success)
loadInstaller ($reporter) -> $ok
Looks for the ${extension}_installer or
${extension}_installer.pl file and extracts the manifest,
dependencies and pre/post Exit routines from the installer.
The local search path is:
- Directory passed as parameter, or root of installation
- This directory is also examined for the .pl version of the _installer
- The
working/Configure/download
directory (recently downloaded)
- The
working/Configure/pkgdata
directory (previously installed)
If the installer is not found and a repository is provided, the
installer file will be retrieved from the repository.
The manifest and dependencies are parsed and loaded into their
respective hashes. The pre and post routines are eval'd and
installed as methods for this object.
Returns:
* boolean success
_parseManifest ( $line, $reporter )
Parse the manifest line into the manifest hash.
->{filename}->{ci} Flag if file should be "checked in"
->{filename}->{perms} File permissions
->{filename}->{MD5} MD5 of file (if available)
ObjectMethod
checkDependencies ()
Checks the dependencies listed for this module. Returns two lists, one
of Installed dependencies and one of Missing dependencies. It also returns a
list of Foswiki package names that might be installed and a list of the
CPAN modules that could be installed.