Module::Build::Convert
Steven
Schubiger
Copyright (c) 2005-2008, 2024 Steven Schubiger
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".
Common distribution "skeleton"
It has been common practice within the Perl community for ages to ship
distributions with a Makefile.PL so that the user will be able to install
the packages when he retrieves them either via the shell which the CPAN/CPANPLUS
modules offer or via manual CPAN download.
The Makefile.PL consists of "meta information" which in the case of the
distribution HTML::Tagset looks as follows:
# This -*-perl-*- program writes the Makefile for installing this distribution.
#
# See "perldoc perlmodinstall" or "perldoc ExtUtils::MakeMaker" for
# info on how to control how the installation goes.
require 5.004;
use strict;
use ExtUtils::MakeMaker;
WriteMakefile(
NAME => 'HTML::Tagset',
AUTHOR => 'Andy Lester <andy@petdance.com>',
VERSION_FROM => 'Tagset.pm', # finds $VERSION
ABSTRACT_FROM => 'Tagset.pm', # retrieve abstract from module
PMLIBDIRS => [qw(lib/)],
dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
clean => { FILES => 'HTML-Tagset-*' },
);
Of interest are the arguments to WriteMakefile(), because they influence
what Makefile is being written by ExtUtils::MakeMaker
after the user has invoked the usual build & install procedure including the subsequent commands:
% perl Makefile.PL
% make
% make test
# make install
Module::Build successor of ExtUtils::MakeMaker?
As Ken Williams grew tired of ExtUtils::MakeMaker & portability issues, he invented
Module::Build, the designated successor of ExtUtils::MakeMaker,
which is expected to run smoothly on most Operating Systems, because Module::Build
takes advantage of creating Perl-valid syntax files only and does not rely upon crufty
Makefiles, which are often subject to misinterpretation, because so many incompatible
flavours of make exist out there in the wild.
The current maintainer of ExtUtils::MakeMaker (Michael G. Schwern) elaborated about
this problematic some more in his talk
MakeMaker is DOOMED.
Module::Build distribution "skeleton"
If you take in consideration the distribution HTML::Tagset again, the rough skeleton
suitable for Module::Build having converted the Makefile.PL by
Module::Build::Convert into a Build.PL, the output would be as
following:
# This -*-perl-*- program writes the Makefile for installing this distribution.
#
# See "perldoc perlmodinstall" or "perldoc ExtUtils::MakeMaker" for
# info on how to control how the installation goes.
# Note: this file has been initially generated by Module::Build::Convert 0.24_01
require 5.004;
use strict;
use warnings;
use Module::Build;
my $build = Module::Build->new
(
module_name => 'HTML::Tagset',
dist_author => 'Andy Lester <andy@petdance.com>',
dist_version_from => 'Tagset.pm',
add_to_cleanup => [
'HTML-Tagset-*'
],
license => 'unknown',
create_readme => 1,
create_makefile_pl => 'traditional',
);
$build->create_build_script;
As you can see while ExtUtils::MakeMaker prefers upper-cased arguments,
Module::Build goes by entirely lower-cased arguments, which obey the rule
of least surprise by being as intuitive as a description can be.
The build and installation procedure is for a Module::Build distribution as following:
% perl Build.PL
% perl Build
% perl Build test
# perl Build install
Module::Build::Convert's state of operation
Module::Build::Convert actually does all the background work and can be safely
considered the backend, whereas make2build may be looked at as practicle frontend utility.
Module::Build::Convert currently exposes two kinds of operation: static approach & dynamic
execution. When static approach is being referred, this means ie. that the arguments contained within
the Makefile.PL's WriteMakefile() call are being parsed, whereas dynamic
execution "runs" the Makefile.PL and captures the arguments provided to WriteMakefile()
.
Module::Build::Convert parses statically by default, because the dynamic execution has the
downside that code will be interpreted and the interpreted output will be written to the Build.PL,
so you have to conclude that the user of the distribution will end up with predefined values computed
on the authors system; this is something that should surely be avoided whenever possible! If the
parsing approach fails, ie. loops endlessly on input, Module::Build::Convert will be "reinited"
again and dynamic execution of the Makefile.PL will be performed instead.
Data section
Module::Build::Convert comes with a rather huge data section, that contains the argument
conversion table, default arguments, sorting order, begin & end code. If you wish to change
this data, you should consider making a ~/.make2buildrc that will consist of this data by
launching make2build with the -rc switch. You shouldn't (!)
edit the data section within Module::Build::Convert directly, unless you are sure you want
to submit a patch.
The sections are enlisted as:
Argument conversion
On the left-hand side is the MakeMaker's argument name, on the right-hand side
the Module::Build's equivalent.
NAME module_name
DISTNAME dist_name
ABSTRACT dist_abstract
AUTHOR dist_author
VERSION dist_version
VERSION_FROM dist_version_from
PREREQ_PM requires
PL_FILES PL_files
PM pm_files
MAN1PODS pod_files
XS xs_files
INC include_dirs
INSTALLDIRS installdirs
DESTDIR destdir
CCFLAGS extra_compiler_flags
EXTRA_META meta_add
SIGN sign
LICENSE license
clean.FILES @add_to_cleanup
Default arguments
Default Module::Build arguments to be added. Arguments with a leading # are ignored.
#build_requires HASH
#recommends HASH
#conflicts HASH
license unknown
create_readme 1
create_makefile_pl traditional
Sorting order
Module::Build arguments are sorted as enlisted herein.
module_name
dist_name
dist_abstract
dist_author
dist_version
dist_version_from
requires
build_requires
recommends
conflicts
PL_files
pm_files
pod_files
xs_files
include_dirs
installdirs
destdir
add_to_cleanup
extra_compiler_flags
meta_add
sign
license
create_readme
create_makefile_pl
Begin code
Code that preceeds converted Module::Build arguments.
$(UPPERCASE) are stubs being substituted by Module::Build code.
use strict;
use warnings;
use Module::Build;
$MAKECODE
my $b = Module::Build->new
$INDENT(
End code
Code that follows converted Module::Build arguments.
$(UPPERCASE) are stubs being substituted by
Module::Build code.
$INDENT);
$b->create_build_script;
$MAKECODE
make2build basic usage
Making proper usage of make2build is as easy as launching it in the directory of the
distribution which Makefile.PL you wish to convert.
For example:
% make2build
But you may also provide the full path to the distribution, assuming for example you didn't cd
directly into the distribution directory.
% make2build /path/to/HTML-Tagset*
In both cases the Makefile.PLs will be converted and no output is generated since make2build
acts quiet by default.
make2build switches
As make2build aims to be a proper script it, of course, provides both, the -h (help screen)
and -V (version) switches.
% make2build -h
% make2build -V
In case you end up with a mangled Build.PL written, you could examine the parsing process by
launching make2build with the -d switch which implies the pseudo-interactive
debugging mode.
% make2build -d
You may execute the Makefile.PL in first place, but such usage is deprecated since
Module::Build::Convert "downgrades" automatically when needed.
% make2build -e (deprecated)
Should you not like the indentation length or judge it to be to small, you can increase
it via the -l switch followed by an integer.
% make2build -l length
If you don't agree with the sorting order predefined in Module::Build::Convert, you may
enforce the native sorting order, which strives to arrange standard arguments with those seen
available in the Makefile.PL.
% make2build -n
The argument conversion table, default arguments to be added, the sorting order of the arguments,
the begin and end code aren't absolute either and may be changed by invoking make2build
with the -rc switch standing for Resource Config file creation; the file will be created
in the home directory of the current user by the defaulted filename .make2buildrc.
% make2build -rc
While make2build is quiet by default, it may be switched to output some verbosity. There are two
verbosity level; to enforce verbosity level 1, launch make2build with -v, to
enforce verbosity level 2, simply launch make2build with -vv.
Whenever -v was chosen, Makefile.PL arguments that were unknown to the
conversion table or are being skipped are being output. Whenever -vv was chosen, it will
accumulate -v output & the entire Build.PL written.
% make2build -v
% make2build -vv