cmwpkginst

NAME

cmwpkginst - Communiware packages installator

SYNOPSIS

cmwpkginst [options]

cmwpkginst [options] directory

cmwpkginst [options] archive

cmwpkginst -h

DESCRIPTION

This script intended for Communiware packages installation. Where to look for package source files depends on command line argument. If there are no arguments script accumes that current directory is package root directopry. It is possible also give as an argument name of package archive file. It must have name like Perl package files: (.+-\d+\.\d+)\.tar\.gz. cmwpkginst unpacks this archive in the current directory and does chdir to it.

After packege sources are fount cmwpkginst builds Makefile and executes make deploy command for building and installing the pachage as well as for needed database upgrading.

Options

-h
Prints short help and exits.

-c conffile
Sets alternate location of used Communiware config file. Without this option file CMWHOME/conf/cmw.conf is used.

-l libdir
Tells where Communiware perl library is placed. By default the script looks for the library ``near'' used config file or in CMWHOME/perllib directory.

-n
By default cmwpkginst builds Makefile and immediately executes make deploy command. The -n option suppresses such subsequent make call, script builds Makefile and exits.

Goals in built Makefile

After Makefile is successfully built it contains the following main goals.

all (default goal)
To do file preprocessing and some additional actions. After make all Communiware package is ready to install.

install_package
To install package files into proper places. This action may require superuser rights, so it may ask about used OS command for sudo-ing.

database
Builds or re-builds Communiware database objects are contained in package. See below about possible kinds of datafile processing. make database causes loading database objects into database if there are no previous version of the same package installed. Otherwise this goal performs database updating.

