internal package Foswiki::Configure::Package

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::Configure::Package is a Foswiki::Configure::Visitor

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.