NAME

Makefile.PL - Koha packager and installer

SYNOPSIS

BASIC INSTALLATION

    perl Makefile.PL
    make
    make test
    sudo make install

UPGRADE INSTALLATION

    NOTE: This option is only available if koha-install-log exists.

    perl Makefile.PL --prev-install-log /path/to/koha-install-log

    make
    make test
    sudo make upgrade

PACKAGING RELEASE TARBALLS

    make manifest tardist
    make manifest zipdist

CLEANING UP

        make clean

DESCRIPTION

This is a packager and installer that uses ExtUtils::MakeMaker, which is fairly common on perl systems. As well as building tar or zip files and installing with the above commands, it allows us to check pre-requisites and generate configuration files.

VARIABLES

NAME, VERSION_FROM, ABSTRACT, AUTHOR

Basic metadata about this software.

NO_META

Suppress generation of META.yml file.

PREREQ_PM

Hash of perl modules and versions required.

PM

Hash of file mappings

PL_FILES

This is a hash of PL scripts to run after installation and the files to ask them to generate. Maybe use the values from CONFIGURE to generate initial configuration files in future.

target_map

This is a hash mapping directories and files in the source tree to installation target directories. The rules for this mapping are:

If a directory or file is specified, it and its contents will be copied to the installation target directory.
If a subdirectory of a mapped directory is specified, its target overrides the parent's target for that subdirectory.
The value of each map entry may either be a scalar containing one target or a reference to a hash containing 'target' and 'trimdir' keys.
Any files at the top level of the source tree that are not included in the map will not be installed.
Any directories at the top level of the source tree that are not included in the map will be installed in INTRANET_CGI_DIR. This is a sensible default given the current organization of the source tree, but (FIXME) it would be better to reorganize the source tree to better match the installation system, to allow adding new directories without having to adjust Makefile.PL each time. The idea is to make the $target_map hash as minimal as possible.

The permitted installation targets are:

INTRANET_CGI_DIR: CGI scripts for intranet (staff) interface.
INTRANET_TMPL_DIR: HTML templates for the intranet interface.
INTRANET_WWW_DIR: HTML files, images, etc. for DocumentRoot for the intranet interface.
OPAC_CGI_DIR: CGI scripts for OPAC (public) interface.
OPAC_TMPL_DIR: HTML templates for the OPAC interface.
OPAC_WWW_DIR: HTML files, images, etc. for DocumentRoot for the OPAC interface.
PERL_MODULE_DIR: Perl modules (at present just the C4 modules) that are intimately tied to Koha. Depending on the installation options, these may or may not be installed one of the standard directories in Perl's default @LIB.
KOHA_CONF_DIR: Directory for Koha configuration files.
ZEBRA_CONF_DIR: Directory for Zebra configuration files.
ZEBRA_LOCK_DIR: Directory for Zebra's lock files.
ZEBRA_DATA_DIR: Directory for Zebra's data files.
ZEBRA_RUN_DIR: Directory for Zebra's UNIX-domain sockets.
MISC_DIR: Directory for for miscellaenous scripts, among other things the translation toolkit and RSS feed tools.
SCRIPT_DIR: Directory for command-line scripts and daemons to be set up all for installation modes.
SCRIPT_NONDEV_DIR: Directory for command-line scripts that should be installed in the same directory as the SCRIPT_DIR target except 'dev' installs.
MAN_DIR: Directory for man pages created from POD -- will mostly contain information of interest to Koha developers.
DOC_DIR: Directory for Koha documentation accessed from the command-line, e.g., READMEs.
LOG_DIR: Directory for Apache and Zebra logs produced by Koha.
BACKUP_DIR: Directory for backup files produced by Koha.
PLUGINS_DIR: Directory for external Koha plugins.
PAZPAR2_CONF_DIR: Directory for PazPar2 configuration files.
NONE: This is a dummy target used to explicitly state that a given file or directory is not to be installed. This is used either for parts of the installer itself or for development tools that are not applicable to a production installation.

CONFIGURATION OPTIONS

The following configuration options are used by the installer.

INSTALL_MODE: Specifies whether installation will be FHS-compliant (default, assumes user has root), put everything under a single directory (for users installing on a web host that allows CGI scripts and a MySQL database but not root access), or development (for a developer who wants to run Koha from a git clone with no fuss).
INSTALL_BASE: Directory under which most components will go. Default value will vary depending on INSTALL_MODE.
DB_TYPE: Type of DBMS (e.g., mysql or Pg).
DB_HOST: Name of DBMS server.
DB_PORT: Port that DBMS server is listening on.
DB_NAME: Name of the DBMS database for Koha.
DB_USER: Name of DBMS user account for Koha's database.
DB_PASS: Pasword of DMBS user account for Koha's database.
ZEBRA_MARC_FORMAT: Specifies format of MARC records to be indexed by Zebra.
ZEBRA_LANGUAGE: Specifies primary language of records that will be indexed by Zebra.
ZEBRA_USER: Internal Zebra user account for the index.
ZEBRA_PASS: Internal Zebra user account's password.
KOHA_USER: System user account that will own Koha's files.
KOHA_GROUP: System group that will own Koha's files.

FUNCTIONS

hashdir

This function recurses through the directory structure and builds a hash of hashes containing the structure with arrays holding filenames. This directory hashing routine was taken from BrowserUK @ http://www.perlmonks.org/?node_id=219919

get_file_map

This function combines the target_map and file hash to map each source file to its destination relative to the set of installation targets.

Output will be a hash mapping from each source file to its destination value, like this:

'mainpage.pl' => '$(INTRANET_CGI_DIR)/mainpage.pl'

AUTHORS

MJ Ray mjr at phonecoop.coop Galen Charlton galen.charlton at liblime.com