- NAME
- SYNOPSIS
- DESCRIPTION

- Creating a new GT::Installer object
- add_config - Adding configuration options.
- add_config_message - Add a configuration message.
- install_exit_message - Add an exit message for installs.
- install_to - Specify where to untar files to.
- use_lib - Set the use lib path for addition to all .pl and .cgi files.
- replace_path - Generic method to replace paths upon install
- add_upgrade - Adding upgrade options.

- COPYRIGHT
- VERSION

# NAME

GT::Installer - Performs initial installs for GTI products

# SYNOPSIS

        main();

        sub main {
            my $format = 'scroll1';
            my $installer = GT::Installer->new(
                product        => 'Gossamer Mail',
                version        => '2.0.0 beta 1',
                load_defaults  => \&load_defaults,
                load_config    => \&load_config,
                save_config    => \&save_config,
                checksums      => "<%Data Path%>/admin/checksums",
                welcome_format => $format
            );

            $installer->add_config_message(q|
        This should be the system path and url (start with http://)
        to the directory where your admin files are. No trailing
        slash please.|, $format);

            $installer->add_config(
                type     => 'path',
                key      => "Admin Path",
                message  => 'Admin Path',
            );
        }
        # Regex to path keys. These regexs have to capture
        # the file in $1
            $installer->install_to(
                '^admin/(.*)$'  => 'Admin Path',
                '^user/(.*)$'   => 'User Path',
                '^batch/(.*)$'  => 'Batch Path',
                '^data/(.*)$'   => 'Data Path',
                '^images/(.*)$' => 'Images Path',
            );

            $installer->add_upgrade(
                message         => 'Program Files. e.g. .pm, .pl and .cgi files',
                file_list       => '\.(?:pl|cgi|pm)$'
            );
            $installer->add_upgrade(skip => 'ConfigData\.pm$');
            $installer->perform;
        }

# DESCRIPTION

GT::Installer is an installer class for all Gossamer Threads products. It will handle both a command line interface and a CGI inteface.

All intallation directives are specified at the start and are called for each CGI request if being ran in CGI mode.

## Creating a new GT::Installer object

There are several options when creating a new GT::Installer object. All options are in the form of key value pairs. The options can be passed in as a flattened hash or as a hash reference.

There are two options that must be specified. These are product and version. All other options are optional.

There are two ways to get a GT::SQL object. First, you can simply provide the path to the def file directory where GT::SQL stores all it's information:

        $db = new GT::SQL '/path/to/def';

or you can pass in a hash or hash ref and specify options:

        $db = new GT::SQL {
                            def_path => '/path/to/def',
                            cache    => 1,
                            debug    => 1,
                            subclass => 1
                        );

You must specify def_path. Setting cache => 1, will result in all table or relation objects to be cached which can improve performance.

Setting subclass => 0 or subclass => 1 will enable or disable the ability to subclass any of the objects GT::SQL creates. The default behaviour is 1.

GT::SQL has advanced debugging, and setting it to 1 should be adequate for most operations.

product
  Specifies the name of the product. This name is used in the welcome message and in various parts of the dialogue.

          product => 'Gossamer Mail'

version
  This is the version of the product. It is used on the startup screen to tell the user what version we are installing or upgrading to.

          version => '2.0.0 beta 1'

load_defaults
  This is a code reference that is called when installing. It is used to defaults for prompts you have set up. The only argument to this code reference if the installer object which has method to assist in setting up defaults for the different configuration options that you would specify.

  If you return false from this code reference the error is expected to be in GT::Installer::error. GT::Installer inherets from GT::Base so you can just call the error method on the object and return it to achieve this.

          load_defaults => \&load_defaults

load_config
  This is another code reference. It is called when the user specifies that they are doing an upgrade. The argument to this callback is the installer object. The path to the admin directory of the last install is a key in the installer object admin_path. In this code reference you will need to correlate all the config option keys to the values in your config file. See the example included in this pod for a possible why to do this.

          load_config => \&load_config

  If you return false from this code reference the error is expected to be in GT::Installer::error. GT::Installer inherets from GT::Base so you can just call the error method on the object and return it to achieve this.

save_config
  This is a code reference that is called after an install or upgrade. It gives you the opertunity to save any user input into there new/old config file.

          save_config => \&save_config

checksums
  This should be set to the full system path to the checksum file. If this is not set checksums will not be used, which makes the upgrade questions usless and all files will be overridden. There is no possible way you can know the full path to this file at the point you set it. You can specify tags in this path that will get replaced with what the user entered. The tags are similar to the GT::Template manpage tags in that they start with &lt;% and end with %&gt;. No other the GT::Template manpage tags conventions are used.

          checksums => "<%Data Path%>/admin/checksums"

welcome_format
  This is the welcome format. There are named formats that are used in GT::Installer for most command line output. This is the one that is used for the initial message. This is not used in CGI mode.

  There are currently 4 formats (more to come :)). There are:

scroll1

           _________________________________________________________________
          /\                                                                \
          \_|                                                                |
            |                                                                |
            | This is the scroll1 format                                     |
            |  ______________________________________________________________|_
            \_/_______________________________________________________________/

