Alien-ROOT
view release on metacpan or search on metacpan
use lib 'inc';
use Alien::ROOT::Builder;
use Env '@PATH';
use Getopt::Long qw/GetOptions/;
Getopt::Long::Configure('pass_through', 'permute', 'no_require_order');
our $USER_CONFIG = {
archive => 'root_v5.34.36.source.tar.gz',
parallel_processes => 1,
force_recompile => 0,
};
GetOptions(
'j|parallel=i' => \($USER_CONFIG->{parallel_processes}),
'archive=s' => \($USER_CONFIG->{archive}),
'recompile' => \($USER_CONFIG->{force_recompile}),
);
my $builder = Alien::ROOT::Builder->new(
module_name => 'Alien::ROOT',
license => 'gpl',
dist_author => 'Steffen Mueller <smueller@cpan.org>',
dist_version_from => 'lib/Alien/ROOT.pm',
inc/Alien/ROOT/Builder.pm view on Meta::CPAN
my $dir = $self->notes('build_data')->{directory};
chdir $dir;
$ENV{PWD} = Cwd::cwd();
# do not reconfigure unless necessary
if (not -f 'config.status') {
system(@cmd) and die "Build failed while running '@cmd': $?";
}
my $make = $self->notes('make');
my $parallel_procs = $self->notes('build_data')->{parallel_processes};
if (defined $parallel_procs and $parallel_procs > 1) {
system($make, "-j$parallel_procs")
and die "Build failed while running '$make -j$parallel_procs': $?";
}
else {
system($make) and die "Build failed while running '$make': $?";
}
chdir $ORIG_DIR;
}
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
# run original signal handler if any (including aliased)
#
if (ref($previous_handler)) {
$previous_handler->($called_sig_name, @sig_param);
}
};
$SIG{$s} = $sig_handler;
}
# give process a chance sending TERM,
# waiting for a while (2 seconds)
# and killing it with KILL
sub kill_gently {
my ($pid, $opts) = @_;
require POSIX;
$opts = {} unless $opts;
$opts->{'wait_time'} = 2 unless defined($opts->{'wait_time'});
$opts->{'first_kill_type'} = 'just_process' unless $opts->{'first_kill_type'};
$opts->{'final_kill_type'} = 'just_process' unless $opts->{'final_kill_type'};
if ($opts->{'first_kill_type'} eq 'just_process') {
kill(15, $pid);
}
elsif ($opts->{'first_kill_type'} eq 'process_group') {
kill(-15, $pid);
}
my $child_finished = 0;
my $wait_start_time = time();
while (!$child_finished && $wait_start_time + $opts->{'wait_time'} > time()) {
my $waitpid = waitpid($pid, POSIX::WNOHANG);
if ($waitpid eq -1) {
$child_finished = 1;
}
Time::HiRes::usleep(250000); # quarter of a second
}
if (!$child_finished) {
if ($opts->{'final_kill_type'} eq 'just_process') {
kill(9, $pid);
}
elsif ($opts->{'final_kill_type'} eq 'process_group') {
kill(-9, $pid);
}
}
}
sub open3_run {
my ($cmd, $opts) = @_;
$opts = {} unless $opts;
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
# so in case i am killed parent
# could stop my child (search for
# child_child_pid in parent code)
if ($opts->{'parent_info'}) {
my $ps = $opts->{'parent_info'};
print $ps "spawned $pid\n";
}
if ($child_in && $child_out->opened && $opts->{'child_stdin'}) {
# If the child process dies for any reason,
# the next write to CHLD_IN is likely to generate
# a SIGPIPE in the parent, which is fatal by default.
# So you may wish to handle this signal.
#
# from http://perldoc.perl.org/IPC/Open3.html,
# absolutely needed to catch piped commands errors.
#
local $SIG{'PIPE'} = sub { 1; };
print $child_in $opts->{'child_stdin'};
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
'scalar_buffer' => "",
'child_handle' => $child_err,
'block_size' => ($child_err->stat)[11] || 1024,
},
};
my $select = IO::Select->new();
$select->add($child_out, $child_err);
# pass any signal to the child
# effectively creating process
# strongly attached to the child:
# it will terminate only after child
# has terminated (except for SIGKILL,
# which is specially handled)
foreach my $s (keys %SIG) {
my $sig_handler;
$sig_handler = sub {
kill("$s", $pid);
$SIG{$s} = $sig_handler;
};
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
}
my $child_finished = 0;
my $got_sig_child = 0;
$SIG{'CHLD'} = sub { $got_sig_child = time(); };
while(!$child_finished && ($child_out->opened || $child_err->opened)) {
# parent was killed otherwise we would have got
# the same signal as parent and process it same way
if (getppid() eq "1") {
# end my process group with all the children
# (i am the process group leader, so my pid
# equals to the process group id)
#
# same thing which is done
# with $opts->{'clean_up_children'}
# in run_forked
#
kill(-9, $$);
POSIX::_exit 1;
}
if ($got_sig_child) {
if (time() - $got_sig_child > 1) {
# select->can_read doesn't return 0 after SIG_CHLD
#
# "On POSIX-compliant platforms, SIGCHLD is the signal
# sent to a process when a child process terminates."
# http://en.wikipedia.org/wiki/SIGCHLD
#
# nevertheless kill KILL wouldn't break anything here
#
kill (9, $pid);
$child_finished = 1;
}
}
Time::HiRes::usleep(1);
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
that the program which you're spawning
might spawn some children itself (which
in their turn could do the same and so on)
it turns out to be not a simple issue.
C<run_forked> is designed to survive and
successfully terminate almost any long running task,
even a fork bomb in case your system has the resources
to survive during given timeout.
This is achieved by creating separate watchdog process
which spawns the specified program in a separate
process session and supervises it: optionally
feeds it with input, stores its exit code,
stdout and stderr, terminates it in case
it runs longer than specified.
Invocation requires the command to be executed or a coderef and optionally a hashref of options:
=over
=item C<timeout>
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
=item C<discard_output>
Discards the buffering of the standard output and standard errors for return by run_forked().
With this option you have to use the std*_handlers to read what the command outputs.
Useful for commands that send a lot of output.
=item C<terminate_on_parent_sudden_death>
Enable this option if you wish all spawned processes to be killed if the initially spawned
process (the parent) is killed or dies without waiting for child processes.
=back
C<run_forked> will return a HASHREF with the following keys:
=over
=item C<exit_code>
The exit code of the executed program.
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
my $now = time();
if ($opts->{'terminate_on_parent_sudden_death'}) {
$opts->{'runtime'}->{'last_parent_check'} = 0
unless defined($opts->{'runtime'}->{'last_parent_check'});
# check for parent once each five seconds
if ($now - $opts->{'runtime'}->{'last_parent_check'} > 5) {
if (getppid() eq "1") {
kill_gently ($pid, {
'first_kill_type' => 'process_group',
'final_kill_type' => 'process_group',
'wait_time' => $opts->{'terminate_wait_time'}
});
$parent_died = 1;
}
$opts->{'runtime'}->{'last_parent_check'} = $now;
}
}
# user specified timeout
if ($opts->{'timeout'}) {
if ($now - $start_time > $opts->{'timeout'}) {
kill_gently ($pid, {
'first_kill_type' => 'process_group',
'final_kill_type' => 'process_group',
'wait_time' => $opts->{'terminate_wait_time'}
});
$child_timedout = 1;
}
}
# give OS 10 seconds for correct return of waitpid,
# kill process after that and finish wait loop;
# shouldn't ever happen -- remove this code?
if ($got_sig_child) {
if ($now - $got_sig_child > 10) {
print STDERR "waitpid did not return -1 for 10 seconds after SIG_CHLD, killing [$pid]\n";
kill (-9, $pid);
$child_finished = 1;
}
}
if ($got_sig_quit) {
kill_gently ($pid, {
'first_kill_type' => 'process_group',
'final_kill_type' => 'process_group',
'wait_time' => $opts->{'terminate_wait_time'}
});
$child_finished = 1;
}
my $waitpid = waitpid($pid, POSIX::WNOHANG);
# child finished, catch it's exit status
if ($waitpid ne 0 && $waitpid ne -1) {
$child_exit_code = $? >> 8;
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
#
# defined $child_pid_pid means child's child
# has not died but nobody is waiting for it,
# killing it brutally.
#
if ($child_child_pid) {
kill_gently($child_child_pid);
}
# in case there are forks in child which
# do not forward or process signals (TERM) correctly
# kill whole child process group, effectively trying
# not to return with some children or their parts still running
#
# to be more accurate -- we need to be sure
# that this is process group created by our child
# (and not some other process group with the same pgid,
# created just after death of our child) -- fortunately
# this might happen only when process group ids
# are reused quickly (there are lots of processes
# spawning new process groups for example)
#
if ($opts->{'clean_up_children'}) {
kill(-9, $pid);
}
# print "child $pid finished\n";
close($child_stdout_socket);
close($child_stderr_socket);
close($child_info_socket);
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
}
else {
delete($SIG{'CHLD'});
}
return $o;
}
else {
die("cannot fork: $!") unless defined($pid);
# create new process session for open3 call,
# so we hopefully can kill all the subprocesses
# which might be spawned in it (except for those
# which do setsid theirselves -- can't do anything
# with those)
POSIX::setsid() || die("Error running setsid: " . $!);
if ($opts->{'child_BEGIN'} && ref($opts->{'child_BEGIN'}) eq 'CODE') {
$opts->{'child_BEGIN'}->();
}
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
} else {
$self->_debug( "# Using system(). Have buffer: $have_buffer" )
if $DEBUG;
$ok = $self->_system_run( $cmd, $verbose );
}
alarm 0;
};
### restore STDIN after duping, or STDIN will be closed for
### this current perl process!
$self->__reopen_fds( @{ $self->_fds} ) if $self->_fds;
my $err;
unless( $ok ) {
### alarm happened
if ( $@ and ref $@ and $@->isa( ALARM_CLASS ) ) {
$err = $@->(); # the error code is an expired alarm
### another error happened, set by the dispatchub
} else {
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
### XXX that code didn't work.
### we now use the following code, thanks to theorbtwo
### define them beforehand, so we always have defined FH's
### to read from.
use Symbol;
my $kidout = Symbol::gensym();
my $kiderror = Symbol::gensym();
### Dup the filehandle so we can pass 'our' STDIN to the
### child process. This stops us from having to pump input
### from ourselves to the childprocess. However, we will need
### to revive the FH afterwards, as IPC::Open3 closes it.
### We'll do the same for STDOUT and STDERR. It works without
### duping them on non-unix derivatives, but not on win32.
my @fds_to_dup = ( IS_WIN32 && !$verbose
? qw[STDIN STDOUT STDERR]
: qw[STDIN]
);
$self->_fds( \@fds_to_dup );
$self->__dup_fds( @fds_to_dup );
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
for my $h ( @ready ) {
my $buf;
### $len is the amount of bytes read
my $len = sysread( $h, $buf, 4096 ); # try to read 4096 bytes
### see perldoc -f sysread: it returns undef on error,
### so bail out.
if( not defined $len ) {
warn(loc("Error reading from process: %1", $!));
last OUTER;
}
### check for $len. it may be 0, at which point we're
### done reading, so don't try to process it.
### if we would print anyway, we'd provide bogus information
$_out_handler->( "$buf" ) if $len && $h == $kidout;
$_err_handler->( "$buf" ) if $len && $h == $kiderror;
### Wait till child process is done printing to both
### stdout and stderr.
$stdout_done = 1 if $h == $kidout and $len == 0;
$stderr_done = 1 if $h == $kiderror and $len == 0;
last OUTER if ($stdout_done && $stderr_done);
}
}
waitpid $pid, 0; # wait for it to die
### restore STDIN after duping, or STDIN will be closed for
### this current perl process!
### done in the parent call now
# $self->__reopen_fds( @fds_to_dup );
### some error occurred
if( $? ) {
$self->error( $self->_pp_child_error( $cmd, $? ) );
$self->ok( 0 );
return;
} else {
return $self->ok( 1 );
inc/inc_IPC-Cmd/IPC/Cmd.pm view on Meta::CPAN
return $cmd;
}
}
### Command-line arguments (but not the command itself) must be quoted
### to ensure case preservation. Borrowed from Module::Build with adaptations.
### Patch for this supplied by Craig Berry, see RT #46288: [PATCH] Add argument
### quoting for run() on VMS
sub _quote_args_vms {
### Returns a command string with proper quoting so that the subprocess
### sees this same list of args, or if we get a single arg that is an
### array reference, quote the elements of it (except for the first)
### and return the reference.
my @args = @_;
my $got_arrayref = (scalar(@args) == 1
&& UNIVERSAL::isa($args[0], 'ARRAY'))
? 1
: 0;
@args = split(/\s+/, $args[0]) unless $got_arrayref || scalar(@args) > 1;
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
fakeinstall html installdirs installsitebin installsitescript installvendorbin
installvendorscript libdoc libhtml pardist ppd ppmdist realclean skipcheck
testall testcover testdb testpod testpodcoverage versioninstall
=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
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
- most of the C<Module::Build> 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<ExtUtils::MakeMaker>
and C<Module::Build>.
To install C<Module::Build>, and any other module that uses
C<Module::Build> 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:
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
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<Module::Build>
scripts at the command line.
=item Authoring Reference (L<Module::Build::Authoring>)
This document describes the structure and organization of
C<Module::Build>, and the relevant concepts needed by authors who are
writing F<Build.PL> scripts for a distribution or controlling
C<Module::Build> processes programmatically.
=item API Reference (L<Module::Build::API>)
This is a reference to the C<Module::Build> API.
=item Cookbook (L<Module::Build::Cookbook>)
This document demonstrates how to accomplish many common tasks. It
covers general command line usage and authoring of F<Build.PL>
scripts. Includes working examples.
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
=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<perl Build.PL>
time (i.e. C<perl Build.PL destdir=/my/secret/place>), in which case
their values last for the lifetime of the C<Build> script. They may
also be specified when executing a particular action (i.e.
C<Build test verbose=1>), 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<perl Build.PL> time.
The build process also relies heavily on the C<Config.pm> module.
If the user wishes to override any of the
values in C<Config.pm>, 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
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
If you run the C<Build> script without any arguments, it runs the
C<build> action, which in turn runs the C<code> and C<docs> actions.
This is analogous to the C<MakeMaker> I<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<blib/> directory (but not including the
C<_build/> directory and the C<Build> script itself).
=item code
[version 0.20]
This action builds your code base.
By default it just creates a C<blib/> directory and copies any C<.pm>
and C<.pod> files from your C<lib/> directory into the C<blib/>
directory. It also compiles any C<.xs> files from C<lib/> and places
them in C<blib/>. Of course, you need a working C compiler (probably
the same one that built perl itself) for the compilation to work
properly.
The C<code> action also runs any C<.PL> files in your F<lib/>
directory. Typically these create other files, named the same but
without the C<.PL> ending. For example, a file F<lib/Foo/Bar.pm.PL>
could create the file F<lib/Foo/Bar.pm>. 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
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
copies all the files listed in the F<MANIFEST> file to that directory.
This directory is what the distribution tarball is created from.
=item distinstall
[version 0.37]
Performs the 'distdir' action, then switches into that directory and runs a
C<perl Build.PL>, followed by the 'build' and 'install' actions in that
directory. Use PERL_MB_OPT or F<.modulebuildrc> to set options that should be
applied during subprocesses
=item distmeta
[version 0.21]
Creates the F<META.yml> file that describes the distribution.
F<META.yml> is a file containing various bits of I<metadata> about the
distribution. The metadata includes the distribution name, version,
abstract, prerequisites, license, and various other data about the
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
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<perl Build.PL>, followed by the 'build' and 'test' actions in that directory.
Use PERL_MB_OPT or F<.modulebuildrc> to set options that should be applied
during subprocesses
=item docs
[version 0.20]
This will generate documentation (e.g. Unix man pages and HTML
documents) for any installable items under B<blib/> that
contain POD. If there are no C<bindoc> or C<libdoc> installation
targets defined (as will be the case on systems that don't support
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
This is just like the C<install> action, but it won't actually do
anything, it will just report what it I<would> have done if you had
actually run the C<install> 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<Build help
test>), the 'help' action will show you any POD documentation it can
find for that action.
=item html
[version 0.26]
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
command line by specifying C<install_path> values for the C<binhtml>
and/or C<libhtml> installation targets.
=item install
[version 0.01]
This action will use C<ExtUtils::Install> to install the files from
C<blib/> 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<uninst> parameter, which tells C<ExtUtils::Install> 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.
inc/inc_Module-Build/Module/Build.pm view on Meta::CPAN
=head1 MOTIVATIONS
There are several reasons I wanted to start over, and not just fix
what I didn't like about C<MakeMaker>:
=over 4
=item *
I don't like the core idea of C<MakeMaker>, namely that C<make> should be
involved in the build process. Here are my reasons:
=over 4
=item +
When a person is installing a Perl module, what can you assume about
their environment? Can you assume they have C<make>? No, but you can
assume they have some version of Perl.
=item +
When a person is writing a Perl module for intended distribution, can
you assume that they know how to build a Makefile, so they can
customize their build process? No, but you can assume they know Perl,
and could customize that way.
=back
For years, these things have been a barrier to people getting the
build/install process to do what they want.
=item *
There are several architectural decisions in C<MakeMaker> that make it
very difficult to customize its behavior. For instance, when using
C<MakeMaker> you do C<use ExtUtils::MakeMaker>, but the object created in
C<WriteMakefile()> is actually blessed into a package name that's
created on the fly, so you can't simply subclass
C<ExtUtils::MakeMaker>. There is a workaround C<MY> package that lets
you override certain C<MakeMaker> methods, but only certain explicitly
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
=over 4
=item current()
[version 0.20]
This method returns a reasonable facsimile of the currently-executing
C<Module::Build> object representing the current build. You can use
this object to query its L</notes()> method, inquire about installed
modules, and so on. This is a great way to share information between
different parts of your build process. For instance, you can ask
the user a question during C<perl Build.PL>, then use their answer
during a regression test:
# In Build.PL:
my $color = $build->prompt("What is your favorite color?");
$build->notes(color => $color);
# In t/colortest.t:
use Module::Build;
my $build = Module::Build->current;
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
to set it to a reasonable default.
The version is extracted from the specified file according to the same
rules as L<ExtUtils::MakeMaker> and C<CPAN.pm>. It involves finding
the first line that matches the regular expression
/([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
eval()-ing that line, then checking the value of the C<$VERSION>
variable. Quite ugly, really, but all the modules on CPAN depend on
this process, so there's no real opportunity to change to something
better.
If the target file of L</dist_version_from> contains more than one package
declaration, the version returned will be the one matching the configured
L</module_name>.
=item dynamic_config
[version 0.07]
A boolean flag indicating whether the F<Build.PL> file must be
executed, or whether this module can be built, tested and installed
solely from consulting its metadata file. The main reason to set this
to a true value is that your module performs some dynamic
configuration as part of its build/install process. If the flag is
omitted, the F<META.yml> spec says that installation tools should
treat it as 1 (true), because this is a safer way to behave.
Currently C<Module::Build> doesn't actually do anything with this flag
- it's up to higher-level tools like C<CPAN.pm> to do something useful
with it. It can potentially bring lots of security, packaging, and
convenience improvements.
=item extra_compiler_flags
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
extra_linker_flags => scalar `glib-config --libs`,
);
=item get_options
[version 0.26]
You can pass arbitrary command line options to F<Build.PL> or
F<Build>, and they will be stored in the Module::Build object and can
be accessed via the L</args()> method. However, sometimes you want
more flexibility out of your argument processing than this allows. In
such cases, use the C<get_options> parameter to pass in a hash
reference of argument specifications, and the list of arguments to
F<Build.PL> or F<Build> will be processed according to those
specifications before they're passed on to C<Module::Build>'s own
argument processing.
The supported option specification hash keys are:
=over 4
=item type
The type of option. The types are those supported by Getopt::Long; consult
its documentation for a complete list. Typical types are C<=s> for strings,
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
L<ExtUtils::CBuilder> is automatically added to C<build_requires> if needed.
For a distribution where a compiler is I<optional>, e.g. a dual XS/pure-Perl
distribution, C<needs_compiler> should explicitly be set to a false value.
=item PL_files
[version 0.06]
An optional parameter specifying a set of C<.PL> files in your
distribution. These will be run as Perl scripts prior to processing
the rest of the files in your distribution with the name of the file
they're generating as an argument. They are usually used as templates
for creating other files dynamically, so that a file like
C<lib/Foo/Bar.pm.PL> might create the file C<lib/Foo/Bar.pm>.
The files are specified with the C<.PL> files as hash keys, and the
file(s) they generate as hash values, like so:
my $build = Module::Build->new
(
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
=head2 METHODS
=over 4
=item add_build_element($type)
[version 0.26]
Adds a new type of entry to the build process. Accepts a single
string specifying its type-name. There must also be a method defined
to process things of that type, e.g. if you add a build element called
C<'foo'>, then you must also define a method called
C<process_foo_files()>.
See also
L<Module::Build::Cookbook/"Adding new file types to the build process">.
=item add_to_cleanup(@files)
[version 0.03]
You may call C<< $self->add_to_cleanup(@patterns) >> to tell
C<Module::Build> that certain files should be removed when the user
performs the C<Build clean> action. The arguments to the method are
patterns suitable for passing to Perl's C<glob()> function, specified
in either Unix format or the current machine's native format. It's
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
With a single argument, returns the value of the configuration
variable C<$name>. With two arguments, sets the given configuration
variable to the given value. The value may be any Perl scalar that's
serializable with C<Data::Dumper>. For instance, if you write a
module that can use a MySQL or PostgreSQL back-end, you might create
configuration variables called C<mysql_connect> and
C<postgres_connect>, and set each to an array of connection parameters
for C<< DBI->connect() >>.
Configuration values set in this way using the Module::Build object
will be available for querying during the build/test process and after
installation via the generated C<...::ConfigData> module, as
C<< ...::ConfigData->config($name) >>.
The L<feature()|/"feature($name)"> and C<config_data()> methods represent
Module::Build's main support for configuration of installed modules.
See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
=item conflicts()
[version 0.21]
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
[version 0.21]
This is a fairly simple wrapper around Perl's C<system()> built-in
command. Given a command and an array of optional arguments, this
method will print the command to C<STDOUT>, and then execute it using
Perl's C<system()>. It returns true or false to indicate success or
failure (the opposite of how C<system()> works, but more intuitive).
Note that if you supply a single argument to C<do_system()>, it
will/may be processed by the system's shell, and any special
characters will do their special things. If you supply multiple
arguments, no shell will get involved and the command will be executed
directly.
=item extra_compiler_flags()
=item extra_compiler_flags(@flags)
[version 0.25]
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
With a single argument, returns true if the given feature is set.
With two arguments, sets the given feature to the given boolean value.
In this context, a "feature" is any optional functionality of an
installed module. For instance, if you write a module that could
optionally support a MySQL or PostgreSQL backend, you might create
features called C<mysql_support> and C<postgres_support>, and set them
to true/false depending on whether the user has the proper databases
installed and configured.
Features set in this way using the Module::Build object will be
available for querying during the build/test process and after
installation via the generated C<...::ConfigData> module, as
C<< ...::ConfigData->feature($name) >>.
The C<feature()> and C<config_data()> methods represent
Module::Build's main support for configuration of installed modules.
See also L<Module::Build::Authoring/"SAVING CONFIGURATION INFORMATION">.
=item fix_shebang_line(@files)
[version 0.??]
inc/inc_Module-Build/Module/Build/API.pod view on Meta::CPAN
Asks the user a question and returns their response as a string. The
first argument specifies the message to display to the user (for
example, C<"Where do you keep your money?">). The second argument,
which is optional, specifies a default answer (for example,
C<"wallet">). The user will be asked the question once.
If C<prompt()> detects that it is not running interactively and there
is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
is set to true, the $default will be used without prompting.
To prevent automated processes from blocking, the user must either set
PERL_MM_USE_DEFAULT or attach something to STDIN (this can be a
pipe/file containing a scripted set of answers or /dev/null.)
If no $default is provided an empty string will be used instead. In
non-interactive mode, the absence of $default is an error (though
explicitly passing C<undef()> as the default is valid as of 0.27.)
This method may be called as a class or object method.
=item recommends()
inc/inc_Module-Build/Module/Build/Authoring.pod view on Meta::CPAN
=head2 XS Extensions
Modules which need to compile XS code should list C<ExtUtils::CBuilder>
as a C<build_requires> element.
=head1 SAVING CONFIGURATION INFORMATION
Module::Build provides a very convenient way to save configuration
information that your installed modules (or your regression tests) can
access. If your Build process calls the C<feature()> or
C<config_data()> methods, then a C<Foo::Bar::ConfigData> module will
automatically be created for you, where C<Foo::Bar> is the
C<module_name> parameter as passed to C<new()>. This module provides
access to the data saved by these methods, and a way to update the
values. There is also a utility script called C<config_data>
distributed with Module::Build that provides a command line interface
to this same functionality. See also the generated
C<Foo::Bar::ConfigData> documentation, and the C<config_data>
script's documentation, for more information.
inc/inc_Module-Build/Module/Build/Authoring.pod view on Meta::CPAN
will invoke the entire build/install procedure:
my $build = Module::Build->new(module_name => 'MyModule');
$build->dispatch('build');
$build->dispatch('test');
$build->dispatch('install');
If any of these steps encounters an error, it will throw a fatal
exception.
You can also pass arguments as part of the build process:
my $build = Module::Build->new(module_name => 'MyModule');
$build->dispatch('build');
$build->dispatch('test', verbose => 1);
$build->dispatch('install', sitelib => '/my/secret/place/');
Building and installing modules in this way skips creating the
C<Build> script.
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
my $vals = delete $p->{$_};
while (my ($k, $v) = each %$vals) {
$self->$_($k, $v);
}
}
}
# The following warning could be unnecessary if the user is running
# an embedded perl, but there aren't too many of those around, and
# embedded perls aren't usually used to install modules, and the
# installation process sometimes needs to run external scripts
# (e.g. to run tests).
$p->{perl} = $self->find_perl_interpreter
or $self->log_warn("Warning: Can't locate your perl binary");
my $blibdir = sub { File::Spec->catdir($p->{blib}, @_) };
$p->{bindoc_dirs} ||= [ $blibdir->("script") ];
$p->{libdoc_dirs} ||= [ $blibdir->("lib"), $blibdir->("arch") ];
$p->{dist_author} = [ $p->{dist_author} ] if defined $p->{dist_author} and not ref $p->{dist_author};
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
$self->recurse_into(\@r);
}
sub cwd {
return Cwd::cwd();
}
sub _quote_args {
# Returns a string that can become [part of] a command line with
# proper quoting so that the subprocess sees this same list of args.
my ($self, @args) = @_;
my @quoted;
for (@args) {
if ( /^[^\s*?!\$<>;\\|'"\[\]\{\}]+$/ ) {
# Looks pretty safe
push @quoted, $_;
} else {
# XXX this will obviously have to improve - is there already a
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
my $cmd = $self->_quote_args(@cmd);
return `$cmd`;
}
}
# Tells us whether the construct open($fh, '-|', @command) is
# supported. It would probably be better to dynamically sense this.
sub have_forkpipe { 1 }
# Determine whether a given binary is the same as the perl
# (configuration) that started this process.
sub _perl_is_same {
my ($self, $perl) = @_;
my @cmd = ($perl);
# When run from the perl core, @INC will include the directories
# where perl is yet to be installed. We need to reference the
# absolute path within the source distribution where it can find
# it's Config.pm This also prevents us from picking up a Config.pm
# from a different configuration that happens to be already
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
my $known_perl;
sub find_perl_interpreter {
my $self = shift;
return $known_perl if defined($known_perl);
return $known_perl = $self->_discover_perl_interpreter;
}
}
# Returns the absolute path of the perl interpreter used to invoke
# this process. The path is derived from $^X or $Config{perlpath}. On
# some platforms $^X contains the complete absolute path of the
# interpreter, on other it may contain a relative path, or simply
# 'perl'. This can also vary depending on whether a path was supplied
# when perl was invoked. Additionally, the value in $^X may omit the
# executable extension on platforms that use one. It's a fatal error
# if the interpreter can't be found because it can result in undefined
# behavior by routines that depend on it (generating errors or
# invoking the wrong perl.)
sub _discover_perl_interpreter {
my $proto = shift;
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
# Create blib/arch to keep blib.pm happy
my $blib = $self->blib;
$self->add_to_cleanup($blib);
File::Path::mkpath( File::Spec->catdir($blib, 'arch') );
if (my $split = $self->autosplit) {
$self->autosplit_file($_, $blib) for ref($split) ? @$split : ($split);
}
foreach my $element (@{$self->build_elements}) {
my $method = "process_${element}_files";
$method = "process_files_by_extension" unless $self->can($method);
$self->$method($element);
}
$self->depends_on('config_data');
}
sub ACTION_build {
my $self = shift;
$self->log_info("Building " . $self->dist_name . "\n");
$self->depends_on('code');
$self->depends_on('docs');
}
sub process_files_by_extension {
my ($self, $ext) = @_;
my $method = "find_${ext}_files";
my $files = $self->can($method) ? $self->$method() : $self->_find_file_by_type($ext, 'lib');
while (my ($file, $dest) = each %$files) {
$self->copy_if_modified(from => $file, to => File::Spec->catfile($self->blib, $dest) );
}
}
sub process_support_files {
my $self = shift;
my $p = $self->{properties};
return unless $p->{c_source};
my $files;
if (ref($p->{c_source}) eq "ARRAY") {
push @{$p->{include_dirs}}, @{$p->{c_source}};
for my $path (@{$p->{c_source}}) {
push @$files, @{ $self->rscan_dir($path, $self->file_qr('\.c(c|p|pp|xx|\+\+)?$')) };
}
} else {
push @{$p->{include_dirs}}, $p->{c_source};
$files = $self->rscan_dir($p->{c_source}, $self->file_qr('\.c(c|p|pp|xx|\+\+)?$'));
}
foreach my $file (@$files) {
push @{$p->{objects}}, $self->compile_c($file);
}
}
sub process_share_dir_files {
my $self = shift;
my $files = $self->_find_share_dir_files;
return unless $files;
# root for all File::ShareDir paths
my $share_prefix = File::Spec->catdir($self->blib, qw/lib auto share/);
# copy all share files to blib
while (my ($file, $dest) = each %$files) {
$self->copy_if_modified(
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
my %files;
for my $dir ( @$list ) {
for my $f ( @{ $self->rscan_dir( $dir, sub {-f} )} ) {
$f =~ s{\A.*?\Q$dir\E/}{};
$files{"$dir/$f"} = "$prefix/$f";
}
}
return %files;
}
sub process_PL_files {
my ($self) = @_;
my $files = $self->find_PL_files;
while (my ($file, $to) = each %$files) {
unless ($self->up_to_date( $file, $to )) {
$self->run_perl_script($file, [], [@$to]) or die "$file failed";
$self->add_to_cleanup(@$to);
}
}
}
sub process_xs_files {
my $self = shift;
my $files = $self->find_xs_files;
while (my ($from, $to) = each %$files) {
unless ($from eq $to) {
$self->add_to_cleanup($to);
$self->copy_if_modified( from => $from, to => $to );
}
$self->process_xs($to);
}
}
sub process_pod_files { shift()->process_files_by_extension(shift()) }
sub process_pm_files { shift()->process_files_by_extension(shift()) }
sub process_script_files {
my $self = shift;
my $files = $self->find_script_files;
return unless keys %$files;
my $script_dir = File::Spec->catdir($self->blib, 'script');
File::Path::mkpath( $script_dir );
foreach my $file (keys %$files) {
my $result = $self->copy_if_modified($file, $script_dir, 'flatten') or next;
$self->fix_shebang_line($result) unless $self->is_vmsish;
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
my ($self, $path) = @_;
return File::Spec->catdir( split m{/}, $path );
}
sub fix_shebang_line { # Adapted from fixin() in ExtUtils::MM_Unix 1.35
my ($self, @files) = @_;
my $c = ref($self) ? $self->{config} : 'Module::Build::Config';
my ($does_shbang) = $c->get('sharpbang') =~ /^\s*\#\!/;
for my $file (@files) {
my $FIXIN = IO::File->new($file) or die "Can't process '$file': $!";
local $/ = "\n";
chomp(my $line = <$FIXIN>);
next unless $line =~ s/^\s*\#!\s*//; # Not a shbang file.
my ($cmd, $arg) = (split(' ', $line, 2), '');
next unless $cmd =~ /perl/i;
my $interpreter = $self->{properties}{perl};
$self->log_verbose("Changing sharpbang in $file to $interpreter\n");
my $shb = '';
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
return $spec->{lib_file};
}
sub compile_xs {
my ($self, $file, %args) = @_;
$self->log_verbose("$file -> $args{outfile}\n");
if (eval {require ExtUtils::ParseXS; 1}) {
ExtUtils::ParseXS::process_file(
filename => $file,
prototypes => 0,
output => $args{outfile},
);
} else {
# Ok, I give up. Just use backticks.
my $xsubpp = Module::Build::ModuleInfo->find_module_by_name('ExtUtils::xsubpp')
or die "Can't find ExtUtils::xsubpp in INC (@INC)";
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
return $self->run_perl_command([@$preargs, $script, @$postargs]);
}
sub run_perl_command {
# XXX Maybe we should accept @args instead of $args? Must resolve
# this before documenting.
my ($self, $args) = @_;
$args = [ $self->split_like_shell($args) ] unless ref($args);
my $perl = ref($self) ? $self->perl : $self->find_perl_interpreter;
# Make sure our local additions to @INC are propagated to the subprocess
local $ENV{PERL5LIB} = join $self->config('path_sep'), $self->_added_to_INC;
return $self->do_system($perl, @$args);
}
# Infer various data from the path of the input filename
# that is needed to create output files.
# The input filename is expected to be of the form:
# lib/Module/Name.ext or Module/Name.ext
sub _infer_xs_spec {
inc/inc_Module-Build/Module/Build/Base.pm view on Meta::CPAN
$spec{c_file} = File::Spec->catfile( $spec{src_dir},
"${file_base}.c" );
$spec{obj_file} = File::Spec->catfile( $spec{src_dir},
"${file_base}".$cf->get('obj_ext') );
return \%spec;
}
sub process_xs {
my ($self, $file) = @_;
my $spec = $self->_infer_xs_spec($file);
# File name, minus the suffix
(my $file_base = $file) =~ s/\.[^.]+$//;
# .xs -> .c
$self->add_to_cleanup($spec->{c_file});
inc/inc_Module-Build/Module/Build/Compat.pm view on Meta::CPAN
For good measure, of course, test both the F<Makefile.PL> and the
F<Build.PL> before shipping.
=item 3.
Include a F<Build.PL> script and a "pass-through" F<Makefile.PL>
built using C<Module::Build::Compat>. This will mean that people can
continue to use the "old" installation commands, and they may never
notice that it's actually doing something else behind the scenes. It
will also mean that your installation process is compatible with older
versions of tools like CPAN and CPANPLUS.
=back
=head1 AUTHOR
Ken Williams <kwilliams@cpan.org>
inc/inc_Module-Build/Module/Build/Cookbook.pm view on Meta::CPAN
As a best practice, we recommend using the "traditional" style of
F<Makefile.PL> unless your distribution has needs that can't be
accomplished that way.
The C<Module::Build::Compat> module, which is part of
C<Module::Build>'s distribution, is responsible for creating these
F<Makefile.PL>s. Please see L<Module::Build::Compat> for the details.
=head2 Changing the order of the build process
The C<build_elements> property specifies the steps C<Module::Build>
will take when building a distribution. To change the build order,
change the order of the entries in that property:
# Process pod files first
my @e = @{$build->build_elements};
my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
unshift @e, splice @e, $i, 1;
Currently, C<build_elements> has the following default value:
[qw( PL support pm xs pod script )]
Do take care when altering this property, since there may be
non-obvious (and non-documented!) ordering dependencies in the
C<Module::Build> code.
=head2 Adding new file types to the build process
Sometimes you might have extra types of files that you want to install
alongside the standard types like F<.pm> and F<.pod> files. For
instance, you might have a F<Bar.dat> file containing some data
related to the C<Foo::Bar> module and you'd like for it to end up as
F<Foo/Bar.dat> somewhere in perl's C<@INC> path so C<Foo::Bar> can
access it easily at runtime. The following code from a sample
C<Build.PL> file demonstrates how to accomplish this:
use Module::Build;
inc/inc_Module-Build/Module/Build/Cookbook.pm view on Meta::CPAN
my $build = new Module::Build
(
module_name => 'Foo::Bar',
dat_files => {'some/dir/Bar.dat' => 'lib/Foo/Bar.dat'},
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
If your extra files actually need to be created on the user's machine,
or if they need some other kind of special processing, you'll probably
want to subclass C<Module::Build> and create a special method to
process them, named C<process_${kind}_files()>:
use Module::Build;
my $class = Module::Build->subclass(code => <<'EOF');
sub process_dat_files {
my $self = shift;
... locate and process *.dat files,
... and create something in blib/lib/
}
EOF
my $build = $class->new
(
module_name => 'Foo::Bar',
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
If your extra files don't go in F<lib/> but in some other place, see
L<"Adding new elements to the install process"> for how to actually
get them installed.
Please note that these examples use some capabilities of Module::Build
that first appeared in version 0.26. Before that it could
still be done, but the simple cases took a bit more work.
=head2 Adding new elements to the install process
By default, Module::Build creates seven subdirectories of the F<blib>
directory during the build process: F<lib>, F<arch>, F<bin>,
F<script>, F<bindoc>, F<libdoc>, and F<html> (some of these may be
missing or empty if there's nothing to go in them). Anything copied
to these directories during the build will eventually be installed
during the C<install> action (see L<Module::Build/"INSTALL PATHS">.
If you need to create a new custom type of installable element, e.g. C<conf>,
then you need to tell Module::Build where things in F<blib/conf/>
should be installed. To do this, use the C<install_path> parameter to
the C<new()> method:
inc/inc_Module-Build/Module/Build/Cookbook.pm view on Meta::CPAN
The user may also specify the path on the command line:
perl Build.PL --install_path conf=/foo/path/etc
The important part, though, is that I<somehow> the install path needs
to be set, or else nothing in the F<blib/conf/> directory will get
installed, and a runtime error during the C<install> action will
result.
See also L<"Adding new file types to the build process"> for how to
create the stuff in F<blib/conf/> in the first place.
=head1 EXAMPLES ON CPAN
Several distributions on CPAN are making good use of various features
of Module::Build. They can serve as real-world examples for others.
=head2 SVN-Notify-Mirror
inc/inc_Module-Build/Module/Build/Platform/VMS.pm view on Meta::CPAN
=item _quote_args
Command-line arguments (but not the command itself) must be quoted
to ensure case preservation.
=cut
sub _quote_args {
# Returns a string that can become [part of] a command line with
# proper quoting so that the subprocess sees this same list of args,
# or if we get a single arg that is an array reference, quote the
# elements of it and return the reference.
my ($self, @args) = @_;
my $got_arrayref = (scalar(@args) == 1
&& UNIVERSAL::isa($args[0], 'ARRAY'))
? 1
: 0;
# Do not quote qualifiers that begin with '/'.
map { if (!/^\//) {
inc/inc_Module-Build/Module/Build/Platform/Windows.pm view on Meta::CPAN
print $out @file[$skiplines..$#file];
print $out $tail unless $taildone;
$out->close;
return $opts{out};
}
sub _quote_args {
# Returns a string that can become [part of] a command line with
# proper quoting so that the subprocess sees this same list of args.
my ($self, @args) = @_;
my @quoted;
for (@args) {
if ( /^[^\s*?!\$<>;|'"\[\]\{\}]+$/ ) {
# Looks pretty safe
push @quoted, $_;
} else {
# XXX this will obviously have to improve - is there already a
inc/inc_Module-Build/Module/Build/WithXSpp.pm view on Meta::CPAN
# overridden from original. We really require
# EU::ParseXS, so the "if (eval{require EU::PXS})" is gone.
sub compile_xs {
my ($self, $file, %args) = @_;
$self->log_verbose("$file -> $args{outfile}\n");
require ExtUtils::ParseXS;
my $main_dir = Cwd::abs_path( Cwd::cwd() );
my $build_dir = Cwd::abs_path( $self->build_dir );
ExtUtils::ParseXS::process_file(
filename => $file,
prototypes => 0,
output => $args{outfile},
# not default:
'C++' => 1,
hiertype => 1,
typemap => File::Spec->catfile($build_dir, 'typemap'),
);
}
inc/inc_Module-Build/Module/Build/WithXSpp.pm view on Meta::CPAN
# optional: mix in some extra C typemaps:
extra_typemap_modules => {
'ExtUtils::Typemaps::ObjectMap' => '0',
},
);
$build->create_build_script;
=head1 DESCRIPTION
This subclass of L<Module::Build> adds some tools and
processes to make it easier to use for wrapping C++
using XS++ (L<ExtUtils::XSpp>).
There are a few minor differences from using C<Module::Build>
for an ordinary XS module and a few conventions that you
should be aware of as an XS++ module author. They are documented
in the L</"FEATURES AND CONVENTIONS"> section below. But if you
can't be bothered to read all that, you may choose skip it and
blindly follow the advice in L</"JUMP START FOR THE IMPATIENT">.
An example of a full distribution based on this build tool
inc/inc_version/version/vpp.pm view on Meta::CPAN
my $vinf = 0;
my ($start, $last, $pos, $s);
$s = 0;
while ( substr($value,$s,1) =~ /\s/ ) { # leading whitespace is OK
$s++;
}
if (substr($value,$s,1) eq 'v') {
$s++; # get past 'v'
$qv = 1; # force quoted version processing
}
$start = $last = $pos = $s;
# pre-scan the input string to check for decimals/underbars
while ( substr($value,$pos,1) =~ /[._\d,]/ ) {
if ( substr($value,$pos,1) eq '.' ) {
if ($alpha) {
Carp::croak("Invalid version format ".
"(underscores before decimal)");
inc/inc_version/version/vpp.pm view on Meta::CPAN
"(alpha without decimal)");
}
if ( $alpha && $saw_period && $width == 0 ) {
require Carp;
Carp::croak("Invalid version format ".
"(misplaced _ in number)");
}
if ( $saw_period > 1 ) {
$qv = 1; # force quoted version processing
}
$last = $pos;
$pos = $s;
if ( $qv ) {
$self->{qv} = 1;
}
if ( $alpha ) {
( run in 0.369 second using v1.01-cache-2.11-cpan-8d75d55dd25 )