NAME

PANT - Perl extension for ANT/NANT like build environments

SYNOPSIS

  perl buildall.pl -output buildlog

  use PANT;
  StartPant();
  Phase(1, "Update");
  Task(Command("cvs update"), "Fetch the latest code");
  Phase(2, "Build");
  Task(UpdateFileVersion("h/version.h",
         qr/(#define\s*VERSION\s+)(\d+)/=>q{"$1" . ($2+1)"},
         "Version file updated");
  Task(Command("make all"), "Built distribution");
  Phase(3, "Deploy");
  Task(Command("make distribution"), "Distribution built");
  if (NewerThan(sources=>["myexe"], targets=>["/usr/bin/myexe"])) {
     CopyFiles("myexe", "/usr/bin");
  }
  EndPant();

ABSTRACT

  This is a module to help construct automated build environments.
  The inspiration came from the ANT/NANT build environments which use
  XML to describe a make like syntax of dependencies. For various
  reasons none of these were suitable for my purposes, and I suspect
  that eventually you will end up writing something pretty similar to
  perl in XML to cater for all the things you want to do.  Also a
  module named PANT was just too good a name to miss!

  This module draws on some of the ideas in ANT/NANT, and also in the
  Test::Mode module for ways to do things.  This module is therefore a
  collection of tools to help automate processes, and provide a build
  log of what happened, so remote builds can be observed.

DESCRIPTION

This module provides various useful functions to help in the automated build of a project and to produce a build log. It is still in development, and may well change shape in the light of experience.

EXPORTS

StartPant([message])

This call should be the first call into the module. It does some intialisation, and parses command line arguments in @ARGV. It takes one optional argument which is a string used to title the HTML build log. If not present it will be called "Build Log".

Supported command line options are

-output file

Write the output to the given file.

-dryrun

Simulate a run without actually doing anything.

EndPant()

This function finishes up the run, and should be the last call into the module. It completes the build log in a tidy way.

CallPant(name, options)

This function allows you to call a subsidiary pant build. The build will be run and waited for. A reference in the current log will be made to the new log. It is assumed that the subsidiary build is also using PANT as it passes some command line arguments to sort out the logging.

Options include

directory=>place

Change to the given directory to run the subsidiary build. The log path should be modified so it fits.

Phase([list])

This function is purely for help in dividing up the build log. It inserts a heading into the log allowing you to divide the build up into a variety of parts. You might have a pre-build cvs checkput phase, a build phase, and followed up by a test and deployment phase.

DateStamp

This function returns a datestamp in a common format. Its is intended for use in logging output, and also in CVS/SVN type retrievals.

NewerThan(sources=>[qw(f1 f2*.txt)], targets=>[build], ...)

This function provides a make like dependency checker. It has the following arguments,

sources

A list of wildcard (glob'able) files that are the source.

treesources

A list of wildcard directories that are descended for source files. Currently all files in the tree are considered possibilities.

targets

A list of wildcard (glob'able) files that are the target

The function will return true if any of the sources are newer than the oldest of the targets.

Task(result, message)

This command evaluates the first argument to see if it is true, and prints the second argument into the log. If the first argument is false, the build will abort.

Abort(list)

This function aborts the build and is called internally when thigns go wrong.

Command(cmd, options)

This function runs the given external command, capturing the output for the log, and evaluating the return code to see if it worked.

Currently there is only one option

directory=>"somewhere"

This will cause the command to run in the given directory, rather than being where you happen to be currently.

CopyFiles(source, destdir)

This function copies all the files that match the source glob pattern to the given directory. The names will remain the same.

CopyFile(source, dest)

This function copies an individual file from the source to the destination. It allows for renaming.

MoveFiles(source, destdir)

This function moves all the files that match the source glob pattern to the given directory. The names will remain the same.

MoveFile(source, dest)

This function moves an individual file from the source to the destination. It allows for renaming.

RmTree(dir)

This function removes the entire tree starting at the given directory. Obviuosly be careful!

MakeTree(dir)

Create a given directory, and an required intermediate paths.

UpdateFileVersion(file, patterns)

This functions name will probably change. It allows for updating files contents based on the given set of patterns. Some care is needed to get the patterns and the replacements correct. The replacement text is subject to double evaluation.

AddOutput(list)

This allows additional commentary to be added to the output stream.

AddElement(list)

This allows additional constructs to be added to the output, such a href references and so on. It is passed onto XML::Writer::dataElement directly and takes the same syntax.

RunTests(list)

Run the list of perl style test files, and capture the result in the output of the log.

Zip(file)

This function returns a PANT::Zip object to help construct the given zip file. See PANT::Zip for more details.

Cvs()

This function returns a PANT::Cvs object to help with running Cvs commands. See PANT::Cvs for more details.

FileCompare(F1, F2, [alg])

This function compares two files for equality using the given hash algorithm. If no algorithm is given, it will use MD5. Returns true if they are the same.

SEE ALSO

Makes use of XML::Writer to construct the build log.

AUTHOR

Julian Onions, <julianonions@yahoo.nospam-co.uk>

COPYRIGHT AND LICENSE

Copyright 2005 by Julian Onions

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

RULES TO LIVE BY

Don't get caught with your PANT's down.

Don't get your PANT's in a wad.

cpanm PANT

perl -MCPAN -e shell
install PANT