EekBoek-2.02.04/0000755000175000017500000000000012165465617012225 5ustar thijsthijsEekBoek-2.02.04/Makefile.PL0000555000175000017500000000241012165465617014175 0ustar thijsthijs# Makefile.PL -- Build file for EekBoek # Author : Johan Vromans # Created On : Fri Sep 2 14:25:11 2005 # Last Modified By: Johan Vromans # Last Modified On: Tue Jul 6 23:24:13 2010 # Update Count : 105 # Status : Unknown, Use with caution! # Ease the life of the CPAN testers. exit 0 if $ENV{AUTOMATED_TESTING} && $] < 5.008003; use 5.008003; use strict; #use inc::Module::Install; use ExtUtils::MakeMaker; our $data = {}; require 'inc/build_common.pl'; # Warn on non-standard install locations. checkbin(<{usrbin} (or some other convenient location) to "make install". EOD # Write Makefile. my $x = WriteMakefile( NAME => $data->{distname}, AUTHOR => $data->{author}, ABSTRACT => $data->{abstract}, PL_FILES => $data->{pl_files}, INSTALLDIRS => $data->{installtype}, DISTNAME => $data->{distname}, EXE_FILES => $data->{script_files}, VERSION_FROM => "lib/EekBoek.pm", PREREQ_PM => { %{$data->{prereq_pm}}, %{$data->{buildreq_pm}}, }, PM => filelist("lib", '$(INST_LIBDIR)/'), ); # Write .spec file, Debian control, ... ProcessTemplates($data->{distname}, $x->{VERSION}); EekBoek-2.02.04/README.emacs0000444000175000017500000000110112165465617014163 0ustar thijsthijsThe EekBoek kit contains two files to be used with GNU Emacs. eekboek-mode.el defines the 'eekboek' major mode for editing EekBoek data files. It is nothing fancy yet. eekboek-site-init.el contains the necessary autoload settings and type associations for EekBoek files. Place these files according to how your distribution configures GNU Emacs. For Fedora systems: /usr/share/emacs/site-lisp/site-start.d/eekboek.el /usr/share/emacs/site-lisp/eekboek-mode.el For Debian systems: /etc/emacs/site-start.d/50eekboek.el /usr/share/emacs/site-lisp/eekboek-mode.el EekBoek-2.02.04/inc/0000755000175000017500000000000012165465617012776 5ustar thijsthijsEekBoek-2.02.04/inc/build_common.pl0000444000175000017500000000776312165465617016015 0ustar thijsthijs# build_common.inc -- Build file common info -*- perl -*- # RCS Info : $Id: build_common.pl,v 1.27 2010/03/29 15:37:55 jv Exp $ # Author : Johan Vromans # Created On : Thu Sep 1 17:28:26 2005 # Last Modified By: Johan Vromans # Last Modified On: Tue Aug 28 21:32:23 2012 # Update Count : 107 # Status : Unknown, Use with caution! use strict; use Config; use File::Spec; our $data; $data = { %$data, author => 'Johan Vromans (jvromans@squirrel.nl)', abstract => 'Elementary Bookkeeping (for the Dutch/European market)', PL_files => {}, installtype => 'site', modname => 'EekBoek', distname => 'EekBoek', license => "perl", script_files => [ map { File::Spec->catfile("script", $_) } qw(ebshell ebwxshell) ], prereq_pm => { 'Getopt::Long' => '2.13', 'Term::ReadLine' => 0, $^O eq "linux" ? ('Term::ReadLine::Gnu' => 0) : (), 'DBI' => '1.40', 'Archive::Zip' => '1.16', 'DBD::SQLite' => '1.13', }, buildreq_pm => { # These are required for the build/test, and will be included. 'Module::Build' => '0.26', 'IPC::Run3' => '0.034', }, recomm_pm => { 'Getopt::Long' => '2.32', 'HTML::Entities' => '1.35', 'DBD::Pg' => '1.41', }, usrbin => "/usr/bin", }; sub checkbin { my ($msg) = @_; my $installscript = $Config{installscript}; return if $installscript eq $data->{usrbin}; print STDERR < ) { chomp; next unless /$dirp(.*)/; $pm->{$_} = $pfx ? $pfx . $1 : $_; } close($mf); $pm; } sub filelist_dyn { my ($dir, $pfx) = @_; use File::Find; $pfx ||= ""; my $dirl = length($dir); my $pm; find(sub { if ( $_ eq "CVS" ) { $File::Find::prune = 1; return; } return if /^#.*#/; return if /~$/; return unless -f $_; if ( $pfx ) { $pm->{$File::Find::name} = $pfx . substr($File::Find::name, $dirl); } else { $pm->{$File::Find::name} = $pfx . $File::Find::name; } }, $dir); $pm; } sub ProcessTemplates { my $name = shift; my $version = shift; my ($mv) = $version =~ /^\d+\.(\d+)/; my %vars = ( PkgName => $name, pkgname => lc($name), version => $version, stable => $mv % 2 ? "-unstable" : "\%nil", stability => $mv % 2 ? "unstable" : "stable", ); vcopy( _tag => "RPM spec file", _dst => "$name.spec", %vars); vcopy( _tag => "XAF ref file (NL)", _dst => "t/ivp/ref/export.xaf", %vars); vcopy( _tag => "XAF ref file (EN)", _dst => "t/ivp_en/ref/export.xaf", %vars); =begin Debian vcopy( _tag => "Debian control file", _dst => "debian/control", %vars); vcopy( _tag => "Debian rules file", _dst => "debian/rules", %vars); ); chmod((((stat("debian/rules"))[2] & 0777) | 0111), "debian/rules"); vcopy( _tag => "Debian changelog file", _dst => "debian/changelog", %vars); =end =cut } sub vcopy { my (%ctrl) = @_; $ctrl{_src} ||= $ctrl{_dst} . ".in"; return unless open(my $fh, "<", $ctrl{_src}); print("Writing ", $ctrl{_tag}, "...\n") if $ctrl{_tag}; my $newfh; open ($newfh, ">", $ctrl{_dst}) or die($ctrl{_dst}, ": $!\n"); my $pat = "("; foreach ( grep { ! /^_/ } keys(%ctrl) ) { $pat .= quotemeta($_) . "|"; } chop($pat); $pat .= ")"; $pat = qr/\[\%\s+$pat\s+\%\]/; while ( <$fh> ) { s/$pat/$ctrl{$1}/ge; print { $newfh } $_; } close($newfh); } 1; EekBoek-2.02.04/inc/IPC/0000755000175000017500000000000012165465617013411 5ustar thijsthijsEekBoek-2.02.04/inc/IPC/Run3/0000755000175000017500000000000012165465617014240 5ustar thijsthijsEekBoek-2.02.04/inc/IPC/Run3/ProfLogger.pm0000444000175000017500000000504412165465617016645 0ustar thijsthijspackage IPC::Run3::ProfLogger; $VERSION = 0.030; =head1 NAME IPC::Run3::ProfLogger - write profiling data to a log file =head1 SYNOPSIS use IPC::Run3::ProfLogger; my $logger = IPC::Run3::ProfLogger->new; ## write to "run3.out" my $logger = IPC::Run3::ProfLogger->new( Destination => $fn ); $logger->app_call( \@cmd, $time ); $logger->run_exit( \@cmd1, @times1 ); $logger->run_exit( \@cmd1, @times1 ); $logger->app_exit( $time ); =head1 DESCRIPTION Used by IPC::Run3 to write a profiling log file. Does not generate reports or maintain statistics; its meant to have minimal overhead. Its API is compatible with a tiny subset of the other IPC::Run profiling classes. =cut use strict; use warnings; =head1 METHODS =head2 C<< IPC::Run3::ProfLogger->new( ... ) >> =cut sub new { my $class = ref $_[0] ? ref shift : shift; my $self = bless { @_ }, $class; $self->{Destination} = "run3.out" unless defined $self->{Destination} && length $self->{Destination}; open PROFILE, ">$self->{Destination}" or die "$!: $self->{Destination}\n"; binmode PROFILE; $self->{FH} = *PROFILE{IO}; $self->{times} = []; return $self; } =head2 C<< $logger->run_exit( ... ) >> =cut sub run_exit { my $self = shift; my $fh = $self->{FH}; print( $fh join( " ", ( map { my $s = $_; $s =~ s/\\/\\\\/g; $s =~ s/ /_/g; $s; } @{shift()} ), join( ",", @{$self->{times}}, @_, ), ), "\n" ); } =head2 C<< $logger->app_exit( $arg ) >> =cut sub app_exit { my $self = shift; my $fh = $self->{FH}; print $fh "\\app_exit ", shift, "\n"; } =head2 C<< $logger->app_call( $t, @args) >> =cut sub app_call { my $self = shift; my $fh = $self->{FH}; my $t = shift; print( $fh join( " ", "\\app_call", ( map { my $s = $_; $s =~ s/\\\\/\\/g; $s =~ s/ /\\_/g; $s; } @_ ), $t, ), "\n" ); } =head1 LIMITATIONS =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker Ebarries@slaysys.comE =cut 1; EekBoek-2.02.04/inc/IPC/Run3/ProfReporter.pm0000444000175000017500000001267712165465617017242 0ustar thijsthijspackage IPC::Run3::ProfReporter; $VERSION = 0.000_1; =head1 NAME IPC::Run3::ProfReporter - base class for handling profiling data =head1 SYNOPSIS =head1 DESCRIPTION See L and for an example subclass. This class just notes and accumulates times; subclasses use methods like "handle_app_call", "handle_run_exit" and "handle_app_exit" to emit reports on it. The default methods for these handlers are noops. If run from the command line, a reporter will be created and run on each logfile given as a command line parameter or on run3.out if none are given. This allows reports to be run like: perl -MIPC::Run3::ProfPP -e1 perl -MIPC::Run3::ProfPP -e1 foo.out bar.out Use "-" to read from STDIN (the log file format is meant to be moderately greppable): grep "^cvs " run3.out perl -MIPC::Run3::ProfPP -e1 - Use --app to show only application level statistics (ie don't emit a report section for each command run). =cut use strict; my $loaded_by; sub import { $loaded_by = shift; } END { my @caller; for ( my $i = 0;; ++$i ) { my @c = caller $i; last unless @c; @caller = @c; } if ( $caller[0] eq "main" && $caller[1] eq "-e" ) { require IPC::Run3::ProfLogReader; require Getopt::Long; my ( $app, $run ); Getopt::Long::GetOptions( "app" => \$app, "run" => \$run, ); $app = 1, $run = 1 unless $app || $run; for ( @ARGV ? @ARGV : "" ) { my $r = IPC::Run3::ProfLogReader->new( Source => $_, Handler => $loaded_by->new( Source => $_, app_report => $app, run_report => $run, ), ); $r->read_all; } } } =head1 METHODS =over =item C<< IPC::Run3::ProfReporter->new >> Returns a new profile reporting object. =cut sub new { my $class = ref $_[0] ? ref shift : shift; my $self = bless { @_ }, $class; $self->{app_report} = 1, $self->{run_report} = 1 unless $self->{app_report} || $self->{run_report}; return $self; } =item C<< $reporter->handle_app_call( ... ) >> =item C<< $reporter->handle_app_exit( ... ) >> =item C<< $reporter->handle_run_exit( ... ) >> These methods are called by the handled events (see below). =cut sub handle_app_call {} sub handle_app_exit {} sub handle_run_exit {} =item C<< $reporter->app_call(\@cmd, $time) >> =item C<< $reporter->app_exit($time) >> =item C<< $reporter->run_exit(@times) >> $self->app_call( $time ); my $time = $self->get_app_call_time; Sets the time (in floating point seconds) when the application, run3(), or system() was called or exited. If no time parameter is passed, uses IPC::Run3's time routine. Use get_...() to retrieve these values (and _accum values, too). This is a separate method to speed the execution time of the setters just a bit. =cut sub app_call { my $self = shift; ( $self->{app_cmd}, $self->{app_call_time} ) = @_; $self->handle_app_call if $self->{app_report}; } sub app_exit { my $self = shift; $self->{app_exit_time} = shift; $self->handle_app_exit if $self->{app_report}; } sub run_exit { my $self = shift; @{$self}{qw( run_cmd run_call_time sys_call_time sys_exit_time run_exit_time )} = @_; ++$self->{run_count}; $self->{run_cumulative_time} += $self->get_run_time; $self->{sys_cumulative_time} += $self->get_sys_time; $self->handle_run_exit if $self->{run_report}; } =item C<< $reporter->get_run_count() >> =item C<< $reporter->get_app_call_time() >> =item C<< $reporter->get_app_exit_time() >> =item C<< $reporter->get_app_cmd() >> =item C<< $reporter->get_app_time() >> =cut sub get_run_count { shift->{run_count} } sub get_app_call_time { shift->{app_call_time} } sub get_app_exit_time { shift->{app_exit_time} } sub get_app_cmd { shift->{app_cmd} } sub get_app_time { my $self = shift; $self->get_app_exit_time - $self->get_app_call_time; } =item C<< $reporter->get_app_cumulative_time() >> =cut sub get_app_cumulative_time { my $self = shift; $self->get_app_exit_time - $self->get_app_call_time; } =item C<< $reporter->get_run_call_time() >> =item C<< $reporter->get_run_exit_time() >> =item C<< $reporter->get_run_time() >> =cut sub get_run_call_time { shift->{run_call_time} } sub get_run_exit_time { shift->{run_exit_time} } sub get_run_time { my $self = shift; $self->get_run_exit_time - $self->get_run_call_time; } =item C<< $reporter->get_run_cumulative_time() >> =cut sub get_run_cumulative_time { shift->{run_cumulative_time} } =item C<< $reporter->get_sys_call_time() >> =item C<< $reporter->get_sys_exit_time() >> =item C<< $reporter->get_sys_time() >> =cut sub get_sys_call_time { shift->{sys_call_time} } sub get_sys_exit_time { shift->{sys_exit_time} } sub get_sys_time { my $self = shift; $self->get_sys_exit_time - $self->get_sys_call_time; } =item C<< $reporter->get_sys_cumulative_time() >> =cut sub get_sys_cumulative_time { shift->{sys_cumulative_time} } =item C<< $reporter->get_run_cmd() >> =cut sub get_run_cmd { shift->{run_cmd} } =back =head1 LIMITATIONS =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker =cut 1; EekBoek-2.02.04/inc/IPC/Run3/ProfLogReader.pm0000444000175000017500000000561712165465617017300 0ustar thijsthijspackage IPC::Run3::ProfLogReader; $VERSION = 0.030; =head1 NAME IPC::Run3::ProfLogReader - read and process a ProfLogger file =head1 SYNOPSIS use IPC::Run3::ProfLogReader; my $reader = IPC::Run3::ProfLogReader->new; ## use "run3.out" my $reader = IPC::Run3::ProfLogReader->new( Source => $fn ); my $profiler = IPC::Run3::ProfPP; ## For example my $reader = IPC::Run3::ProfLogReader->new( ..., Handler => $p ); $reader->read; $eaderr->read_all; =head1 DESCRIPTION Reads a log file. Use the filename "-" to read from STDIN. =cut use strict; use warnings; =head1 METHODS =head2 C<< IPC::Run3::ProfLogReader->new( ... ) >> =cut sub new { my $class = ref $_[0] ? ref shift : shift; my $self = bless { @_ }, $class; $self->{Source} = "run3.out" unless defined $self->{Source} && length $self->{Source}; my $source = $self->{Source}; if ( ref $source eq "GLOB" || UNIVERSAL::isa( $source, "IO::Handle" ) ) { $self->{FH} = $source; } elsif ( $source eq "-" ) { $self->{FH} = \*STDIN; } else { open PROFILE, "<$self->{Source}" or die "$!: $self->{Source}\n"; $self->{FH} = *PROFILE{IO}; } return $self; } =head2 C<< $reader->set_handler( $handler ) >> =cut sub set_handler { $_[0]->{Handler} = $_[1] } =head2 C<< $reader->get_handler() >> =cut sub get_handler { $_[0]->{Handler} } =head2 C<< $reader->read() >> =cut sub read { my $self = shift; my $fh = $self->{FH}; my @ln = split / /, <$fh>; return 0 unless @ln; return 1 unless $self->{Handler}; chomp $ln[-1]; ## Ignore blank and comment lines. return 1 if @ln == 1 && ! length $ln[0] || 0 == index $ln[0], "#"; if ( $ln[0] eq "\\app_call" ) { shift @ln; my @times = split /,/, pop @ln; $self->{Handler}->app_call( [ map { s/\\\\/\\/g; s/\\_/ /g; $_; } @ln ], @times ); } elsif ( $ln[0] eq "\\app_exit" ) { shift @ln; $self->{Handler}->app_exit( pop @ln, @ln ); } else { my @times = split /,/, pop @ln; $self->{Handler}->run_exit( [ map { s/\\\\/\\/g; s/\\_/ /g; $_; } @ln ], @times ); } return 1; } =head2 C<< $reader->read_all() >> This method reads until there is nothing left to read, and then returns true. =cut sub read_all { my $self = shift; 1 while $self->read; return 1; } =head1 LIMITATIONS =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker Ebarries@slaysys.comE =cut 1; EekBoek-2.02.04/inc/IPC/Run3/ProfArrayBuffer.pm0000444000175000017500000000237712165465617017644 0ustar thijsthijspackage IPC::Run3::ProfArrayBuffer; $VERSION = 0.030; =head1 NAME IPC::Run3::ProfArrayBuffer - Store profile events in RAM in an array =head1 SYNOPSIS =head1 DESCRIPTION =cut use strict; use warnings; =head1 METHODS =over =item C<< IPC::Run3::ProfArrayBuffer->new() >> =cut sub new { my $class = ref $_[0] ? ref shift : shift; my $self = bless { @_ }, $class; $self->{Events} = []; return $self; } =item C<< $buffer->app_call(@events) >> =item C<< $buffer->app_exit(@events) >> =item C<< $buffer->run_exit(@events) >> The three above methods push the given events onto the stack of recorded events. =cut for my $subname ( qw(app_call app_exit run_exit) ) { no strict 'refs'; *{$subname} = sub { push @{shift->{Events}}, [ $subname => @_ ]; }; } =item get_events Returns a list of all the events. Each event is an ARRAY reference like: [ "app_call", 1.1, ... ]; =cut sub get_events { my $self = shift; @{$self->{Events}}; } =back =head1 LIMITATIONS =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker Ebarries@slaysys.comE =cut 1; EekBoek-2.02.04/inc/IPC/Run3/ProfPP.pm0000444000175000017500000000706012165465617015745 0ustar thijsthijspackage IPC::Run3::ProfPP; $VERSION = 0.000_1; =head1 NAME IPC::Run3::ProfPP - Generate reports from IPC::Run3 profiling data =head1 SYNOPSIS =head1 DESCRIPTION Used by IPC::Run3 and/or run3profpp to print out profiling reports for human readers. Use other classes for extracting data in other ways. The output methods are plain text, override these (see the source for now) to provide other formats. This class generates reports on each run3_exit() and app_exit() call. =cut require IPC::Run3::ProfReporter; @ISA = qw( IPC::Run3::ProfReporter ); use strict; use warnings; use POSIX qw( floor ); =head1 METHODS =head2 C<< IPC::Run3::ProfPP->new() >> Returns a new profile reporting object. =cut sub _t { sprintf "%10.6f secs", @_; } sub _r { my ( $num, $denom ) = @_; return () unless $denom; sprintf "%10.6f", $num / $denom; } sub _pct { my ( $num, $denom ) = @_; return () unless $denom; sprintf " (%3d%%)", floor( 100 * $num / $denom + 0.5 ); } =head2 C<< $profpp->handle_app_call() >> =cut sub handle_app_call { my $self = shift; warn "IPC::Run3 parent: ", join( " ", @{$self->get_app_cmd} ), "\n"; $self->{NeedNL} = 1; } =head2 C<< $profpp->handle_app_exit() >> =cut sub handle_app_exit { my $self = shift; warn "\n" if $self->{NeedNL} && $self->{NeedNL} != 1; warn "IPC::Run3 total elapsed: ", _t( $self->get_app_cumulative_time ), "\n"; warn "IPC::Run3 calls to run3(): ", sprintf( "%10d", $self->get_run_count ), "\n"; warn "IPC::Run3 total spent in run3(): ", _t( $self->get_run_cumulative_time ), _pct( $self->get_run_cumulative_time, $self->get_app_cumulative_time ), ", ", _r( $self->get_run_cumulative_time, $self->get_run_count ), " per call", "\n"; my $exclusive = $self->get_app_cumulative_time - $self->get_run_cumulative_time; warn "IPC::Run3 total spent not in run3(): ", _t( $exclusive ), _pct( $exclusive, $self->get_app_cumulative_time ), "\n"; warn "IPC::Run3 total spent in children: ", _t( $self->get_sys_cumulative_time ), _pct( $self->get_sys_cumulative_time, $self->get_app_cumulative_time ), ", ", _r( $self->get_sys_cumulative_time, $self->get_run_count ), " per call", "\n"; my $overhead = $self->get_run_cumulative_time - $self->get_sys_cumulative_time; warn "IPC::Run3 total overhead: ", _t( $overhead ), _pct( $overhead, $self->get_sys_cumulative_time ), ", ", _r( $overhead, $self->get_run_count ), " per call", "\n"; } =head2 C<< $profpp->handle_run_exit() >> =cut sub handle_run_exit { my $self = shift; my $overhead = $self->get_run_time - $self->get_sys_time; warn "\n" if $self->{NeedNL} && $self->{NeedNL} != 2; $self->{NeedNL} = 3; warn "IPC::Run3 child: ", join( " ", @{$self->get_run_cmd} ), "\n"; warn "IPC::Run3 run3() : ", _t( $self->get_run_time ), "\n", "IPC::Run3 child : ", _t( $self->get_sys_time ), "\n", "IPC::Run3 overhead: ", _t( $overhead ), _pct( $overhead, $self->get_sys_time ), "\n"; } =head1 LIMITATIONS =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker Ebarries@slaysys.comE =cut 1; EekBoek-2.02.04/inc/IPC/Run3.pm0000444000175000017500000004253312165465617014603 0ustar thijsthijspackage IPC::Run3; =head1 NAME IPC::Run3 - run a subprocess in batch mode (a la system) on Unix, Win32, etc. =head1 VERSION version 0.034 =cut $VERSION = '0.034'; =head1 SYNOPSIS use IPC::Run3; # Exports run3() by default run3 \@cmd, \$in, \$out, \$err; run3 \@cmd, \@in, \&out, \$err; =head1 DESCRIPTION This module allows you to run a subprocess and redirect stdin, stdout, and/or stderr to files and perl data structures. It aims to satisfy 99% of the need for using C, C, and C with a simple, extremely Perlish API and none of the bloat and rarely used features of IPC::Run. Speed, simplicity, and portability are paramount. (That's speed of Perl code; which is often much slower than the kind of buffered I/O that this module uses to spool input to and output from the child command.) Disk space is not. =head2 C<< run3(\@cmd, INPUT, OUTPUT, \$err) >> Note that passing in a reference to C explicitly redirects the associated file descriptor for C, C, or C from or to the local equivalent of C (this does I pass a closed filehandle). Passing in C (or not passing a redirection) allows the child to inherit the corresponding C, C, or C from the parent. Because the redirects come last, this allows C and C to default to the parent's by just not specifying them -- a common use case. B: This means that: run3 \@cmd, undef, \$out; # Pass on parent's STDIN B, it passes on the parent's. Use run3 \@cmd, \undef, \$out; # Close child's STDIN for that. It's not ideal, but it does work. If the exact same value is passed for C<$stdout> and C<$stderr>, then the child will write both to the same filehandle. In general, this means that run3 \@cmd, \undef, "foo.txt", "foo.txt"; run3 \@cmd, \undef, \$both, \$both; will DWYM and pass a single file handle to the child for both C and C, collecting all into C<$both>. =head1 DEBUGGING To enable debugging use the IPCRUN3DEBUG environment variable to a non-zero integer value: $ IPCRUN3DEBUG=1 myapp =head1 PROFILING To enable profiling, set IPCRUN3PROFILE to a number to enable emitting profile information to STDERR (1 to get timestamps, 2 to get a summary report at the END of the program, 3 to get mini reports after each run) or to a filename to emit raw data to a file for later analysis. =head1 COMPARISON Here's how it stacks up to existing APIs: =over =item compared to C, C, C, C: =over =item + redirects more than one file descriptor =item + returns TRUE on success, FALSE on failure =item + throws an error if problems occur in the parent process (or the pre-exec child) =item + allows a very perlish interface to Perl data structures and subroutines =item + allows 1 word invocations to avoid the shell easily: run3 ["foo"]; # does not invoke shell =item - does not return the exit code, leaves it in $? =back =item compared to C, C: =over =item + No lengthy, error prone polling / select loop needed =item + Hides OS dependancies =item + Allows SCALAR, ARRAY, and CODE references to source and sink I/O =item + I/O parameter order is like open3() (not like open2()). =item - Does not allow interaction with the subprocess =back =item compared to C: =over =item + Smaller, lower overhead, simpler, more portable =item + No select() loop portability issues =item + Does not fall prey to Perl closure leaks =item - Does not allow interaction with the subprocess (which IPC::Run::run() allows by redirecting subroutines). =item - Lacks many features of IPC::Run::run() (filters, pipes, redirects, pty support). =back =back =cut @EXPORT = qw( run3 ); %EXPORT_TAGS = ( all => \@EXPORT ); @ISA = qw( Exporter ); use Exporter; use strict; use constant debugging => $ENV{IPCRUN3DEBUG} || $ENV{IPCRUNDEBUG} || 0; use constant profiling => $ENV{IPCRUN3PROFILE} || $ENV{IPCRUNPROFILE} || 0; use constant is_win32 => 0 <= index $^O, "Win32"; BEGIN { if ( is_win32 ) { eval "use Win32 qw( GetOSName ); 1" or die $@; } } #use constant is_win2k => is_win32 && GetOSName() =~ /Win2000/i; #use constant is_winXP => is_win32 && GetOSName() =~ /WinXP/i; use Carp qw( croak ); use File::Temp qw( tempfile ); use POSIX qw( dup dup2 ); # We cache the handles of our temp files in order to # keep from having to incur the (largish) overhead of File::Temp my %fh_cache; my $fh_cache_pid = $$; my $profiler; sub _profiler { $profiler } # test suite access BEGIN { if ( profiling ) { eval "use Time::HiRes qw( gettimeofday ); 1" or die $@; if ( $ENV{IPCRUN3PROFILE} =~ /\A\d+\z/ ) { require IPC::Run3::ProfPP; IPC::Run3::ProfPP->import; $profiler = IPC::Run3::ProfPP->new(Level => $ENV{IPCRUN3PROFILE}); } else { my ( $dest, undef, $class ) = reverse split /(=)/, $ENV{IPCRUN3PROFILE}, 2; $class = "IPC::Run3::ProfLogger" unless defined $class && length $class; if ( not eval "require $class" ) { my $e = $@; $class = "IPC::Run3::$class"; eval "require IPC::Run3::$class" or die $e; } $profiler = $class->new( Destination => $dest ); } $profiler->app_call( [ $0, @ARGV ], scalar gettimeofday() ); } } END { $profiler->app_exit( scalar gettimeofday() ) if profiling; } sub _spool_data_to_child { my ( $type, $source, $binmode_it ) = @_; # If undef (not \undef) passed, they want the child to inherit # the parent's STDIN. return undef unless defined $source; warn "binmode()ing STDIN\n" if is_win32 && debugging && $binmode_it; my $fh; if ( ! $type ) { local *FH; # Do this the backcompat way open FH, "<$source" or croak "$!: $source"; $fh = *FH{IO}; if ( is_win32 ) { binmode $fh, ":raw"; # Remove all layers binmode $fh, ":crlf" unless $binmode_it; } warn "run3(): feeding file '$source' to child STDIN\n" if debugging >= 2; } elsif ( $type eq "FH" ) { $fh = $source; warn "run3(): feeding filehandle '$source' to child STDIN\n" if debugging >= 2; } else { $fh = $fh_cache{in} ||= tempfile; truncate $fh, 0; seek $fh, 0, 0; if ( is_win32 ) { binmode $fh, ":raw"; # Remove any previous layers binmode $fh, ":crlf" unless $binmode_it; } my $seekit; if ( $type eq "SCALAR" ) { # When the run3()'s caller asks to feed an empty file # to the child's stdin, we want to pass a live file # descriptor to an empty file (like /dev/null) so that # they don't get surprised by invalid fd errors and get # normal EOF behaviors. return $fh unless defined $$source; # \undef passed warn "run3(): feeding SCALAR to child STDIN", debugging >= 3 ? ( ": '", $$source, "' (", length $$source, " chars)" ) : (), "\n" if debugging >= 2; $seekit = length $$source; print $fh $$source or die "$! writing to temp file"; } elsif ( $type eq "ARRAY" ) { warn "run3(): feeding ARRAY to child STDIN", debugging >= 3 ? ( ": '", @$source, "'" ) : (), "\n" if debugging >= 2; print $fh @$source or die "$! writing to temp file"; $seekit = grep length, @$source; } elsif ( $type eq "CODE" ) { warn "run3(): feeding output of CODE ref '$source' to child STDIN\n" if debugging >= 2; my $parms = []; # TODO: get these from $options while (1) { my $data = $source->( @$parms ); last unless defined $data; print $fh $data or die "$! writing to temp file"; $seekit = length $data; } } seek $fh, 0, 0 or croak "$! seeking on temp file for child's stdin" if $seekit; } croak "run3() can't redirect $type to child stdin" unless defined $fh; return $fh; } sub _fh_for_child_output { my ( $what, $type, $dest, $binmode_it ) = @_; my $fh; if ( $type eq "SCALAR" && $dest == \undef ) { warn "run3(): redirecting child $what to oblivion\n" if debugging >= 2; $fh = $fh_cache{nul} ||= do { local *FH; open FH, ">" . File::Spec->devnull; *FH{IO}; }; } elsif ( $type eq "FH" ) { $fh = $dest; warn "run3(): redirecting $what to filehandle '$dest'\n" if debugging >= 3; } elsif ( !$type ) { warn "run3(): feeding child $what to file '$dest'\n" if debugging >= 2; local *FH; open FH, ">$dest" or croak "$!: $dest"; $fh = *FH{IO}; } else { warn "run3(): capturing child $what\n" if debugging >= 2; $fh = $fh_cache{$what} ||= tempfile; seek $fh, 0, 0; truncate $fh, 0; } if ( is_win32 ) { warn "binmode()ing $what\n" if debugging && $binmode_it; binmode $fh, ":raw"; binmode $fh, ":crlf" unless $binmode_it; } return $fh; } sub _read_child_output_fh { my ( $what, $type, $dest, $fh, $options ) = @_; return if $type eq "SCALAR" && $dest == \undef; seek $fh, 0, 0 or croak "$! seeking on temp file for child $what"; if ( $type eq "SCALAR" ) { warn "run3(): reading child $what to SCALAR\n" if debugging >= 3; # two read()s are used instead of 1 so that the first will be # logged even it reads 0 bytes; the second won't. my $count = read $fh, $$dest, 10_000; while (1) { croak "$! reading child $what from temp file" unless defined $count; last unless $count; warn "run3(): read $count bytes from child $what", debugging >= 3 ? ( ": '", substr( $$dest, -$count ), "'" ) : (), "\n" if debugging >= 2; $count = read $fh, $$dest, 10_000, length $$dest; } } elsif ( $type eq "ARRAY" ) { @$dest = <$fh>; if ( debugging >= 2 ) { my $count = 0; $count += length for @$dest; warn "run3(): read ", scalar @$dest, " records, $count bytes from child $what", debugging >= 3 ? ( ": '", @$dest, "'" ) : (), "\n"; } } elsif ( $type eq "CODE" ) { warn "run3(): capturing child $what to CODE ref\n" if debugging >= 3; local $_; while ( <$fh> ) { warn "run3(): read ", length, " bytes from child $what", debugging >= 3 ? ( ": '", $_, "'" ) : (), "\n" if debugging >= 2; $dest->( $_ ); } } else { croak "run3() can't redirect child $what to a $type"; } } sub _type { my ( $redir ) = @_; return "FH" if eval { $redir->isa("IO::Handle") }; my $type = ref $redir; return $type eq "GLOB" ? "FH" : $type; } sub _max_fd { my $fd = dup(0); POSIX::close $fd; return $fd; } my $run_call_time; my $sys_call_time; my $sys_exit_time; sub run3 { $run_call_time = gettimeofday() if profiling; my $options = @_ && ref $_[-1] eq "HASH" ? pop : {}; my ( $cmd, $stdin, $stdout, $stderr ) = @_; print STDERR "run3(): running ", join( " ", map "'$_'", ref $cmd ? @$cmd : $cmd ), "\n" if debugging; if ( ref $cmd ) { croak "run3(): empty command" unless @$cmd; croak "run3(): undefined command" unless defined $cmd->[0]; croak "run3(): command name ('')" unless length $cmd->[0]; } else { croak "run3(): missing command" unless @_; croak "run3(): undefined command" unless defined $cmd; croak "run3(): command ('')" unless length $cmd; } my $in_type = _type $stdin; my $out_type = _type $stdout; my $err_type = _type $stderr; if ($fh_cache_pid != $$) { # fork detected, close all cached filehandles and clear the cache close $_ foreach values %fh_cache; %fh_cache = (); $fh_cache_pid = $$; } # This routine procedes in stages so that a failure in an early # stage prevents later stages from running, and thus from needing # cleanup. my $in_fh = _spool_data_to_child $in_type, $stdin, $options->{binmode_stdin} if defined $stdin; my $out_fh = _fh_for_child_output "stdout", $out_type, $stdout, $options->{binmode_stdout} if defined $stdout; my $tie_err_to_out = defined $stderr && defined $stdout && $stderr eq $stdout; my $err_fh = $tie_err_to_out ? $out_fh : _fh_for_child_output "stderr", $err_type, $stderr, $options->{binmode_stderr} if defined $stderr; # this should make perl close these on exceptions local *STDIN_SAVE; local *STDOUT_SAVE; local *STDERR_SAVE; my $saved_fd0 = dup( 0 ) if defined $in_fh; # open STDIN_SAVE, "<&STDIN"# or croak "run3(): $! saving STDIN" # if defined $in_fh; open STDOUT_SAVE, ">&STDOUT" or croak "run3(): $! saving STDOUT" if defined $out_fh; open STDERR_SAVE, ">&STDERR" or croak "run3(): $! saving STDERR" if defined $err_fh; my $ok = eval { # The open() call here seems to not force fd 0 in some cases; # I ran in to trouble when using this in VCP, not sure why. # the dup2() seems to work. dup2( fileno $in_fh, 0 ) # open STDIN, "<&=" . fileno $in_fh or croak "run3(): $! redirecting STDIN" if defined $in_fh; # close $in_fh or croak "$! closing STDIN temp file" # if ref $stdin; open STDOUT, ">&" . fileno $out_fh or croak "run3(): $! redirecting STDOUT" if defined $out_fh; open STDERR, ">&" . fileno $err_fh or croak "run3(): $! redirecting STDERR" if defined $err_fh; $sys_call_time = gettimeofday() if profiling; my $r = ref $cmd ? system { $cmd->[0] } is_win32 ? map { # Probably need to offer a win32 escaping # option, every command may be different. ( my $s = $_ ) =~ s/"/"""/g; $s = qq{"$s"}; $s; } @$cmd : @$cmd : system $cmd; $sys_exit_time = gettimeofday() if profiling; unless ( defined $r && $r != -1 ) { if ( debugging ) { my $err_fh = defined $err_fh ? \*STDERR_SAVE : \*STDERR; print $err_fh "run3(): system() error $!\n" } die $!; } if ( debugging ) { my $err_fh = defined $err_fh ? \*STDERR_SAVE : \*STDERR; print $err_fh "run3(): \$? is $?\n" } 1; }; my $x = $@; my @errs; if ( defined $saved_fd0 ) { dup2( $saved_fd0, 0 ); POSIX::close( $saved_fd0 ); } # open STDIN, "<&STDIN_SAVE"# or push @errs, "run3(): $! restoring STDIN" # if defined $in_fh; open STDOUT, ">&STDOUT_SAVE" or push @errs, "run3(): $! restoring STDOUT" if defined $out_fh; open STDERR, ">&STDERR_SAVE" or push @errs, "run3(): $! restoring STDERR" if defined $err_fh; croak join ", ", @errs if @errs; die $x unless $ok; _read_child_output_fh "stdout", $out_type, $stdout, $out_fh, $options if defined $out_fh && $out_type && $out_type ne "FH"; _read_child_output_fh "stderr", $err_type, $stderr, $err_fh, $options if defined $err_fh && $err_type && $err_type ne "FH" && !$tie_err_to_out; $profiler->run_exit( $cmd, $run_call_time, $sys_call_time, $sys_exit_time, scalar gettimeofday() ) if profiling; return 1; } =head1 TODO pty support =head1 LIMITATIONS Often uses intermediate files (determined by File::Temp, and thus by the File::Spec defaults and the TMPDIR env. variable) for speed, portability and simplicity. Use extrem caution when using C in a threaded environment if concurrent calls of C are possible. Most likely, I/O from different invocations will get mixed up. The reason is that in most thread implementations all threads in a process share the same STDIN/STDOUT/STDERR. Known failures are Perl ithreads on Linux and Win32. Note that C on Win32 is emulated via Win32 threads and hence I/O mix up is possible between forked children here (C is "fork safe" on Unix, though). =head1 COPYRIGHT Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved =head1 LICENSE You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version. =head1 AUTHOR Barrie Slaymaker ECE Ricardo SIGNES ECE performed some routine maintenance in 2005, thanks to help from the following ticket and/or patch submitters: Jody Belka, Roderich Schupp, David Morel, and anonymous others. =cut 1; EekBoek-2.02.04/inc/Module/0000755000175000017500000000000012165465617014223 5ustar thijsthijsEekBoek-2.02.04/inc/Module/Build.pm0000444000175000017500000010312712165465617015622 0ustar thijsthijspackage Module::Build; # This module doesn't do much of anything itself, it inherits from the # modules that do the real work. The only real thing it has to do is # figure out which OS-specific module to pull in. Many of the # OS-specific modules don't do anything either - most of the work is # done in Module::Build::Base. use strict; use File::Spec (); use File::Path (); use File::Basename (); use Module::Build::Base; use vars qw($VERSION @ISA); @ISA = qw(Module::Build::Base); $VERSION = '0.32'; $VERSION = eval $VERSION; # Okay, this is the brute-force method of finding out what kind of # platform we're on. I don't know of a systematic way. These values # came from the latest (bleadperl) perlport.pod. my %OSTYPES = qw( aix Unix bsdos Unix dgux Unix dragonfly Unix dynixptx Unix freebsd Unix linux Unix haiku Unix hpux Unix irix Unix darwin Unix machten Unix midnightbsd Unix mirbsd Unix next Unix openbsd Unix netbsd Unix dec_osf Unix nto Unix svr4 Unix svr5 Unix sco_sv Unix unicos Unix unicosmk Unix solaris Unix sunos Unix cygwin Unix os2 Unix interix Unix gnu Unix gnukfreebsd Unix dos Windows MSWin32 Windows os390 EBCDIC os400 EBCDIC posix-bc EBCDIC vmesa EBCDIC MacOS MacOS VMS VMS VOS VOS riscos RiscOS amigaos Amiga mpeix MPEiX ); # Inserts the given module into the @ISA hierarchy between # Module::Build and its immediate parent sub _interpose_module { my ($self, $mod) = @_; eval "use $mod"; die $@ if $@; no strict 'refs'; my $top_class = $mod; while (@{"${top_class}::ISA"}) { last if ${"${top_class}::ISA"}[0] eq $ISA[0]; $top_class = ${"${top_class}::ISA"}[0]; } @{"${top_class}::ISA"} = @ISA; @ISA = ($mod); } if (grep {-e File::Spec->catfile($_, qw(Module Build Platform), $^O) . '.pm'} @INC) { __PACKAGE__->_interpose_module("Module::Build::Platform::$^O"); } elsif (exists $OSTYPES{$^O}) { __PACKAGE__->_interpose_module("Module::Build::Platform::$OSTYPES{$^O}"); } else { warn "Unknown OS type '$^O' - using default settings\n"; } sub os_type { $OSTYPES{$^O} } sub is_vmsish { return ((os_type() || '') eq 'VMS') } sub is_windowsish { return ((os_type() || '') eq 'Windows') } sub is_unixish { return ((os_type() || '') eq 'Unix') } 1; __END__ =head1 NAME Module::Build - Build and install Perl modules =head1 SYNOPSIS Standard process for building & installing modules: perl Build.PL ./Build ./Build test ./Build install Or, if you're on a platform (like DOS or Windows) that doesn't require the "./" notation, you can do this: perl Build.PL Build Build test Build install =head1 DESCRIPTION C is a system for building, testing, and installing Perl modules. It is meant to be an alternative to C. Developers may alter the behavior of the module through subclassing in a much more straightforward way than with C. It also does not require a C on your system - most of the C code is pure-perl and written in a very cross-platform way. In fact, you don't even need a shell, so even platforms like MacOS (traditional) can use it fairly easily. Its only prerequisites are modules that are included with perl 5.6.0, and it works fine on perl 5.005 if you can install a few additional modules. See L<"MOTIVATIONS"> for more comparisons between C and C. To install C, and any other module that uses C for its installation process, do the following: perl Build.PL # 'Build.PL' script creates the 'Build' script ./Build # Need ./ to ensure we're using this "Build" script ./Build test # and not another one that happens to be in the PATH ./Build install This illustrates initial configuration and the running of three 'actions'. In this case the actions run are 'build' (the default action), 'test', and 'install'. Other actions defined so far include: build manpages clean pardist code ppd config_data ppmdist diff prereq_data dist prereq_report distcheck pure_install distclean realclean distdir retest distmeta skipcheck distsign test disttest testall docs testcover fakeinstall testdb help testpod html testpodcoverage install versioninstall manifest You can run the 'help' action for a complete list of actions. =head1 GUIDE TO DOCUMENTATION The documentation for C is broken up into three sections: =over =item General Usage (L) This is the document you are currently reading. It describes basic usage and background information. Its main purpose is to assist the user who wants to learn how to invoke and control C scripts at the command line. =item Authoring Reference (L) This document describes the structure and organization of C, and the relevant concepts needed by authors who are writing F scripts for a distribution or controlling C processes programmatically. =item API Reference (L) This is a reference to the C API. =item Cookbook (L) This document demonstrates how to accomplish many common tasks. It covers general command line usage and authoring of F scripts. Includes working examples. =back =head1 ACTIONS There are some general principles at work here. First, each task when building a module is called an "action". These actions are listed above; they correspond to the building, testing, installing, packaging, etc., tasks. Second, arguments are processed in a very systematic way. Arguments are always key=value pairs. They may be specified at C time (i.e. C), in which case their values last for the lifetime of the C script. They may also be specified when executing a particular action (i.e. C), in which case their values last only for the lifetime of that command. Per-action command line parameters take precedence over parameters specified at C time. The build process also relies heavily on the C module. If the user wishes to override any of the values in C, she may specify them like so: perl Build.PL --config cc=gcc --config ld=gcc The following build actions are provided by default. =over 4 =item build [version 0.01] If you run the C script without any arguments, it runs the C action, which in turn runs the C and C actions. This is analogous to the MakeMaker 'make all' target. =item clean [version 0.01] This action will clean up any files that the build process may have created, including the C directory (but not including the C<_build/> directory and the C script itself). =item code [version 0.20] This action builds your codebase. By default it just creates a C directory and copies any C<.pm> and C<.pod> files from your C directory into the C directory. It also compiles any C<.xs> files from C and places them in C. Of course, you need a working C compiler (probably the same one that built perl itself) for the compilation to work properly. The C action also runs any C<.PL> files in your F directory. Typically these create other files, named the same but without the C<.PL> ending. For example, a file F could create the file F. The C<.PL> files are processed first, so any C<.pm> files (or other kinds that we deal with) will get copied correctly. =item config_data [version 0.26] ... =item diff [version 0.14] This action will compare the files about to be installed with their installed counterparts. For .pm and .pod files, a diff will be shown (this currently requires a 'diff' program to be in your PATH). For other files like compiled binary files, we simply report whether they differ. A C parameter may be passed to the action, which will be passed to the 'diff' program. Consult your 'diff' documentation for the parameters it will accept - a good one is C<-u>: ./Build diff flags=-u =item dist [version 0.02] This action is helpful for module authors who want to package up their module for source distribution through a medium like CPAN. It will create a tarball of the files listed in F and compress the tarball using GZIP compression. By default, this action will use the external C and C executables on Unix-like platforms, and the C module elsewhere. However, you can force it to use whatever executable you want by supplying an explicit C (and optional C) parameter: ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe =item distcheck [version 0.05] Reports which files are in the build directory but not in the F file, and vice versa. (See L for details.) =item distclean [version 0.05] Performs the 'realclean' action and then the 'distcheck' action. =item distdir [version 0.05] Creates a "distribution directory" named C<$dist_name-$dist_version> (if that directory already exists, it will be removed first), then copies all the files listed in the F file to that directory. This directory is what the distribution tarball is created from. =item distmeta [version 0.21] Creates the F file that describes the distribution. F is a file containing various bits of "metadata" about the distribution. The metadata includes the distribution name, version, abstract, prerequisites, license, and various other data about the distribution. This file is created as F in YAML format. It is recommended that the C module be installed to create it. If the C module is not installed, an internal module supplied with Module::Build will be used to write the META.yml file, and this will most likely be fine. F file must also be listed in F - if it's not, a warning will be issued. The current version of the F specification can be found at L =item distsign [version 0.16] Uses C to create a SIGNATURE file for your distribution, and adds the SIGNATURE file to the distribution's MANIFEST. =item disttest [version 0.05] Performs the 'distdir' action, then switches into that directory and runs a C, followed by the 'build' and 'test' actions in that directory. =item docs [version 0.20] This will generate documentation (e.g. Unix man pages and html documents) for any installable items under B that contain POD. If there are no C or C installation targets defined (as will be the case on systems that don't support Unix manpages) no action is taken for manpages. If there are no C or C installation targets defined no action is taken for html documents. =item fakeinstall [version 0.02] This is just like the C action, but it won't actually do anything, it will just report what it I have done if you had actually run the C action. =item help [version 0.03] This action will simply print out a message that is meant to help you use the build process. It will show you a list of available build actions too. With an optional argument specifying an action name (e.g. C), the 'help' action will show you any POD documentation it can find for that action. =item html [version 0.26] This will generate HTML documentation for any binary or library files under B that contain POD. The HTML documentation will only be installed if the install paths can be determined from values in C. You can also supply or override install paths on the command line by specifying C values for the C and/or C installation targets. =item install [version 0.01] This action will use C to install the files from C into the system. See L<"INSTALL PATHS"> for details about how Module::Build determines where to install things, and how to influence this process. If you want the installation process to look around in C<@INC> for other versions of the stuff you're installing and try to delete it, you can use the C parameter, which tells C to do so: ./Build install uninst=1 This can be a good idea, as it helps prevent multiple versions of a module from being present on your system, which can be a confusing situation indeed. =item manifest [version 0.05] This is an action intended for use by module authors, not people installing modules. It will bring the F up to date with the files currently present in the distribution. You may use a F file to exclude certain files or directories from inclusion in the F. F should contain a bunch of regular expressions, one per line. If a file in the distribution directory matches any of the regular expressions, it won't be included in the F. The following is a reasonable F starting point, you can add your own stuff to it: ^_build ^Build$ ^blib ~$ \.bak$ ^MANIFEST\.SKIP$ CVS See the L and L actions if you want to find out what the C action would do, without actually doing anything. =item manpages [version 0.28] This will generate man pages for any binary or library files under B that contain POD. The man pages will only be installed if the install paths can be determined from values in C. You can also supply or override install paths by specifying there values on the command line with the C and C installation targets. =item pardist [version 0.2806] Generates a PAR binary distribution for use with L or L. It requires that the PAR::Dist module (version 0.17 and up) is installed on your system. =item ppd [version 0.20] Build a PPD file for your distribution. This action takes an optional argument C which is used in the generated ppd file to specify the (usually relative) URL of the distribution. By default, this value is the distribution name without any path information. Example: ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz" =item ppmdist [version 0.23] Generates a PPM binary distribution and a PPD description file. This action also invokes the 'ppd' action, so it can accept the same C argument described under that action. This uses the same mechanism as the C action to tar & zip its output, so you can supply C and/or C parameters to affect the result. =item prereq_data [version 0.32] This action prints out a Perl data structure of all prerequsites and the versions required. The output can be loaded again using C. This can be useful for external tools that wish to query a Build script for prerequisites. =item prereq_report [version 0.28] This action prints out a list of all prerequisites, the versions required, and the versions actually installed. This can be useful for reviewing the configuration of your system prior to a build, or when compiling data to send for a bug report. =item pure_install [version 0.28] This action is identical to the C action. In the future, though, when C starts writing to the file F<$(INSTALLARCHLIB)/perllocal.pod>, C won't, and that will be the only difference between them. =item realclean [version 0.01] This action is just like the C action, but also removes the C<_build> directory and the C script. If you run the C action, you are essentially starting over, so you will have to re-create the C script again. =item retest [version 0.2806] This is just like the C action, but doesn't actually build the distribution first, and doesn't add F to the load path, and therefore will test against a I installed version of the distribution. This can be used to verify that a certain installed distribution still works, or to see whether newer versions of a distribution still pass the old regression tests, and so on. =item skipcheck [version 0.05] Reports which files are skipped due to the entries in the F file (See L for details) =item test [version 0.01] This will use C or C to run any regression tests and report their results. Tests can be defined in the standard places: a file called C in the top-level directory, or several files ending with C<.t> in a C directory. If you want tests to be 'verbose', i.e. show details of test execution rather than just summary information, pass the argument C. If you want to run tests under the perl debugger, pass the argument C. If you want to have Module::Build find test files with different file name extensions, pass the C argument with an array of extensions, such as C<[qw( .t .s .z )]>. If you want test to be run by C, rather than C, pass the argument C as an array reference of arguments to pass to the TAP::Harness constructor. In addition, if a file called C exists in the top-level directory, this file will be executed as a Perl script and its output will be shown to the user. This is a good place to put speed tests or other tests that don't use the C format for output. To override the choice of tests to run, you may pass a C argument whose value is a whitespace-separated list of test scripts to run. This is especially useful in development, when you only want to run a single test to see whether you've squashed a certain bug yet: ./Build test --test_files t/something_failing.t You may also pass several C arguments separately: ./Build test --test_files t/one.t --test_files t/two.t or use a C-style pattern: ./Build test --test_files 't/01-*.t' =item testall [verion 0.2807] [Note: the 'testall' action and the code snippets below are currently in alpha stage, see L<"http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html"> ] Runs the C action plus each of the C actions defined by the keys of the C parameter. Currently, you need to define the ACTION_test$type method yourself and enumerate them in the test_types parameter. my $mb = Module::Build->subclass( code => q( sub ACTION_testspecial { shift->generic_test(type => 'special'); } sub ACTION_testauthor { shift->generic_test(type => 'author'); } ) )->new( ... test_types => { special => '.st', author => ['.at', '.pt' ], }, ... =item testcover [version 0.26] Runs the C action using C, generating a code-coverage report showing which parts of the code were actually exercised during the tests. To pass options to C, set the C<$DEVEL_COVER_OPTIONS> environment variable: DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover =item testdb [version 0.05] This is a synonym for the 'test' action with the C argument. =item testpod [version 0.25] This checks all the files described in the C action and produces C-style output. If you are a module author, this is useful to run before creating a new release. =item testpodcoverage [version 0.28] This checks the pod coverage of the distribution and produces C-style output. If you are a module author, this is useful to run before creating a new release. =item versioninstall [version 0.16] ** Note: since C is so new, and since we just recently added support for it here too, this feature is to be considered experimental. ** If you have the C module installed on your system, you can use this action to install a module into the version-specific library trees. This means that you can have several versions of the same module installed and C a specific one like this: use only MyModule => 0.55; To override the default installation libraries in C, specify the C parameter when you run the C script: perl Build.PL --versionlib /my/version/place/ To override which version the module is installed as, specify the C parameter when you run the C script: perl Build.PL --version 0.50 See the C documentation for more information on version-specific installs. =back =head1 OPTIONS =head2 Command Line Options The following options can be used during any invocation of C or the Build script, during any action. For information on other options specific to an action, see the documentation for the respective action. NOTE: There is some preliminary support for options to use the more familiar long option style. Most options can be preceded with the C<--> long option prefix, and the underscores changed to dashes (e.g. --use-rcfile). Additionally, the argument to boolean options is optional, and boolean options can be negated by prefixing them with 'no' or 'no-' (e.g. --noverbose or --no-verbose). =over 4 =item quiet Suppress informative messages on output. =item use_rcfile Load the F<~/.modulebuildrc> option file. This option can be set to false to prevent the custom resource file from being loaded. =item verbose Display extra information about the Build on output. =item allow_mb_mismatch Suppresses the check upon startup that the version of Module::Build we're now running under is the same version that was initially invoked when building the distribution (i.e. when the C script was first run). Use with caution. =back =head2 Default Options File (F<.modulebuildrc>) [version 0.28] When Module::Build starts up, it will look first for a file, F<$ENV{HOME}/.modulebuildrc>. If it's not found there, it will look in the the F<.modulebuildrc> file in the directories referred to by the environment variables C + C, C, C, C, C. If the file exists, the options specified there will be used as defaults, as if they were typed on the command line. The defaults can be overridden by specifying new values on the command line. The action name must come at the beginning of the line, followed by any amount of whitespace and then the options. Options are given the same as they would be on the command line. They can be separated by any amount of whitespace, including newlines, as long there is whitespace at the beginning of each continued line. Anything following a hash mark (C<#>) is considered a comment, and is stripped before parsing. If more than one line begins with the same action name, those lines are merged into one set of options. Besides the regular actions, there are two special pseudo-actions: the key C<*> (asterisk) denotes any global options that should be applied to all actions, and the key 'Build_PL' specifies options to be applied when you invoke C. * verbose=1 # global options diff flags=-u install --install_base /home/ken --install_path html=/home/ken/docs/html If you wish to locate your resource file in a different location, you can set the environment variable 'MODULEBUILDRC' to the complete absolute path of the file containing your options. =head1 INSTALL PATHS [version 0.19] When you invoke Module::Build's C action, it needs to figure out where to install things. The nutshell version of how this works is that default installation locations are determined from F, and they may be overridden by using the C parameter. An C parameter lets you specify an alternative installation root like F, and a C lets you specify a temporary installation directory like F in case you want to create bundled-up installable packages. Natively, Module::Build provides default installation locations for the following types of installable items: =over 4 =item lib Usually pure-Perl module files ending in F<.pm>. =item arch "Architecture-dependent" module files, usually produced by compiling XS, Inline, or similar code. =item script Programs written in pure Perl. In order to improve reuse, try to make these as small as possible - put the code into modules whenever possible. =item bin "Architecture-dependent" executable programs, i.e. compiled C code or something. Pretty rare to see this in a perl distribution, but it happens. =item bindoc Documentation for the stuff in C