ChainMake - Make targets with dependencies
# this example uses the function-oriented interface use ChainMake::Functions ':all'; # this target is to generate example.dvi from example.tex target 'example.dvi', ( timestamps => ['$t_name'], requirements => ['$t_base.tex'], handler => sub { my ($t_name,$t_base,$t_ext)=@_; execute_system( All => "latex $t_base.tex", ); } ); # this target is to generate example.ps from example.dvi # and another.ps from another.dvi targets ['example.ps','another.ps'], ( timestamps => ['$t_name'], requirements => ['$t_base.dvi'], handler => sub { my ($t_name,$t_base,$t_ext)=@_; execute_system( All => "dvips -q -t a5 $t_base.dvi", ); } ); # this target is to generate a *.pdf from a *.ps target qr/^[^\.]+\.pdf$/, ( timestamps => ['$t_name'], requirements => ['$t_base.ps'], handler => sub { my ($t_name,$t_base,$t_ext)=@_; execute_system( All => "ps2pdf $t_base.ps $t_base.pdf", ); } ); target 'clean', ( handler => sub { unlink qw/example.aux example.dvi example.log example.pdf example.ps/; 1; } ); target [qw/all All/], requirements => ['example.pdf','clean']; chainmake(@ARGV);
This module helps with driving data through process chains. It can be a better alternative to make in some use cases.
make
TODO: More bla here: * separation of target name from timestamp file * 'auto' timestamps, for targets that don't create files (i.e. xml validation) * write perl script in perl, not makefile in makefile lingo * typically for processing files (xml, images etc.) through several process steps (i.e. latex, xslt, pbmtools) * not so much for compiling and installing software, i.e. principally possible, but no luxury (libpath etc.) provided so far * in summary it is a better alternative for use cases that 'make' is not really intended for, but still widely used
A script that uses this module will typically create one ChainMake object, add some "targets" to it and then call the "chainmake" method, potentially with user supplied parameters.
For a more declarative look-and-feel, script authors may also consider using the function-oriented interface provided by ChainMake::Functions .
my $cm=new ChainMake(%options);
Creates a new ChainMake object. Options %options are the same as for configure.
%options
$cm->configure( timestamps_file => '.timestamps_file', symbols => [ qr/\$t_name/, qr/\$t_base/, qr/\$t_ext/ ], verbose => 1, silent => 0, );
Configures the ChainMake object. Available options are discussed below. Default values are shown above.
timestamps_file is a filename that will be used for automatic timestamps as discussed under "timestamps".
timestamps_file
symbols is a list of three regular expressions that are used for referring to the current target name. See "requirements" below.
symbols
Usage of verbose is under development and will change.
verbose
Usage of silent is under development and will change.
silent
$cm->targets( ['all', 'document'], requirements => ['document.html', 'document.pdf'] );
Adds a new target type. A human readable explanation will be given below.
For reference, this is a pseudo formal form of the syntax:
$target_names = targetname | regexp | [targetname | regexp, ...] %description = ( requirements => [ targetname | filename, ... ] | (), insistent => 0 | 1, parallel => 0 | number, handler => coderef | (), timestamps => [ filename, ... ] | 'once' | (), ); $cm->targets( $target_names, %description );
These are examples in perl:
$cm->targets( ['all', 'document'], requirements => ['document.html', 'document.pdf'] ); $cm->targets( qr/^[^\.]+\.html?$/, requirements => ['$t_base.xml'], handler => sub { ... }, timestamps => ['$t_base.$t_ext'], );
The first argument of the targets method is for supplying one or more targets names. Target names can be strings or regular expressions.
targets
The targets method declares a target type that is used for all targets that match any of the supplied target names.
%description = ( requirements => ['index.txt', '$t_base.dat'], }
The requirements field lists things that need to be done before the target can be made. The requirements field is optional, but either requirements or a handler must be specified.
requirements
handler
Requirements may be given as targets or filenames. If a given requirement does not match a target it is regarded a filename. Filenames should include a path if necessary.
The requirements strings may contain any of the three symbols specified with "configure". The symbols will be replaced with the current target's full name, base name (without extension) and extension respectively. Assuming that you haven't defined different symbols the following will be replaced in the requirements of a target 'index.html':
$t_name -> index.html $t_base -> index $t_ext -> html
%description = ( handler => sub { my ($t_name, $t_base, $t_ext) = @_; execute_system( All => "dvips -q -t a5 $t_base.dvi", ); } }
The handler field can be used to supply a subroutine that will be executed to build the target. The return value of this subroutine should indicate whether the build has been successfull.
Three parameters will be passed to the subroutine: The full name of the target to make, only the base part of this name (minus the extension), and the extension of the target name. These three variables equal the replacement symbols discussed under "requirements" and should convienently be named equally, i.e. $t_name, $t_base, $t_ext.
$t_name
$t_base
$t_ext
If no handler is supplied, the target will always be considered successfull.
%description = ( timestamps => ['index.html'], } %description2 = ( timestamps => 'once', }
The timestamps field defines how to check whether the target is up-to-date. Either one or more filenames or the string once may be supplied.
timestamps
once
The separation of the timestamps from the target name is an important difference between this module and make.
If the timestamps field is supplied, the handler field must be supplied as well.
If the timestamps is missing, each time that chainmake() is performed on the target all requirements will be checked and the handler will be executed.
chainmake()
In case one or more filenames are given, the timestamp (age) of the oldest of these files is determined. This timestamp is compared to the timestamps of all of the requirements to find out if the target is outdated or not.
The filenames may be identical to target names, but, as opposed to make, does not need to be. The filename is given with a path relative to the current directory. For a filename that matches the target name use timestamps => ['$t_name'].
timestamps => ['$t_name']
The file should typically be a file that the handler produces from at least some of the requirements. The handler must at least touch the file to make this form of timestamps work. If this is not the case, use 'once'.
touch
'once'
If the handler fails, any remaining files listed under timestamps will be removed.
The string once may be supplied instead of a list reference. This turns on automatic bookkeeping of the target's status.
The data necessary for the once automatism is stored in a file with the name that has been defined with the "timestamps_file" option.
%description = ( insistent => 1, );
The insistent field defines if remaining requirements should still still be checked after one requirement failed. Default behaviour is to stop.
insistent
When a target has several requirements they will be all be checked (and built if necessary) before this target can be built. If one of the requirements fails, i.e. does not exist or fails to built, the remaining requirements may still be checked (insistent => 1) or the attempt to build the target may aborted immediately (insistent => 0).
insistent => 1
insistent => 0
$cm->chainmake($target);
Makes the target $target.
$target
This is a simplified schematic of the algorithm in use:
Find matching target type
See, if all "timestamps" files are present and how old the oldest one is ($oldest)
$oldest
Go through all "requirements":
For the ones that are targets, call chainmake() on each of them to learn about their age (recursion here)
For the ones that are files, check their age
Compare all these ages with $oldest to see if one requirement is younger than the target $target. If so, we'll have to run the "handler"
If any requirement is missing: we cannot make $target; Continue with examining the remaining requirements if "insistent" == 1
The youngest of all the seen requirements is $youngest_requirement, as passed to the handler.
$youngest_requirement
Entire loop done in parallel threads by ChainMake::Parallel
Run the handler if necessary
Return the age of the youngest file in "timestamps"
print $cm->avaliable_targets();
Returns a formatted string listing the available targets. This will maybe change.
$cm1->delete_timestamp('document.validation')
Deletes the automatic ('once') timestamp for the given target.
Unlinks the timestamps file.
Under development.
Under development, i.e. too lazy to document right now.
None known. In the Rakudo way: It passes almost 300 tests.
My search for similar modules has returned the following
Very minimalistic. Syntax tries to mimic makefile syntax.
Uses some sort of database. Difficult-to-read documentation.
This is $Id: ChainMake.pm 1231 2009-03-15 21:23:32Z schroeer $.
Copyright 2008-2009 Daniel Schröer (schroeer@cpan.org). Any feedback is appreciated.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'Schröer'. Assuming CP1252
To install ChainMake, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ChainMake
CPAN shell
perl -MCPAN -e shell install ChainMake
For more information on module installation, please visit the detailed CPAN module installation guide.