test
This goal performs package testing - the same way as for Perl packages it executes all t/*.t scripts in package distribution. Pay attention: in difference with Perl packages testing of Communiware packages must be performed after the package is successfully installed.

deploy
The ``very main'' goal. It includes consequent execution of goals all, install_package, database and test. make deploy runs automatically by cmwpkginst after Makefile building if -n option is not present.

clean_package
Cleans all created temporary files except Makefile which is renamed to Makefile.old. Be attentive! You should use <clean_package>, not just clean goal.

The package ExtUtils::MakeMaker is used for building Makefile, so this Makefile contains ``usual'' for Perl packages goals such as dist, distcheck and other (see ExtUtils::MakeMaker man for details).

COMMUNIWARE PACKAGES

Packages purpose

Communiware package (just ``package'' below) is a set of Communiware system components for realizing some functionality. It may contain the following kinds of components:

  • Perl packages from Communiware hyerarchy.

  • Command-line utilites (bin-files).

  • System utilites (sbin-files).

  • Communiware scripts.

  • SQL-scripts intended for creation some objects in Communiware database (probably different for different SQL-servers).

  • Ontology files.

  • Data in load_item utility format (dump-files). There are two possible kinds of this data: ``simple'' when the file contains dump of several items and ``splitted'' when data about each item are stored in separate file, and list of these files and thier loading order are kept in items.list file.

  • Files with internationalisation messages, in short i18n-files.

  • Files with message translations, in format of load_transl utilite.

Besides the package may change functionality of cmwctl, cmwcronctl and cmwrotatelogs utilites if it contains daemons, cron jobs or generates some logfiles.

At last the package may require some software to be installed.

  • Communiware version not less than some.

  • Another Communiware packages, maybe with versions not less than some.

  • Some third-party software.

  • Perl packages.

Package files and directories

Directories structure

In general package directory structure is like the Communiware one.

bin/
Command line utilites.

sbin/
System utilites.

scripts/
Communiware scripts.

Communiware/ and its subdirectories
Perl packages.

t/
Test scripts.

Database objects

There can be up to three directories contain database objects - init_base, update_base and seed_base. Besides this update_base (if present) has several subdirectories whose names are version numbers. See database objects loading for explaining all these dirs.

Each of these directories may contain following files (we use usual Unix file mask).

  • *.Oracle.*.sql *.Pg.*.sql

    Server-specific SQL-scripts. They are loaded into DB if only current Communiware instance works with ``corresponding'' SQL server.

  • *.sql

    Server-independed SQL-scripts. They are loaded in case of any SQL server.

  • *.xml

    Ontology files in load_mata format.

  • *.dmp

    ``Single'' dump file. It has format suitable for load_item utilite.

  • Subdirectory which contains items.list and charset files.

    This is directory with ``splitted'' item dumps. The rest of files in this dir are dumps (in load_item format) of the set of items, one item in each file. As a rule they have *.dmp names. items.list contains list and loading order of these files (one name per line), and charset file - name of charset in which these dumps are stored, for example koi8-r or windows-1251.

  • *.transl

    Translation files. These files are loaded via load_transl utility. They can be placed in template subdirectories subdirectories only ans must have .transl suffix. There can be no more than one translation file in each template directory.

MANIFEST

This required file contains (name per line) names of all files in the package including MANIFEST itself. An example:

    MANIFEST
    MANIFEST.SKIP
    Makefile.PL
    PkgDef.pm
    bin/util1
    bin/util3.PL
        helpers/helper_name/helper_file.css
        helpers/helper_name/helper_file.js
        helpers/helper_name/helper_file.jpg
    scripts/script1
    sbin/sutil1
    Communiware/Module1.pm
    Communiware/Module2.pm.PL
    seed_base/a.xml
    seed_base/b.xml.PL
    seed_base/aa.dmp
    seed_base/bb.dmp.PL

MANIFEST.SKIP

This optional file contains list (one per line) of Perl regular expressions. Files whose names are matched at least one of these regexps are ignored during make distr and make distcheck.

An example of MANIFEST.SKIP:

    \~$
    CVS
    ^.config$
    ^cmw\.conf$
    \.gz$
    ^Makefile$
    ^Makefile.old$
    ^package.cfg$
    \.#

package.conf.in or package.conf

If package.conf.in is present then package.conf is built from it by preprocessing (see the preprocessing manpage). This file if package description in XML format according to donfig.dtd. This file will be added to main Communiware config file - cmw.conf after package installing.

At least this file must contain package name and version. Also it can contain information about package dependances, daemons, cron jobs etc. See package definition in config.dtd for details.

Here is an example of ``minimal'' package.conf file:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE package SYSTEM "config.dtd">
 <package version="1.2" id="XPiki">
 </package>

PkgDef.pm

Optional file. ``Usual'' Perl package, contains (as a set of Perl variables) information needed for package building. All of these variables are optional.

@CLEANFILES
List of file names which must be deleted during make clean executing. You have not to include in this list preprocessing results (see the preprocessing manpage) as well as temporery files created during make execution.

%REQPERLMOD
Keys of this hashe are names of Perl modules needed for package installation. Values are required version of these modules or 0 if version does not matter.

%REQPROG
This hashe defines external programms needed for package. Keys are names of executables which must exist somewhere in PATH, values are names of options in Communiware config file. These names can be used during file preprocessing (see the preprocessing manpage).

For example if the package requires gnuplot program then %REQPROG can contain element

 gnuplot => 'GNUPLOT'

and preprocessed files can contain something about

 system '~~GNUPLOT~~', @args;

or

 system $Commuiware::config{GNUPLOT}, @args;

If there are more than one program in PATH with given name then cmwpkginst asks: which to use.

If there are already such option in config file (for example if any other package required the same GNUPLOT) then such a program is not searced in PATH, an old value is used.

$ADDCHECK
Code reference. This code block can perform any additional checks before package installation. It must call die if checks are unsuccessful.

An example of PkgDef.pm:

        === example starts ===
        package PkgDef;
        @CLEANFILES = qw(tmpfile1 tmpfile2);
        %REQPERLMOD = (
                Term::ReadKey => 1.25,
                Data::Dumper  => 0
        );
        %REQPROG = (gnuplot => 'GNUPLOT');
        $ADDCHECK = sub {
                die "Cannot read your passwords...\n" unless -r '/etc/master.passwd';
        };
        1;
        === example ends ===

Test scripts

Test scripts must have *.t names and are placed in t package subdirectory. They are usual perl-scripts. See Communiware::TBone and Communiware::TestCase modules info for extended test discussion.

As a rule test scripts are create by createtest utility from dev-site package.

Preprocessing

Package file can be preprocessed before installing. Preprocessing means some change of file text depends on Communiware config file options.

All files with .PL suffix are preprocessed during make all execution. After preprocessing for each *.PL file file with the same name but without .PL suffixwill be created.

Preprocessing is performed by procplfile utility from Communiware distribution. See procplfile manpage for details. Main preprocessing is changing constructions ~~OPTION_NAME~~ to value of this option. For example if .PL file contains ~~BINDIR~~ after preprocessing it can be replaced to /usr/local/communiware/bin.

Database objects loading

Above (Package files and directories) we wrote about package data files. Remember, they can be placed in three directories: init_base, seed_base and update_base and its subdirectories. Here we explain meaning of all these dirs.

There are two main cases during package installation:

  1. We install package first time. In this case all files from init_base and seed_base in alphabetical order of thier base names are loaded. Pay attention: this order does not depend on in which of these two directories file is placed.

    Files from update_base remains untouched.

  2. We do upgrading an old package version. In this case files from update_base subdirs with version numbers greater then an ``old'' package version are loaded, in alphabetical order in each this subdir.

    After this files from seed_base are loaded.

The meaning of word ``load'' here depens on the suffix of loaded file. Dump files (*.dmp) are loaded via load_item, ontology files (*.xml) - via load_meta and SQL-scripts (*.sql) - via sqlplus or psql utilite, depend on used SQL server type.

If loading of any file fails then loading process and make execution stops.

Permissions of installed files

By default package files will have the following permissions after installation:

 bin/*             555
 sbin/*           2555
 scripts/*         555
 Communiware/*/*   444
 i18n/*            444

It is possible to change these default permissions for bin/*, sbin/* and script/* files. For this purpose you must type in second (exactly second!) line of such a file the following:

 # PERM: <perms> <user> <group>

<perms> are needed for installed file permissions. They can set as in chmod utility - in digital or symbolic mode, for example 2755 or -rwxr-xr-x.

<user> and <group> are names of owner and group of installed file. Both of them may be shown as literal string (root) or as a name of config option ($ADMGROUP).

So here is more real example of permission line:

 # PERM: 2755 root $ADMGROUP

Superuser rights during installation

Some actions during package installation may require root permissions. First of all these are bin/*, sbin/* and Communiware/* files installation. As a rule they are installed into root-owned directories, such as a /usr/local/bin.

There is a rule to determine when we need root permissions:

  1. If there are Perl modules (Communiware/* files), bin/*, sbin/* or scripts/* in the installed package.

  2. If there are directories containing thier own Makefiles in the package. If root permissions are not necessary in you should create ``flag'' file named .norootinstall in such directory.

If you need root permission during package installation then program with the name stored in SUDOCOMMAND config file option is used. If there are no such option in config file then you are asked about this program by cmwpkginst. Typical values for this program are su or sudo.

Temporary files

The cmwpkginst script creates some temporary files. All of them are deleted by make clean_package executing. Here we give list of them.

.config
``Dictonary'' of used config options. Is included into created Makefile.

Makefile
The main result of cmwpkginst working. Contains all goals needed for package building and installation.

Makefile.old
This file is the only remainded after make clean_package, this is renamed Makefile.

config.dtd
Symlink to read Document Type Definition file. Needed for correct package.conf parsing.

ENVIRONMENT VARIABLES

MAKE
Sets name of used make programm instead of default ``make'', for example ``gmake''.

16 октябрь 2007 13:45