README
1NAME
2 Module::Build::Convert - Makefile.PL to Build.PL converter
3
4SYNOPSIS
5 use Module::Build::Convert;
6
7 # example arguments (empty %args is sufficient too)
8 %args = (Path => '/path/to/perl/distribution(s)',
9 Verbose => 2,
10 Use_Native_Order => 1,
11 Len_Indent => 4);
12
13 $make = Module::Build::Convert->new(%args);
14 $make->convert;
15
16DESCRIPTION
17 "ExtUtils::MakeMaker" has been a de-facto standard for the common
18 distribution of Perl modules; "Module::Build" is expected to supersede
19 "ExtUtils::MakeMaker" in some time (part of the Perl core as of 5.9.4).
20
21 The transition takes place slowly, as the converting process manually
22 achieved is yet an uncommon practice. The Module::Build::Convert
23 Makefile.PL parser is intended to ease the transition process.
24
25CONSTRUCTOR
26 new
27 Options:
28
29 * "Path"
30 Path to a Perl distribution. May point to a single distribution
31 directory or to one containing more than one distribution. Default:
32 ''
33
34 * "Makefile_PL"
35 Filename of the Makefile script. Default: Makefile.PL
36
37 * "Build_PL"
38 Filename of the Build script. Default: Build.PL
39
40 * "MANIFEST"
41 Filename of the MANIFEST file. Default: MANIFEST
42
43 * "RC"
44 Filename of the RC file. Default: .make2buildrc
45
46 * "Dont_Overwrite_Auto"
47 If a Build.PL already exists, output a notification and ask whether
48 it should be overwritten. Default: 1
49
50 * "Create_RC"
51 Create a RC file in the homedir of the current user. Default: 0
52
53 * "Parse_PPI"
54 Parse the Makefile.PL in the PPI Parser mode. Default: 0
55
56 * "Exec_Makefile"
57 Execute the Makefile.PL via 'do Makefile.PL'. Default: 0
58
59 * "Verbose"
60 Verbose mode. If set to 1, overridden defaults and skipped arguments
61 are printed while converting; if set to 2, output of "Verbose = 1"
62 and created Build script will be printed. May be set via the
63 make2build switches "-v" (mode 1) and "-vv" (mode 2). Default: 0
64
65 * "Debug"
66 Rudimentary debug facility for examining the parsing process.
67 Default: 0
68
69 * "Process_Code"
70 Process code embedded within the arguments list. Default: 0
71
72 * "Use_Native_Order"
73 Native sorting order. If set to 1, the native sorting order of the
74 Makefile arguments will be tried to preserve; it's equal to using
75 the make2build switch "-n". Default: 0
76
77 * "Len_Indent"
78 Indentation (character width). May be set via the make2build switch
79 "-l". Default: 3
80
81 * "DD_Indent"
82 "Data::Dumper" indendation mode. Mode 0 will be disregarded in favor
83 of 2. Default: 2
84
85 * "DD_Sortkeys"
86 "Data::Dumper" sort keys. Default: 1
87
88METHODS
89 convert
90 Parses the Makefile.PL's "WriteMakefile()" arguments and converts them
91 to "Module::Build" equivalents; subsequently the according Build.PL is
92 created. Takes no arguments.
93
94DATA SECTION
95 Argument conversion
96 "ExtUtils::MakeMaker" arguments followed by their "Module::Build"
97 equivalents. Converted data structures preserve their native structure,
98 that is, "HASH" -> "HASH", etc.
99
100 NAME module_name
101 DISTNAME dist_name
102 ABSTRACT dist_abstract
103 AUTHOR dist_author
104 VERSION dist_version
105 VERSION_FROM dist_version_from
106 PREREQ_PM requires
107 PL_FILES PL_files
108 PM pm_files
109 MAN1PODS pod_files
110 XS xs_files
111 INC include_dirs
112 INSTALLDIRS installdirs
113 DESTDIR destdir
114 CCFLAGS extra_compiler_flags
115 EXTRA_META meta_add
116 SIGN sign
117 LICENSE license
118 clean.FILES @add_to_cleanup
119
120 Default arguments
121 "Module::Build" default arguments may be specified as key/value pairs.
122 Arguments attached to multidimensional structures are unsupported.
123
124 #build_requires HASH
125 #recommends HASH
126 #conflicts HASH
127 license unknown
128 create_readme 1
129 create_makefile_pl traditional
130
131 Value may be either a string or of type "SCALAR, ARRAY, HASH".
132
133 Sorting order
134 "Module::Build" arguments are sorted as enlisted herein. Additional
135 arguments, that don't occur herein, are lower prioritized and will be
136 inserted in unsorted order after preceedingly sorted arguments.
137
138 module_name
139 dist_name
140 dist_abstract
141 dist_author
142 dist_version
143 dist_version_from
144 requires
145 build_requires
146 recommends
147 conflicts
148 PL_files
149 pm_files
150 pod_files
151 xs_files
152 include_dirs
153 installdirs
154 destdir
155 add_to_cleanup
156 extra_compiler_flags
157 meta_add
158 sign
159 license
160 create_readme
161 create_makefile_pl
162
163 Begin code
164 Code that preceeds converted "Module::Build" arguments.
165
166 use strict;
167 use warnings;
168
169 use Module::Build;
170
171 $MAKECODE
172
173 my $b = Module::Build->new
174 $INDENT(
175
176 End code
177 Code that follows converted "Module::Build" arguments.
178
179 $INDENT);
180
181 $b->create_build_script;
182
183 $MAKECODE
184
185INTERNALS
186 co-opting "WriteMakefile()"
187 This behavior is no longer the default way to receive WriteMakefile()'s
188 arguments; the Makefile.PL is now statically parsed unless one forces
189 manually the co-opting of WriteMakefile().
190
191 In order to convert arguments, a typeglob from "WriteMakefile()" to an
192 internal sub will be set; subsequently Makefile.PL will be executed and
193 the arguments are then accessible to the internal sub.
194
195 Data::Dumper
196 Converted "ExtUtils::MakeMaker" arguments will be dumped by
197 "Data::Dumper's" "Dump()" and are then furtherly processed.
198
199BUGS & CAVEATS
200 "Module::Build::Convert" should be considered experimental as the
201 parsing of the Makefile.PL doesn't necessarily return valid arguments,
202 especially for Makefiles with bad or even worse, missing intendation.
203
204 The parsing process may sometimes hang with or without warnings in such
205 cases. Debugging by using the appropriate option/switch (see
206 CONSTRUCTOR/new) may reveal the root cause.
207
208SEE ALSO
209 <http://www.makemaker.org>, ExtUtils::MakeMaker, Module::Build,
210 <http://www.makemaker.org/wiki/index.cgi?ModuleBuildConversionGuide>
211
212AUTHOR
213 Steven Schubiger <schubiger@cpan.org>
214
215LICENSE
216 This program is free software; you may redistribute it and/or modify it
217 under the same terms as Perl itself.
218
219 See <http://www.perl.com/perl/misc/Artistic.html>
220
221