/ 
CatalystX-Usul-0.6.1167
/ CatalystX::Usul::Build

Name

CatalystX::Usul::Build - M::B subclass

Version

This document describes CatalystX::Usul::Build version 0.6.$Revision: 1165 $

Synopsis

use CatalystX::Usul::Build;
use MRO::Compat;

my $builder = q(CatalystX::Usul::Build);
my $class   = $builder->subclass( class => 'Bob', code  => <<'EOB' );

sub ACTION_instal { # Spelling mistake intentional
   my $self = shift;

   $self->next::method();

   # Your application specific post installation code goes here

   return;
}
EOB

Description

Subclasses Module::Build. Ask questions during the install phase. The answers to the questions determine where the application will be installed and which additional actions will take place. Should be generic enough for any web application

ACTIONS

ACTION_build

Prompts the user for information about how this installation is to be performed. User responses are saved to the build.xml file. The "config_attributes" method returns the list of questions to ask

ACTION_change_version

_change_version

Changes the $VERSION strings in all of the projects files

ACTION_distmeta

distmeta

Updates license file and changelog

ACTION_install

install

Optionally calls the ACTION_install method in Module::Build

Next it performs the additional sequence of actions required to install the application. The "actions" method returns the list of additional steps required

ACTION_install_local_cpanm

Install a copy of App::cpanminus to the local lib

ACTION_install_local_deps

Install the applications dependencies to the local lib

ACTION_install_local_lib

Bootstrap a copy of local::lib into the project directory

ACTION_install_local_perl

Install a version of Perl using perlbrew to the local lib

ACTION_install_local_perlbrew

Install a copy of perlbrew to the local lib

ACTION_local_archive

_local_archive

Create a tarball (in the parent of the project directory, the one with Build.PL in it). Contains the local lib built by the "_install_local_deps" action

ACTION_prereq_diff

_prereq_diff

Generates a report of dependencies used by the module. It is presented as three lists; a list of modules that you might want to add to the target list in Build.PL, a list of modules you might want to remove from Build.PL, and a list modules whose versions should be updated in Build.PL. The target list defaults to requires and can be changed to build_requires or configure_requires on the command line

ACTION_release

release

Commits the current working copy as the next release

ACTION_restore_local_archive

_restore_local_archive

Unpack the tarball created by "_local_archive"

ACTION_standalone

Create a local lib directory, populate it with dependencies and then include it in the application distribution

ACTION_uninstall

Removes the HTTP server deployment links. Deletes the database. Deletes the owner id and the two groups that were created when the application was installed. Does not delete the application files and directories

ACTION_upload

upload

Upload distribution to CPAN

Subroutines/Methods

actions

$current_list_of_actions = $builder->actions( $new_list_of_actions );

This accessor/mutator method defaults to the list defined in the $CONFIG{actions} package variable

cli

$cli = $builder->cli;

Returns an instance of CatalystX::Usul::Programs, the command line interface object

config_attributes

$current_list_of_attrs = $builder->config_attributes( $new_list_of_attrs );

This accessor/mutator method defaults to the list defined in the $CONFIG{attrs} package variable

dispatch

$builder->dispatch( @_ );

Intercept the call to parent method and call "_setup_plugins" first

dist_description

$builder->dist_description;

Returns the description section from the POD in the main application class

make_tarball

$builder->make_tarball( $dir, $archive );

Prepends updir to the file name and calls make_tarball. The $archive defaults to $dir

patch_file

$builder->patch_file( $path, $patch );

Apply a patch to the specified file

process_files

$builder->process_files( $source, $destination );

Handles the processing of files other than library modules and programs. Uses the Bob::skip_pattern defined in the subclass to select only those files that should be processed. Copies files from source to destination, creating the destination directories as required. Source can be a single file or a directory. The destination is optional and defaults to blib

process_local_files

$builder->process_local_files();

Causes the local lib to be copied to blib during the build process

public_repository

Return the URI of the VCS repository for this project. Return undef if we are not using svn or the repository is a local file path

repository

Returns the URI of the VCS repository for this project

skip_pattern

$regexp = $builder->skip_pattern( $new_regexp );

Accessor/mutator method. Used by "_copy_file" to skip processing files that match this pattern. Set to false to not have a skip list

Questions

All question methods are passed $config and return the new value for one of it's attributes

q_built

Always returns true. This dummy question is used to trigger the suppression of any further questions once the build phase is complete

q_install

Should we execute the Module::Build install method. Answer no if the distribution tarball was unpacked into the directory where the application is going to be executed from, e.g. one's home directory for non-root installations

q_path_prefix

Prompt for the installation prefix. The application name and version directory are automatically appended. All of the application will be installed to this path. The default is /opt

q_phase

The phase number represents the reason for the installation. It is encoded into the name of the application home directory. At runtime the application will load some configuration data that is dependent upon this value

q_post_install

Prompt for permission to execute the post installation commands

q_ver

Dummy question returns the version part of the installation directory

Actions

All action methods are passed $config

copy_files

Copies files as defined in the $config->{copy_files} attribute. Each item in this list is a hash ref containing from and to keys

create_dirs

Create the directory paths specified in the list $config->{create_dirs} if they do not exist

create_files

Create the files specified in the list $config->{create_files} if they do not exist

edit_files

Edit the path that points to the application install directory in /etc/default/{app-name}. Edit the same path in the {prefix}_admin program which runs setuid root. Hence taint mode is on and it cannot aquire the path

Creates some symbolic links

Private Methods

_ask_questions

$config = $builder->_ask_questions( $config );

Called from the "ACTION_install" method. Writes the $config hash to file for later use by the post install commands

_commit_release

$builder->_commit_release( 'Release message for VCS log' );

Commits the release to the VCS

_copy_file

$builder->_copy_file( $source, $destination );

Called by "process_files". Copies the $source file to the $destination directory

_cpan_upload

$builder->_cpan_upload;

Called by "ACTION_upload". Uses CPAN::Uploader (which it loads on demand) to do the lifting. Reads from the users .pause in their $ENV{HOME} directory

_get_config

$config = $builder->_get_config( $config_hash_ref );

Will merge the Module::Build notes hash with the passed config hash ref and the %CONFIG hash in. Caches the result

_log_info

$builder->_log_info( @list_of_messages );

Add newlines to the messages before calling parent method

_set_base_path

$base = $builder->_set_base_path( $config );

Sets the Module::Build install_base attribute to the base directory for this installation. Returns that path. Also sets; bin, lib, and var directory paths as appropriate. Called from the "ACTION_install" method

_setup_plugins

$builder->_setup_plugins

Loads any plugins it finds in the CX::U::Plugin::Build namespace. The $builder-config> setup_plugins attribute is passed to setup_plugins

_update_changelog

$builder->_update_changelog( $config, $version );

Update the version number and date/time stamp in the Changes file

Diagnostics

None

Configuration and Environment

Stores config information in the file var/etc/cli.xml

Dependencies

CatalystX::Usul::Programs
Module::Build
SVN::Class

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to the address below. Patches are welcome

Author

Peter Flanigan, <Support at RoxSoft.co.uk>

License and Copyright

Copyright (c) 2011 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE