Steven Schubiger Copyright (c) 2005-2008 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". 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 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. 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 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. 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: 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 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 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 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( Code that follows converted Module::Build arguments. $(UPPERCASE) are stubs being substituted by Module::Build code. $INDENT); $b->create_build_script; $MAKECODE 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. 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