scroll2

           __^__                                                                __^__
          ( ___ )--------------------------------------------------------------( ___ )
           | / |                                                                | \ |
           | / | This is the scroll2 format                                     | \ |
           |___|                                                                |___|
          (_____)--------------------------------------------------------------(_____)

professional

           #================================================================#
           =                                                                =
           =  This is the professional format                               =
           #================================================================#

none
  This format just performs line wraps. Has no outline :(

## add_config - Adding configuration options.

There are 3 methods for adding user prompts. When I say user promts I mean that in the telnet sence, in CGI mode it is just a table row.

This is the method you will be calling for every install option the user should specify. This method takes it's arguments as key value pair. The arguments can either be in the form of a flatened hash or a hash reference.

        $installer->add_config(
            type            => 'url',
            key             => "Admin URL",
            message         => 'Admin URL',
            telnet_callback => \&telnet_callback,
        );

Each key in the hash defines an attribute of the user prompt.

type
  The type attribute should be one of the built in input types. There is currently no way to specify your own type. If this becomes a problem it will be added. The built in types are as follows.

          url           - User specifies a URL.
          ftp           - User specifies an FTP URL.
          path          - User specifies a Path to something on the system.
          message       - This is the same as calling the add_config_message
                          method.
          create_dirs   - This is a yes/no answer on weather the user wants the
                          directories for this install created.
          email         - User specifies and email address. This is commonly
                          used to prompt for the admin email address.
          reg_number    - User specifies the registration number they recieved
                          from us when they paid for the product.
          email_support - Specify either the path to sendmail or the hostname
                          of an smtp server. What is specified with be in the
                          config hash as email_support. The key default for
                          this option is Mailer.
          perl_path     - Specify the path to perl on this system.

key
  Each item the user enters is stored in a hash in the installer object. This hash is called config. This specifies the key used in that hash to store this user option.

  This key is also used at the end of the telnet install to display the options the user has specified for the install.

  You will be accessing these keys in your configuration callbacks to either set defaults or save the user specified options in your config file. See the complete example below to see how this is used.

message
  This is the message the user is pompted with in telnet. From the with this appears on the left of the form the user fills out.

  This will default to the value of the key if not specified

telnet_callback
  This is a code reference that, if specified, will be ran after the user enteres the information. You can use this to tweek the other option defaults. If this method returns false the user will be reprompted for the information. So you can effectivly use this to validate command line input.

## add_config_message - Add a configuration message.

This is a method to add a configuration message. This message is displayed to the user in telnet in the order you specify it. No prompt is performed for these messages.

This is a shortcut function that is the same as specifing:

        $installer->add_config(
            type    => 'message',
            message => 'This message is displayed to the user',
            format  => 'none'
        );

The arguments to this function are (message, format). Message is what is displayed, format is the format used. See above for a list of formats.

        $installer->add_config_message(q|My configuration message.|, 'professional');

## install_exit_message - Add an exit message for installs.

This is the message that is displayed after the installation is complete. This message uses the same convention for tags as the checksum option for the constructor method. Any keys that are set during the install will be available as tags here. The second argument to this method is an optional format (used in telnet see above).

        $installer->install_exit_message(q|
        To run the setup, point your browser to:
        <a href="<%Admin URL%>/admin.cgi"><%Admin URL%>/admin.cgi</a>
        |, 'scroll2');

## install_to - Specify where to untar files to.

The way this options is specified is a bit strange and my be rewritten. It takes it arguments as a hash of regular expressions to keys. The keys are the keys you specified with add_config(). The regexs are matched against the relative path in the tar file. Anything captured in $1 is appended to the value the user entered for that regexs key. For example is you specify a key Admin Path such as

        $installer->add_config(
            type  => 'path',
            key   => 'Admin Path'
        );

You could then use the key like:

        $installer->install_to(
            '^admin/(.*)' => 'Admin Path'
        );

This would replace admin/ in the relative path in the tar file with what the user entered for the Admin Path prompt.

## use_lib - Set the use lib path for addition to all .pl and .cgi files.

The argument to this should be a key specified with add_config(). The path the user entered for that config is added to all .cgi and .pl files in a use lib '' statement. Followig the example above:

        $installer->use_lib('Admin Path');

All .cgi and .pl file in the install will now have

        use lib '/home/bline/projects/library';

added to them assuming the path the user entered for that config option was /home/bline/projects/library'.

You can set $GT::Installer::USE_LIB_SPACES to something other than the default 4 spaces to alter the number of spaces that will be put before the ``use lib''. Please be careful - if you set this to something other than whitespace you are asking for trouble or being an 1337 h4xx0r.

## replace_path - Generic method to replace paths upon install

The argument should be a hash of key => value replacements that should be made upon installation.

        $installer->replace_path(
            '../private/ConfigData.pm' => '<%Private_Path%>/ConfigData.pm'
        );

This will replace all occurrences of ../private/ConfigData.pm with what the user entered in <%Private_Path%>.

## add_upgrade - Adding upgrade options.

This is a method for grouping files and or directories under user prompted upgrade options. This is NOT designed to be a complete upgrade system. It handled basic checksuming, overwrites and backup. This should probably not be used for a major upgrade.

more to come...

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Installer.pm,v 1.93 2005/03/27 20:52:53 jagerman Exp $