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.

  The basic philosophy is that you can probably use make or visual studio
  or similar to do the heavy building. There is no real need to replicate 
  that. However stuff like checking out of CVS/SVN repositories, updating
  version numbers, checking it back in, running test harnesses, and similar
  are things that make is not good at. 

  XML is not a programming language, but you can describe a lot of
  what you want using it, which is what ANT/NANT basically do. However
  there is always something you want to do, which can't be described
  in the current description language. In these cases you can call out
  to an external routine to do things.

  However it seems much easier to provide a number of useful
  subroutines in a scripting language, which help you build
  things. Then if you need to do something slightly of piste, you have
  all the power right there.

  The other thing I want to know about is "did it work" and if it
  didn't, what went wrong? To this end plenty of logging is required so
  the build can be tracked. As the build is probably going to be remote,
  HTML seems the obvious choice to report in, so you can just look at it
  from a web server.

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([title],[style=>stuff])

This call should be the first call into the module. It does some intialisation, and parses command line arguments in @ARGV. It takes the following arguments.

String

The first argument is a string, and is used as the title of the web page if present. If not present it will be called "Build Log".

style=>stuff

This argument if present signals some style data to include. This will be included in a <style> tag. This allows you to apply different styles to the generated page.

stylelink=>href

This argument if present directs the inclusion of a style sheet external link.

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.

logname=>name

Name the log file that it will write to this. If this is not given, a name will be made up for you.

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.

The list is used as the contents of the header, and the first element of the list is used as an HTML anchor in case you want to refer to it.

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.

CopyTree(source, dest)

This function copies an entire tree hierarchy from the source to the destination. It makes use of File::Copy::Recursive routines to do this.

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.

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(args)

Run the list of perl style test files, and capture the result in the output of the log. The The arguments allow you to specify the tests to run, see PANT::Test for details.

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.

Svn()

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

FileCompare(F1, F2)

This function compares two files using the File::Compare routines to see if their contents are identical.

MakeTree(dir)

Create a given directory, and all required intermediate paths.

RmTree(dir)

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

BuildSolution(project, args...)

This function attempts to build a visual studio style project. The first argument is the base name of the project, which will be used to derive the .SLN and other files. It has the following parameters,

solution=>name

The name of the solution file. This can be used to insert a .vcproj file to have a similar effect.

project=>name

The given project in the solution you wish to build.

buildtype=>type

What sort of build you want to do. These are the support targets from visual studio, such as /build (default), /rebuild, /clean, /deploy etc.

log=>file

Where to output the log. The default is the base name with .log appended.

target=>Release

The target build environment, usually Debug or Release.

devenv=>devenv

The name of the devenv binary - which might be a full pathname.

FindPatternInFile(file, pattern)

This function searches the given file line by line, until it finds the pattern given, and returns the string matching the first bracketed expression int the regexp. This can be used to find things like file versions.

my $ver = FindPatternInFile("thing.rc", qr/^\s*FILEVERSION\s*(\d+,\d+,\d+,\d+)/);

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