CPAN Compatibility

This is a starting proposal; please modify and update.

Packaging and installation strategy

The Foswiki project shall consist of one CPAN package for the core Foswiki distribution, and separate packages for each extension, or each bundle of logically-related extensions.

For the core package, the makefile / Build script created by the Makefile.PL/Build.PL script shall install the Foswiki application, other than the lib/ directory, to a user-specified location (denote this as the "master copy"). The Perl modules shall be installed to the Perl library directory specified as part of the execution of Makefile.PL/Build.PL.

A deployment script (updated as part of the Perl install process to know the master copy location) shall be given a directory location within a web server's document root, and it will setup the appropriate files and subdirectories in this location.* The script shall support writing the necessary configuration files for supported web servers (e.g. .htaccess files). For fresh installs, the script shall require an initial password to protect the configure web interface. The script shall also require a directory location to store a per-instance copy of the files in the master copy directory. This will allow for more than one instance of Foswiki to be running on the same web server, and makes it easier to support upgrades to new versions (either patches or full version upgrades): the Perl install is solely responsible for putting a master copy in place, and the deployment script is responsible for deploying a copy of these files to a specific Foswiki instance.

*The deployment script can handle OS-specific issues, such as putting in place appropriate command file wrappers for installations on Windows.

Extension packages shall follow a similar installation process as for the core package. The basic Perl install shall install modules to the specified Perl library directory and other files to the master copy location. An installation script shall perform any additional required configuration and install the required files into the directory for a specific Foswiki instance.

Documentation for extension developers

With the process for CPAN packaging being a bit complex, it may be useful to have skeleton extensions for each different type (such as plugins and skins) and cookbook examples of the whole end-to-end process: developing the extension, writing the deployment script, creating the CPAN package (including the Makefile.PL or Build.PL script), and getting it into CPAN. (Existing CPAN documentation can be used for interacting with CPAN, and for the non-Foswiki-specific steps for creating a package.)
Topic revision: r1 - 09 Nov 2008, IsaacLin
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy