Perl Interface

Starting with version 2.5.3, Amanda ships with a Perl interface to the core, and with an increasing proportion of the core itself written in Perl.

Modules

All Amanda modules have the prefix Amanda::. The specific modules correspond loosely to C modules of the same name; for example, the contents of device.h are available in Amanda::Device. The modules are not installed in Perl's default search path, but are located by default at $prefix/lib/amanda/perl.

All Amanda modules contain POD, plain old documentation, that is readable via the perldoc command, e.g.,

perldoc /usr/lib/amanda/perl/Amanda/Device.pm

In general, this POD describes the perl-specific calling conventions and other details of the module, while omitting the higher-level descsription that it shares with the C module. The latter description is available on this wiki.

Applications

Amanda applications written in Perl have a few features in common. They usually begin with

#! @PERL@
use lib '@amperldir@';

causing them to use the perl binary with which Amanda was configured, and to search the proper directory for Amanda modules.

The Amanda::Util module makes application setup fairly straightforward. Consult an existing Perl application for examples.

Build Architecture

Source for the Amanda perl modules is stored in the top-level directory perl/. This directory contains server-specific, client-specific, and common modules; the Makefile figures out which modules should be built for a specific installation. Some Amanda modules are native Perl, while others are interfaces to C code, built with SWIG. Both kinds of modules are stored side-by-side in perl/Amanda/. Finally, perl/amglue/ contains macros, functions, and other material to support the build process.

Native Perl Modules

Native Perl modules usually need some substitutions from configure, and as such have the suffix .pm.in. They are specified in the Makefile.am with a stanza like this:

# PACKAGE: Amanda::Foo
Amanda_DATA += Amanda/Foo.pm
EXTRA_DIST += Amanda/Foo.pm.in
DISTCLEANFILES += Amanda/Foo.pm

SWIG Modules

SWIG modules are, of course, a bit more complicated. SWIG converts C/C++ header files to extension modules. In common usage, SWIG is applied directly to an existing header file, with precomplier macros and typemaps applied to tweak its behavior where necessary. The result is usually a scripting language interface that is awkward but functional, but no code duplication. We want the Amanda Perl interface to be as natural as possible, as it will eventually be the primary or only interface.

Amanda modules, then, are built from distinct files, with the suffix .swg. These are technically header files, with many SWIG declarations (preceded by %) included. Fully understanding them requires a hearty familiarity with SWIG, but adding a new constant or function should be fairly straightforward.

There are a few helpful macro families defined in amglue/amglue.swg:

Exports

All Amanda modules use the Exporter module to export their symbols. Symbols are available for import individually, or organized by theme into tags. For example, Amanda::Debug exports initialization symbols like dbopen under the tag :init, and logging functions like info under the tag :logging.

A few SWIG macros exist to make this easier; see the comments in perl/amglue/exports.swg for details.

Constants

Amanda has many, many constants, most of which are either enumerations (e.g., protocol states) or bitfields (e.g., access permissions). These are written as follows:

amglue_add_flag_tag_fns(running_as_flags);
amglue_add_constant(RUNNING_AS_ROOT, running_as_flags);
amglue_add_constant(RUNNING_AS_DUMPUSER, running_as_flags);
/* ... */

This creates a Perl export tag named :running_as_flags, all of the constants as scalars (e.g., $RUNNING_AS_ROOT). It also creates a Perl function running_as_flags_to_strings which converts an integer to a list of the names of all matching constants. This function is useful for displaying flag values without writing out bit-level operations in Perl.

Likewise, enumerations begin with amglue_add_enum_tag_fns(..):

amglue_add_enum_tag_fns(logtype_t);
amglue_add_constant(L_BOGUS, logtype_t);
amglue_add_constant(L_FATAL, logtype_t);
/* ... */

and define a function logtype_t_to_string (note the singular) to convert an integer to the single corresponding string.

The macro amglue_add_constant_short is like amglue_add_constant, but uses a shorter name for conversion to string form. We could write, e.g.,

amglue_add_constant_short(RUNNING_AS_DUMPUSER, DUMPUSER, running_as_flags);

amglue_add_constant_noshort is like amglue_add_constant, but will never use the symbol when converting to string form. This is used for bit combinations, enumeration maxima, etc.

Integers

perl/amglue/integers.swg installs the requisite typemaps to accomplish the integer conversions described above.

History

Please consult the [email protected] archives for the "why" and "why perl" discussions.