perl Build.PL ./Build ./Build test ./Build install
There's nothing complicated here - first you're running a script called Build.PL, then you're running a (newly-generated) script called Build and passing it various arguments.
The exact commands may vary a bit depending on how you invoke perl scripts on your system. For instance, if you have multiple versions of perl installed, you can install to one particular perl's library directories like so:
/usr/bin/perl5.8.1 Build.PL ./Build ./Build test ./Build install
If you're on Windows where the current directory is always searched first for scripts, you'll probably do something like this:
perl Build.PL Build Build test Build install
On the old Mac OS (version 9 or lower) using MacPerl, you can double-click on the Build.PL script to create the Build script, then double-click on the Build script to run its "build", "test", and "install" actions.
The Build script knows what perl was used to run Build.PL, so you don't need to re-invoke the Build script with the complete perl path each time. If you invoke it with the wrong perl path, you'll get a warning or a fatal error.
perl Build.PL --config cc=gcc --config ld=gcc
Inside the "Build.PL" script the same thing can be accomplished by passing values for the "config" parameter to "new()":
my $build = Module::Build->new
(
...
config => { cc => 'gcc', ld => 'gcc' },
...
);
In custom build code, the same thing can be accomplished by calling the ``config'' in Module::Build method:
$build->config( cc => 'gcc' ); # Set
$build->config( ld => 'gcc' ); # Set
...
my $linker = $build->config('ld'); # Get
my $build = Module::Build->new
(
module_name => 'Foo::Bar',
license => 'perl',
requires => { 'Some::Module' => '1.23' },
);
$build->dispatch('build');
$build->dispatch('test', verbose => 1);
$build->dispatch('install');
The first argument to "dispatch()" is the name of the action, and any following arguments are named parameters.
This is the interface we use to test Module::Build itself in the regression tests.
./Build install --destdir /tmp/my-package-1.003
This essentially just prepends all the installation paths with the /tmp/my-package-1.003 directory.
./Build install --install_base /foo/bar
See ``INSTALL PATHS'' in Module::Build for a much more complete discussion of how installation paths are determined.
First, ensure you have at least version 0.28 of Module::Build installed and 6.31 of "ExtUtils::MakeMaker". Prior versions have differing (and in some cases quite strange) installation behaviors.
The following installation flags are equivalent between "ExtUtils::MakeMaker" and "Module::Build".
MakeMaker Module::Build
PREFIX=... --prefix ...
INSTALL_BASE=... --install_base ...
DESTDIR=... --destdir ...
LIB=... --install_path lib=...
INSTALLDIRS=... --installdirs ...
INSTALLDIRS=perl --installdirs core
UNINST=... --uninst ...
INC=... --extra_compiler_flags ...
POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE
For example, if you are currently installing "MakeMaker" modules with this command:
perl Makefile.PL PREFIX=~
make test
make install UNINST=1
You can install into the same location with Module::Build using this:
perl Build.PL --prefix ~
./Build test
./Build install --uninst 1
"prefix" vs "install_base"
The behavior of "prefix" is complicated and depends on how your Perl is configured. The resulting installation locations will vary from machine to machine and even different installations of Perl on the same machine. Because of this, it's difficult to document where "prefix" will place your modules.
In contrast, "install_base" has predictable, easy to explain installation locations. Now that "Module::Build" and "MakeMaker" both have "install_base" there is little reason to use "prefix" other than to preserve your existing installation locations. If you are starting a fresh Perl installation we encourage you to use "install_base". If you have an existing installation installed via "prefix", consider moving it to an installation structure matching "install_base" and using that instead.
./Build test --test_files t/mytest.t
In addition, you may want to run the test in verbose mode to get more informative output:
./Build test --test_files t/mytest.t --verbose 1
I run this so frequently that I define the following shell alias:
alias t './Build test --verbose 1 --test_files'
So then I can just execute "t t/mytest.t" to run a single test.
As a best practice, we recommend using the ``traditional'' style of Makefile.PL unless your distribution has needs that can't be accomplished that way.
The "Module::Build::Compat" module, which is part of "Module::Build"'s distribution, is responsible for creating these Makefile.PLs. Please see Module::Build::Compat for the details.
# Process pod files first
my @e = @{$build->build_elements};
my ($i) = grep {$e[$_] eq 'pod'} 0..$#e;
unshift @e, splice @e, $i, 1;
Currently, "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 "Module::Build" code.
use Module::Build;
my $build = Module::Build->new
(
module_name => 'Foo::Bar',
...other stuff here...
);
$build->add_build_element('dat');
$build->create_build_script;
This will find all .dat files in the lib/ directory, copy them to the blib/lib/ directory during the "build" action, and install them during the "install" action.
If your extra files aren't located in the "lib/" directory in your distribution, you can explicitly say where they are, just as you'd do with .pm or .pod files:
use Module::Build;
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 "Module::Build" and create a special method to process them, named "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 lib/ but in some other place, see ``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.
If you need to create a new custom type of installable element, e.g. "conf", then you need to tell Module::Build where things in blib/conf/ should be installed. To do this, use the "install_path" parameter to the "new()" method:
my $build = Module::Build->new
(
...other stuff here...
install_path => { conf => $installation_path }
);
Or you can call the "install_path()" method later:
$build->install_path(conf => $installation_path);
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 somehow the install path needs to be set, or else nothing in the blib/conf/ directory will get installed, and a runtime error during the "install" action will result.
See also ``Adding new file types to the build process'' for how to create the stuff in blib/conf/ in the first place.
John Peacock, author of the "SVN-Notify-Mirror" distribution, says:
You can subclass "Module::Build" on the fly using the "subclass()" method and override the methods that perform the actions. You may need to read through "Module::Build::Authoring" and "Module::Build::API" to find the methods you want to override. All ``action'' methods are implemented by a method called ``ACTION_'' followed by the action's name, so here's an example of how it would work for the "install" action:
# Build.PL
use Module::Build;
my $class = Module::Build->subclass(
class => "Module::Build::Custom",
code => <<'SUBCLASS' );
sub ACTION_install {
my $self = shift;
# YOUR CODE HERE
$self->SUPER::ACTION_install;
}
SUBCLASS
$class->new(
module_name => 'Your::Module',
# rest of the usual Module::Build parameters
)->create_build_script;
For example, let's say you wanted to be able to write "./Build commit" to test your code and commit it to Subversion.
# Build.PL
use Module::Build;
my $class = Module::Build->subclass(
class => "Module::Build::Custom",
code => <<'SUBCLASS' );
sub ACTION_commit {
my $self = shift;
$self->depends_on("test");
$self->do_system(qw(svn commit));
}
SUBCLASS
Suppose you want to use some new-ish features of Module::Build, e.g. newer than the version of Module::Build your users are likely to already have installed on their systems. The first thing you should do is set "configure_requires" to your minimum version of Module::Build. See Module::Build::Authoring.
But not every build system honors "configure_requires" yet. Here's how you can ship a copy of Module::Build, but still use a newer installed version to take advantage of any bug fixes and upgrades.
First, install Module::Build into Your-Project/inc/Module-Build. CPAN will not index anything in the inc directory so this copy will not show up in CPAN searches.
cd Module-Build
perl Build.PL --install_base /path/to/Your-Project/inc/Module-Build
./Build test
./Build install
You should now have all the Module::Build .pm files in Your-Project/inc/Module-Build/lib/perl5.
Next, add this to the top of your Build.PL.
my $Bundled_MB = 0.30; # or whatever version it was.
# Find out what version of Module::Build is installed or fail quietly.
# This should be cross-platform.
my $Installed_MB =
`$^X -e "eval q{require Module::Build; print Module::Build->VERSION} or exit 1"`;
# some operating systems put a newline at the end of every print.
chomp $Installed_MB;
$Installed_MB = 0 if $?;
# Use our bundled copy of Module::Build if it's newer than the installed.
unshift @INC, "inc/Module-Build/lib/perl5" if $Bundled_MB > $Installed_MB;
require Module::Build;
And write the rest of your Build.PL normally. Module::Build will remember your change to @INC and use it when you run ./Build.
In the future, we hope to provide a more automated solution for this scenario; see "inc/latest.pm" in the Module::Build distribution for one indication of the direction we're moving.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.