Main Site Contents Up Previous Next

Rules - Custom Script

A custom script can be used to add extra modules, files and shared library dependencies at scan time in a portable way.

The code itself is run under the Perl you are using to run and package your application. It passes information back to the Cava applications using the Cava::Packager::Rule module.

Example:

use strict;
use warnings;
use Cava::Packager::Rule;
my $rules = Cava::Packager::Rule->new;
....
....
....
$rules->add_shared_library( $filename, $fullfilepath  );
cavalog( qq(I added $filename at $fullfilepath));
cavalogwarning('Log A Warning');
cavalogerror('Log an Error');

On Linux and MacOSX you need not be concerned whether you add library files or symlinks or both. Cava Packager will import the correct file and create the correct symlinks.

On MacOSX if you have a rule that adds shared libraries, you will also need to define a MacOSX Framework to make them portable.


Exported Logging Functions

The Cava::Packager::Rule module exports several logging functions into your script namespace. Messages logged using these functions will appear in the Cava log files. When scanning from the Cava Packager GUI the log level used is 4 (info). When using the cavaconsole command line executable, the loglevel can be set using the parameter --loglevel=n.

As you would expect, only messages at or below the current log level will appear in the Cava logs.

cavalog($logmessage);          A synonym for cavalognotice

cavaloginfo($logmessage);      log level 4

cavalognotice($logmessage);    log level 3 (default)

cavalogwarning($logmessage);   log level 2

cavalogerror($logmessage);     log level 1




Exported Utility Functions


IsWindows

IsMac

IsLinux



Rule Object Utility Methods


stashvalue

my $value = $rule->stashvalue($valuename, [ $newvalue ]);

Each Custom Script for each module is run in isolation. This method allows you to save any value against a hash key. This value will then be available for use by any other custom script that runs during the current scan. This can be useful if the scripts for several different modules have to carry out the same process. You can store the result from the first script that runs during the scan and use the value in subsequent scripts that may need that value.

Please note that you cannot predict which order custom scripts will be run in so you should account for that when storing and retrieving stashed values. You can use a custom script for the Cava::Global module to set global values as the custom rule for Cava::Global is always the first thing to run in a scan.

get_module_name

my $modulename = $rule->get_module_name();

This method returns the module name for which the current script is running.

get_module_key

my $modulekey = $rule->get_module_key();

This method returns the module key of the modules for which the current script is running. For example, the module named My::Module::TypeOne has a module key of My/Module/TypeOne.pm.

get_module_inc

my $incpath = $rule->get_module_inc();

This method returns the directory from which the current module will be loaded. For example:

Module Name = My::Module::TypeOne

Module Key = My/Module/TypeOne.pm

Module Path = /home/me/CitrusPerl/x86/5-12/site/lib/My/Module/TypeOne.pm

$incpath = /home/me/CitrusPerl/x86/5-12/site/lib

get_module_autodir

my $autodir = $rule->get_module_autodir();

This method returns the directory for the current module autofiles (if any). For example:

Module Name = My::Module::TypeOne

Module Key = My/Module/TypeOne.pm

Module Path = /home/me/CitrusPerl/x86/5-12/site/lib/My/Module/TypeOne.pm

$autodir = /home/me/CitrusPerl/x86/5-12/site/lib/auto/My/Module/TypeOne

get_module_xslibrary

my $xslibpath = $rule->get_module_xslibrary();

This method returns the xs file for the current module(if any). For example:

Module Name = My::Module::TypeOne

Module Key = My/Module/TypeOne.pm

Module Path = /home/me/CitrusPerl/x86/5-12/site/lib/My/Module/TypeOne.pm

$xslibpath = /home/me/CitrusPerl/x86/5-12/site/lib/auto/My/Module/TypeOne/TypeOne.so

The method will return undef if there is no xs file.

get_dependent_library

my $libpath = $rule->get_dependent_library($libprefix);

If the current module has an xs library, this method will return the full path to the first dependent library that matches $libprefix

For example, My::Module::TypeOne has an xs library which loads a shared library libmyshared. We do not know if our actual dependency is libmyshared.so or libmyshared.so.5 etc. If we call:

my $libpath = $rule->get_dependent_library('libmyshared');

The rule engine will load My::Module::TypeOne, check all the shared libraries loaded and return the path to the first one that matches /^libmyshared/.

get_dependent_library_dir

my $libdir = $rule->get_dependent_library_dir($libprefix);

This method works in exacly the same was as get_dependent_library except that it returns the directory the library was found in rather than the full path to the library.


Alter Scan Methods


These methods allow you to alter the scan rules dynamically at scan run time.

add_shared_library

$rule->add_shared_library($libname, $libpath);

This method allows you to add additional shared libraries required by the current module.

For example, to add 'libmyname.so.3' from '/usr/lib/libmyname.so.3':

$rule->add_shared_library('libmyname.so.3','/usr/lib/libmyname.so.3');

You may find it simpler in practice to use the method add_shared_library_path

add_shared_library_path

$rule->add_shared_library_path($libpath);

This method allows you to add additional shared libraries required by the current module.

For example, to add '/usr/lib/libmyname.so.3':

$rule->add_shared_library_path('/usr/lib/libmyname.so.3');

Commonly this would be used with the utility method get_dependent_library.

For example:

my $libpath = $rule->get_dependent_library('libexpat');
$rule->add_shared_library_path($libpath) if $libpath;

add_module

$rule->add_module($modulename);

Use this method to add extra modules to the current scan.

add_perlfile

$rule->add_perlfile($filekey);

Use this method to add Perl files to the current scan. Note that filekey must be a relative path that can be found by traversing the current @INC.

add_datafile

$rule->add_datafile($filekey);

Use this method to add data files to the current scan. Note that filekey must be a relative path that can be found by traversing the current @INC.

add_perlslurp

$rule->add_perlslurp($dirkey, $level);

Use this method to add additional directories to be 'slurped' for modules and Perl files during the current scan. Note that dirkey must be a relative path that can be found by traversing the current @INC.

Level can be a number from 1 - 5 that dictates the number of directory levels to slurp. You can also specify -1 to indicate that all directory levels should be slurped. Specifying 0 removes any slurp action. You might specify 0 if some other value was hard coded by the standard rule and you wished to dynamically switch this off.

add_dataslurp

$rule->add_dataslurp($dirkey, $level);

Use this method to add additional directories to be 'slurped' for data files during the current scan. Note that dirkey must be a relative path that can be found by traversing the current @INC.

Level can be a number from 1 - 5 that dictates the number of directory levels to slurp. You can also specify -1 to indicate that all directory levels should be slurped. Specifying 0 removes any slurp action. You might specify 0 if some other value was hard coded by the standard rule and you wished to dynamically switch this off.

set_submodules_slurp

$rule->set_submodules_slurp($level);

Use this method to cause directories below the directory for the current module to be 'slurped' for Perl files and modules during the current scan. Level can be a number from 1 - 5 that dictates the number of directory levels to slurp. You can also specify -1 to indicate that all directory levels should be slurped. Specifying 0 removes any slurp action. You might specify 0 if some other value was hard coded by the standard rule and you wished to dynamically switch this off.

set_location_standard

$rule->set_location_standard();

The default location for all packaged modules and Perl files is the Virtual @INC. You can dynamically change the packaged location for the current module to Standard @INC by calling this method.

set_code_plaintext

$rule->set_code_plaintext();

By default, all packaged modules and Perl files are stored as masked text. You can dynamically change this to plain text for the current module by calling this method.

set_preserve_tree

$rule->set_preserve_tree();

Call this method to force this module and all sub modules ( modules in directories below this ) to be packaged in the Standard @INC. You may wish to do this if the module searches for submodules by traversing @INC.

Note that calling this method alone will not cause additional modules to be packaged; it merely dictates how any that are scanned will be packaged. To force inclusion of all submodules, call method set_submodules_slurp in addition to this method.





Contents Up Previous Next


Cava Packager Copyright © 2006-2012 Mark Dootson