The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Software-Packager-0.09
River stage zero No dependents
++
/ Software::Packager

NAME

Software::Packager - Common software packaging interface

SYNOPSIS

 use Software::Packager;
 my $packager = new Software::Packager();
 $packager->version('1.2.3.4.5.6');
 $packager->package_name("Somename");
 $packager->program_name('Software Packager');
 $packager->description("This is the description.");
 $packager->short_description("This is a short description.");
 $packager->output_dir("/home/software/packages");
 $packager->category("Applications");
 $packager->architecture("sparc");

 my %object_data = (
    'SOURCE' => '/source/file1',
    'TYPE' => 'file',
    'DESTINATION' => '/usr/local/file1',
    'USER' => 'joe',
    'GROUP' => 'staff',
    'MODE' => '0750',
    );
 $packager->add_item(%object_data);

 my $version = $packager->version();
 my $name = $packager->package_name();
 my $program_name = $packager->program_name();
 my $description = $packager->description();
 my $description = $packager->short_description();
 my $output_directory = $packager->output_dir();
 my $category = $packager->category();
 my $arch = $packager->architecture();

DESCRIPTION

The Software Packager module is designed to provide a common interface for packaging software on any platform. This module does not do the packaging of the software but is merely a wraper around the various software packaging tools already provided with various operating systems.

This module provides the base API and sets default values common to the various software packaging methods.

EXTENDING Software::Packager

To extend the Software::Packager suite all that is required is to create a module that the wraps the desired software packaging system.

FUNCTIONS

new()

 my $packager = new Software::Packager();
 or
 my $packager = new Software::Packager('tar');

This function creates and returns a new Packager object appropriate for the current platform. Optionally the packager type can be passed and the appropriate software packager will be returned.

version()

 $packager->version('1.2.3.4.5.6');
 my $version = $packager->version();

This function sets the version for the package to the passed value. If no value is passed then the packager version is returned.

The version passed must be a number seperated by periods "." and contain at least three parts "1.2.3". since some software packaging products require or can handle longer version numbers the default is for a six part version number "1.2.3.4.5.6".

The version will be set to the value you pass, however not all software packaging products need this many fields or can handle them, so the version applied to the actual software package will be set to the appropriate lengthed value.

Having said this, as a software package creator, you need to know what version is being applied to the package you are creating, right... so after you set the version check what the version will be set to by calling the version method without any arguments to see what is returned.

Example: If we are on AIX, which has a four part version we would get...

 $packager->version('10.2.1');
 my $version = $packager->version();
 print "VERSION: $version\n";
 ...
 VERSION: 10.2.1.0

 or

 $packager->version(1);
 my $version = $packager->version();
 print "VERSION: $version\n";
 ...
 VERSION: 1.1.0.0

Since AIX requires the first two values to be set the second is set to be 1.

For full details on version string requirements refer to the operating system documentation or the documentation for the desired packaging system.

package_name()

 $packager->package_name("Somename");
 my $name = $packager->package_name();

This method sets the package name to the passed value. If no arguments are passed the package name is returned.

Note that some software packaging methods place various limitations on the package name. For example on Solaris the package name is limited to 9 Charaters while the RedHat Package Manager is very strict about the format of the names of the packages it creates.

program_name()

 $packager->program_name('Software Packager');
 my $program_name = $packager->program_name();

This method is used to set the name of the program that the package is installing. This may in some cases be the same as the package name but that is not required.

description()

 $packager->description("This is the description.");
 my $description = $packager->description();

The description method sets the package description to the passed value. If no arguments are passed the package description is returned. It is important to note that some installation package methods limit the length of the description. Therefore it is advisable to check what the description will be set to by calling the method without any arguments.

Example:

 $packager->description("This is a short message.");
 my $description = $packager->descriotion();
 print "DESCRIPTION: $description\n";
 ...
 DESCRIPTION: This is a short message.

short_description()

 $packager->short_description("This is a short description.");
 my $description = $packager->short_description();

The short description is typically a single line that describes the package It is important to note that some installation package methods limit the length of the description. Therefore it is advisable to check what the description will be set to by calling the method without any arguments.

Example:

 $packager->short_description("This is a short message.");
 my $short_description = $packager->short_descriotion();
 print "DESCRIPTION: $short_description\n";
 ...
 DESCRIPTION: This is a short message.

output_dir()

 $packager->output_dir("/home/software/packages");
 my $output_directory = $packager->output_dir();

The output_dir method sets the directory where the final installation package will be placed. The output directory can be set by passing the desired directory to the method. the current outout directory can be checked by calling the method without any arguments.

category()

 $packager->category("Applications");
 my $category = $packager->category();

This method returns or sets the category for the package. Not all packaging systems support categories and so this will only be set where possible.

architecture()

 $packager->architecture("sparc");
 my $arch = $packager->architecture();

This method sets the architecture for the package to the passed value. If no argument is passed then the current architecture is returned.

The default value is the name given the current architecture by the current packaging system.

Not all packaging systems care about architectures and so this will only be used where it is required.

add_item()

 my %object_data = (
    'SOURCE' => '/source/file1',
    'TYPE' => 'file',
    'DESTINATION' => '/usr/local/file1',
    'USER' => 'joe',
    'GROUP' => 'staff',
    'MODE' => '0750',
    );
 $packager->add_item(%object_data);

The add_item method is used to add objects to the software package. By default each object added to the software package must have a unique installation destination, though some packaging systems allow many objects to have the same installation location; with the decision of which object to install happening at install time. This ability is not common to all software packaging systems and thus is only available for systems that support this ability.

The add_item method has some mandatory arguments which are described in the module Software::Packager::Object. The documentation for this module should be consulted if a more detailed explanation of these arguments is required.

 Required arguments:
 TYPE           The type is case insensitive and can be one of:
        File            A standard file.
        Directory       A directory.
        Softlink        A symbolic link.
        Hardlink        A file link.
        Config          A configuration file.
        Volatile        A volatile file.
        Install         An installation file used by the installer.
        InstallDir      A directory to be used by the installer then deleted.
        Pipe            A named pipe.
        Block           A block special device.
        Charater        A Charater special device.
        
        If the type is set to File, Install or Config then the SOURCE value must
        be a real file.
                If the type is a link then both the SOURCE and DESTINATION must
                be present.
 SOURCE         This is the source file to add to the package.
 DESTINATION    The installation destination. This must always be present.

 Optional arguments:
 MODE           The installation permissions. 
 USER           The installation user. Defaults to the current user.
 GROUP          The installation group. Default is the current users primary
                group.

prerequisites()

 $packager->prerequisites('/usr/bin/perl');
 $icon = $packager->prerequisites();

This function returns or sets the prerequisites for this package. since prerequisites can be handled in so many ways it is best to see the documentation in the various packaging system modules. Not all packaging systems can or do use prerequisites and so they will only be used where they are supported.

icon()

 $packager->icon('/source/icon.png');
 $icon = $packager->icon();

This function returns or sets the icon file name for the package. Not all packaging systems use icons and so this will only be used where the use of icons are supported.

vendor()

 $packager->vendor('Gondwanatech');
 my $vendor = $packager->vendor();

This method is used to specify the vendor of the software package. This is the name of the company or organisation that is creating the software package.

email_contact()

 $packager->email_contact('rbdavison@cpan.org');
 my $email = $packager->email_contact();

This function sets or returns the email address for the package contact. Typicaly this will be the person / mail list where help with the software can be sort.

creator()

 $packager->creator('R Bernard Davison');
 my $creator = $packager->creator();

This set the name of the person who created the software package.

install_dir()

 $packager->install_dir('/usr/local');
 my $base_dir = $packager->install_dir();

This method sets the base directory for the software to be installed.

tmp_dir()

 $packager->tmp_dir('/tmp');
 my $tmp_dir = $packager->tmp_dir();

This method returns or sets the temporary build directory to be used for package creation. This directory is used for any preparation that is needed to make the package. This directory should be on a partition with sufficient disk space to hold all temporary objects for the package creation process.

copyright()

This method sets the copyright type for the package. This can either be a file that contains the copyright, The copyright type or the copy information itself

As many packaging systems treat copyright information it is wise to check with the various Software::Packager modules to see how they are treated.

reboot_required()

$packager->reboot_required(0); $packager->reboot_required(1);

This method specifies wether a reboot of the operating system is required after the installation is complete. If set to a true value then any package create will request a reboot after installation.

homepage()

This method sets the home page for the package. This is a URL for a web site that is for the software being released.

package()

This method forms part of the base API it should be overriden by sub classes of Software::Packager

SEE ALSO

 Software::Packager::Object

AUTHOR

 Bernard Davison <rbdavison@cpan.org>

HOMEPAGE

 http://bernard.gondwana.com.au

COPYRIGHT

 Copyright (c) 2001 Gondwanatech. All rights reserved.
 This program is free software; you can redistribute it and/or modify it under
 the same terms as Perl itself.