-
-
29 Jan 2020 07:52:41 UTC
- Distribution: Module-Build
- Module version: 0.4231
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues (117)
- Testers (1825 / 73 / 15)
- Kwalitee
Bus factor: 2- 63.77% Coverage
- License: perl_5
- Perl: v5.6.1
- Activity
24 month- Tools
- Download (296.35KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- CPAN::Meta
- Cwd
- Data::Dumper
- ExtUtils::CBuilder
- ExtUtils::Install
- ExtUtils::Manifest
- ExtUtils::Mkbootstrap
- ExtUtils::ParseXS
- File::Basename
- File::Compare
- File::Copy
- File::Find
- File::Path
- File::Spec
- Getopt::Long
- Module::Metadata
- Perl::OSType
- Pod::Man
- TAP::Harness
- Text::Abbrev
- Text::ParseWords
- version
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- DESCRIPTION
- BASIC RECIPES
- ADVANCED RECIPES
- EXAMPLES ON CPAN
- AUTHOR
- COPYRIGHT
- SEE ALSO
NAME
Module::Build::Cookbook - Examples of Module::Build Usage
DESCRIPTION
Module::Build
isn't conceptually very complicated, but examples are always helpful. The following recipes should help developers and/or installers put together the pieces from the other parts of the documentation.BASIC RECIPES
Installing modules that use Module::Build
In most cases, you can just issue the following commands:
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
, andinstall
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.
Modifying Config.pm values
Module::Build
relies heavily on various values from perl'sConfig.pm
to do its work. For example, default installation paths are given byinstallsitelib
andinstallvendorman3dir
and friends, C linker & compiler settings are given byld
,lddlflags
,cc
,ccflags
, and so on. If you're pretty sure you know what you're doing, you can tellModule::Build
to pretend there are different values in Config.pm than what's really there, by passing arguments for the--config
parameter on the command line:perl Build.PL --config cc=gcc --config ld=gcc
Inside the
Build.PL
script the same thing can be accomplished by passing values for theconfig
parameter tonew()
: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
Installing modules using the programmatic interface
If you need to build, test, and/or install modules from within some other perl code (as opposed to having the user type installation commands at the shell), you can use the programmatic interface. Create a Module::Build object (or an object of a custom Module::Build subclass) and then invoke its
dispatch()
method to run various actions.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.
Installing to a temporary directory
To create packages for package managers like RedHat's
rpm
or Debian'sdeb
, you may need to install to a temporary directory first and then create the package from that temporary installation. To do this, specify thedestdir
parameter to theinstall
action:./Build install --destdir /tmp/my-package-1.003
This essentially just prepends all the installation paths with the /tmp/my-package-1.003 directory.
Installing to a non-standard directory
To install to a non-standard directory (for example, if you don't have permission to install in the system-wide directories), you can use the
install_base
orprefix
parameters:./Build install --install_base /foo/bar
See "INSTALL PATHS" in Module::Build for a much more complete discussion of how installation paths are determined.
Installing in the same location as ExtUtils::MakeMaker
With the introduction of
--prefix
in Module::Build 0.28 andINSTALL_BASE
inExtUtils::MakeMaker
6.31 its easy to get them both to install to the same locations.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
andModule::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
vsinstall_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 whereprefix
will place your modules.In contrast,
install_base
has predictable, easy to explain installation locations. Now thatModule::Build
andMakeMaker
both haveinstall_base
there is little reason to useprefix
other than to preserve your existing installation locations. If you are starting a fresh Perl installation we encourage you to useinstall_base
. If you have an existing installation installed viaprefix
, consider moving it to an installation structure matchinginstall_base
and using that instead.Running a single test file
Module::Build
supports running a single test, which enables you to track down errors more quickly. Use the following format:./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.ADVANCED RECIPES
Making a CPAN.pm-compatible distribution
New versions of CPAN.pm understand how to use a Build.PL script, but old versions don't. If authors want to help users who have old versions, some form of Makefile.PL should be supplied. The easiest way to accomplish this is to use the
create_makefile_pl
parameter toModule::Build->new()
in theBuild.PL
script, which can create various flavors of Makefile.PL during thedist
action.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 ofModule::Build
's distribution, is responsible for creating these Makefile.PLs. Please see Module::Build::Compat for the details.Changing the order of the build process
The
build_elements
property specifies the stepsModule::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,
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.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 .pm and .pod files. For instance, you might have a Bar.dat file containing some data related to the
Foo::Bar
module and you'd like for it to end up as Foo/Bar.dat somewhere in perl's@INC
path soFoo::Bar
can access it easily at runtime. The following code from a sampleBuild.PL
file demonstrates how to accomplish this: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 theinstall
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, namedprocess_${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.
Adding new elements to the install process
By default, Module::Build creates seven subdirectories of the blib directory during the build process: lib, arch, bin, script, bindoc, libdoc, and 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
install
action (see "INSTALL PATHS" in Module::Build.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 theinstall_path
parameter to thenew()
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.
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.
SVN-Notify-Mirror
http://search.cpan.org/~jpeacock/SVN-Notify-Mirror/
John Peacock, author of the
SVN-Notify-Mirror
distribution, says:- 1. Using
auto_features
, I check to see whether two optional modules are available - SVN::Notify::Config and Net::SSH; - 2. If the S::N::Config module is loaded, I automatically generate test files for it during Build (using the
PL_files
property). - 3. If the
ssh_feature
is available, I ask if the user wishes to perform the ssh tests (since it requires a little preliminary setup); - 4. Only if the user has
ssh_feature
and answers yes to the testing, do I generate a test file. -
I'm sure I could not have handled this complexity with EU::MM, but it was very easy to do with M::B.
Modifying an action
Sometimes you might need an to have an action, say
./Build install
, do something unusual. For instance, you might need to change the ownership of a file or do something else peculiar to your application.You can subclass
Module::Build
on the fly using thesubclass()
method and override the methods that perform the actions. You may need to read throughModule::Build::Authoring
andModule::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 theinstall
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;
Adding an action
You can add a new
./Build
action simply by writing the method for it in your subclass. Usedepends_on
to declare that another action must have been run before your action.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
Bundling Module::Build
Note: This section probably needs an update as the technology improves (see contrib/bundle.pl in the distribution).
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.AUTHOR
Ken Williams <kwilliams@cpan.org>
COPYRIGHT
Copyright (c) 2001-2008 Ken Williams. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
perl(1), Module::Build(3), Module::Build::Authoring(3), Module::Build::API(3)
Module Install Instructions
To install Module::Build, copy and paste the appropriate command in to your terminal.
cpanm Module::Build
perl -MCPAN -e shell install Module::Build
For more information on module installation, please visit the detailed CPAN module installation guide.