This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Typo fix
[perl5.git] / cpan / Module-Build / lib / Module / Build / Compat.pm
CommitLineData
bb4e9162
YST
1package Module::Build::Compat;
2
3use strict;
4use vars qw($VERSION);
cdbde1c3 5$VERSION = '0.35';
bb4e9162 6
23837600 7use File::Basename ();
bb4e9162
YST
8use File::Spec;
9use IO::File;
10use Config;
11use Module::Build;
12use Module::Build::ModuleInfo;
13use Data::Dumper;
14
738349a8
SH
15my %convert_installdirs = (
16 PERL => 'core',
17 SITE => 'site',
18 VENDOR => 'vendor',
19);
20
bb4e9162
YST
21my %makefile_to_build =
22 (
23 TEST_VERBOSE => 'verbose',
24 VERBINST => 'verbose',
738349a8
SH
25 INC => sub { map {(extra_compiler_flags => $_)} Module::Build->split_like_shell(shift) },
26 POLLUTE => sub { (extra_compiler_flags => '-DPERL_POLLUTE') },
27 INSTALLDIRS => sub { (installdirs => $convert_installdirs{uc shift()}) },
28 LIB => sub {
29 my $lib = shift;
30 my %config = (
31 installprivlib => $lib,
32 installsitelib => $lib,
33 installarchlib => "$lib/$Config{archname}",
34 installsitearch => "$lib/$Config{archname}"
35 );
36 return map { (config => "$_=$config{$_}") } keys %config;
37 },
38
39 # Convert INSTALLVENDORLIB and friends.
40 (
41 map {
23837600 42 my $name = $_;
738349a8 43 $name => sub {
23837600 44 my @ret = (config => lc($name) . "=" . shift );
738349a8
SH
45 print STDERR "# Converted to @ret\n";
46
47 return @ret;
48 }
23837600
DG
49 } qw(
50 INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
51 INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
52 INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
53 INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
54 INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
55 INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
56 )
738349a8 57 ),
bb4e9162
YST
58
59 # Some names they have in common
60 map {$_, lc($_)} qw(DESTDIR PREFIX INSTALL_BASE UNINST),
61 );
62
738349a8
SH
63my %macro_to_build = %makefile_to_build;
64# "LIB=foo make" is not the same as "perl Makefile.PL LIB=foo"
65delete $macro_to_build{LIB};
bb4e9162
YST
66
67
68sub create_makefile_pl {
69 my ($package, $type, $build, %args) = @_;
70
71 die "Don't know how to build Makefile.PL of type '$type'"
72 unless $type =~ /^(small|passthrough|traditional)$/;
73
74 my $fh;
75 if ($args{fh}) {
76 $fh = $args{fh};
77 } else {
78 $args{file} ||= 'Makefile.PL';
738349a8
SH
79 local $build->{properties}{quiet} = 1;
80 $build->delete_filetree($args{file});
bb4e9162
YST
81 $fh = IO::File->new("> $args{file}") or die "Can't write $args{file}: $!";
82 }
83
84 print {$fh} "# Note: this file was auto-generated by ", __PACKAGE__, " version $VERSION\n";
85
7a827510
RGS
86 # Minimum perl version should be specified as "require 5.XXXXXX" in
87 # Makefile.PL
88 my $requires = $build->requires;
89 if ( my $minimum_perl = $requires->{perl} ) {
90 print {$fh} "require $minimum_perl;\n";
91 }
92
dc8021d3 93 # If a *bundled* custom subclass is being used, make sure we add its
738349a8 94 # directory to @INC. Also, lib.pm always needs paths in Unix format.
bb4e9162
YST
95 my $subclass_load = '';
96 if (ref($build) ne "Module::Build") {
97 my $subclass_dir = $package->subclass_dir($build);
dc8021d3 98
bb4e9162
YST
99 if (File::Spec->file_name_is_absolute($subclass_dir)) {
100 my $base_dir = $build->base_dir;
101
102 if ($build->dir_contains($base_dir, $subclass_dir)) {
103 $subclass_dir = File::Spec->abs2rel($subclass_dir, $base_dir);
738349a8 104 $subclass_dir = $package->unixify_dir($subclass_dir);
dc8021d3 105 $subclass_load = "use lib '$subclass_dir';";
bb4e9162 106 }
738349a8 107 # Otherwise, leave it the empty string
dc8021d3
SP
108
109 } else {
738349a8 110 $subclass_dir = $package->unixify_dir($subclass_dir);
dc8021d3 111 $subclass_load = "use lib '$subclass_dir';";
bb4e9162 112 }
bb4e9162 113 }
dc8021d3 114
bb4e9162
YST
115 if ($type eq 'small') {
116 printf {$fh} <<'EOF', $subclass_load, ref($build), ref($build);
117 use Module::Build::Compat 0.02;
118 %s
119 Module::Build::Compat->run_build_pl(args => \@ARGV);
120 require %s;
121 Module::Build::Compat->write_makefile(build_class => '%s');
122EOF
123
124 } elsif ($type eq 'passthrough') {
125 printf {$fh} <<'EOF', $subclass_load, ref($build), ref($build);
126
127 unless (eval "use Module::Build::Compat 0.02; 1" ) {
128 print "This module requires Module::Build to install itself.\n";
129
130 require ExtUtils::MakeMaker;
131 my $yn = ExtUtils::MakeMaker::prompt
132 (' Install Module::Build now from CPAN?', 'y');
133
134 unless ($yn =~ /^y/i) {
135 die " *** Cannot install without Module::Build. Exiting ...\n";
136 }
137
138 require Cwd;
139 require File::Spec;
140 require CPAN;
141
142 # Save this 'cause CPAN will chdir all over the place.
143 my $cwd = Cwd::cwd();
144
bb4e9162 145 CPAN::Shell->install('Module::Build::Compat');
47f13fd5
SP
146 CPAN::Shell->expand("Module", "Module::Build::Compat")->uptodate
147 or die "Couldn't install Module::Build, giving up.\n";
bb4e9162
YST
148
149 chdir $cwd or die "Cannot chdir() back to $cwd: $!";
150 }
151 eval "use Module::Build::Compat 0.02; 1" or die $@;
152 %s
153 Module::Build::Compat->run_build_pl(args => \@ARGV);
94410036
DG
154 my $build_script = 'Build';
155 $build_script .= '.com' if $^O eq 'VMS';
156 exit(0) unless(-e $build_script); # cpantesters convention
bb4e9162
YST
157 require %s;
158 Module::Build::Compat->write_makefile(build_class => '%s');
159EOF
160
161 } elsif ($type eq 'traditional') {
162
163 my (%MM_Args, %prereq);
164 if (eval "use Tie::IxHash; 1") {
165 tie %MM_Args, 'Tie::IxHash'; # Don't care if it fails here
166 tie %prereq, 'Tie::IxHash'; # Don't care if it fails here
167 }
168
169 my %name = ($build->module_name
170 ? (NAME => $build->module_name)
171 : (DISTNAME => $build->dist_name));
172
173 my %version = ($build->dist_version_from
174 ? (VERSION_FROM => $build->dist_version_from)
175 : (VERSION => $build->dist_version)
176 );
177 %MM_Args = (%name, %version);
178
179 %prereq = ( %{$build->requires}, %{$build->build_requires} );
180 %prereq = map {$_, $prereq{$_}} sort keys %prereq;
181
23837600 182 delete $prereq{perl};
bb4e9162
YST
183 $MM_Args{PREREQ_PM} = \%prereq;
184
185 $MM_Args{INSTALLDIRS} = $build->installdirs eq 'core' ? 'perl' : $build->installdirs;
186
187 $MM_Args{EXE_FILES} = [ sort keys %{$build->script_files} ] if $build->script_files;
188
94410036 189 $MM_Args{PL_FILES} = $build->PL_files || {};
23837600
DG
190
191 if ($build->recursive_test_files) {
192 $MM_Args{TESTS} = join q{ }, $package->_test_globs($build);
193 }
194
bb4e9162
YST
195 local $Data::Dumper::Terse = 1;
196 my $args = Data::Dumper::Dumper(\%MM_Args);
197 $args =~ s/\{(.*)\}/($1)/s;
198
199 print $fh <<"EOF";
200use ExtUtils::MakeMaker;
201WriteMakefile
202$args;
203EOF
204 }
205}
206
23837600
DG
207sub _test_globs {
208 my ($self, $build) = @_;
209
210 return map { File::Spec->catfile($_, '*.t') }
211 @{$build->rscan_dir('t', sub { -d $File::Find::name })};
212}
bb4e9162
YST
213
214sub subclass_dir {
215 my ($self, $build) = @_;
216
217 return (Module::Build::ModuleInfo->find_module_dir_by_name(ref $build)
218 || File::Spec->catdir($build->config_dir, 'lib'));
219}
220
738349a8
SH
221sub unixify_dir {
222 my ($self, $path) = @_;
223 return join '/', File::Spec->splitdir($path);
224}
225
bb4e9162 226sub makefile_to_build_args {
738349a8 227 my $class = shift;
bb4e9162
YST
228 my @out;
229 foreach my $arg (@_) {
230 next if $arg eq '';
231
232 my ($key, $val) = ($arg =~ /^(\w+)=(.+)/ ? ($1, $2) :
233 die "Malformed argument '$arg'");
234
235 # Do tilde-expansion if it looks like a tilde prefixed path
738349a8 236 ( $val ) = Module::Build->_detildefy( $val ) if $val =~ /^~/;
bb4e9162
YST
237
238 if (exists $makefile_to_build{$key}) {
239 my $trans = $makefile_to_build{$key};
738349a8 240 push @out, $class->_argvify( ref($trans) ? $trans->($val) : ($trans => $val) );
bb4e9162 241 } elsif (exists $Config{lc($key)}) {
738349a8 242 push @out, $class->_argvify( config => lc($key) . "=$val" );
bb4e9162
YST
243 } else {
244 # Assume M::B can handle it in lowercase form
738349a8 245 push @out, $class->_argvify("\L$key" => $val);
bb4e9162
YST
246 }
247 }
248 return @out;
249}
250
738349a8
SH
251sub _argvify {
252 my ($self, @pairs) = @_;
253 my @out;
254 while (@pairs) {
255 my ($k, $v) = splice @pairs, 0, 2;
256 push @out, ("--$k", $v);
257 }
258 return @out;
259}
260
bb4e9162
YST
261sub makefile_to_build_macros {
262 my @out;
23837600 263 my %config; # must accumulate and return as a hashref
738349a8 264 while (my ($macro, $trans) = each %macro_to_build) {
bb4e9162
YST
265 # On some platforms (e.g. Cygwin with 'make'), the mere presence
266 # of "EXPORT: FOO" in the Makefile will make $ENV{FOO} defined.
267 # Therefore we check length() too.
268 next unless exists $ENV{$macro} && length $ENV{$macro};
269 my $val = $ENV{$macro};
23837600
DG
270 my @args = ref($trans) ? $trans->($val) : ($trans => $val);
271 while (@args) {
272 my ($k, $v) = splice(@args, 0, 2);
273 if ( $k eq 'config' ) {
274 if ( $v =~ /^([^=]+)=(.*)$/ ) {
275 $config{$1} = $2;
276 }
277 else {
278 warn "Couldn't parse config '$v'\n";
279 }
280 }
281 else {
282 push @out, ($k => $v);
283 }
284 }
bb4e9162 285 }
23837600 286 push @out, (config => \%config) if %config;
bb4e9162
YST
287 return @out;
288}
289
290sub run_build_pl {
291 my ($pack, %in) = @_;
292 $in{script} ||= 'Build.PL';
293 my @args = $in{args} ? $pack->makefile_to_build_args(@{$in{args}}) : ();
294 print "# running $in{script} @args\n";
295 Module::Build->run_perl_script($in{script}, [], \@args) or die "Couldn't run $in{script}: $!";
296}
297
298sub fake_makefile {
299 my ($self, %args) = @_;
300 unless (exists $args{build_class}) {
301 warn "Unknown 'build_class', defaulting to 'Module::Build'\n";
302 $args{build_class} = 'Module::Build';
303 }
c1d8f74e 304 my $class = $args{build_class};
bb4e9162 305
c1d8f74e 306 my $perl = $class->find_perl_interpreter;
738349a8
SH
307
308 # VMS MMS/MMK need to use MCR to run the Perl image.
309 $perl = 'MCR ' . $perl if $self->_is_vms_mms;
310
c1d8f74e 311 my $noop = ($class->is_windowsish ? 'rem>nul' :
738349a8 312 $self->_is_vms_mms ? 'Continue' :
bb4e9162 313 'true');
bb4e9162 314
738349a8
SH
315 my $filetype = $class->is_vmsish ? '.COM' : '';
316
317 my $Build = 'Build' . $filetype . ' --makefile_env_macros 1';
318 my $unlink = $class->oneliner('1 while unlink $ARGV[0]', [], [$args{makefile}]);
86bddcbf 319 $unlink =~ s/\$/\$\$/g unless $class->is_vmsish;
738349a8 320
cdbde1c3
DG
321 my $maketext = ($^O eq 'os2' ? "SHELL = sh\n\n" : '');
322
323 $maketext .= <<"EOF";
bb4e9162
YST
324all : force_do_it
325 $perl $Build
326realclean : force_do_it
327 $perl $Build realclean
738349a8 328 $unlink
94410036
DG
329distclean : force_do_it
330 $perl $Build distclean
331 $unlink
332
bb4e9162
YST
333
334force_do_it :
335 @ $noop
336EOF
337
c1d8f74e 338 foreach my $action ($class->known_actions) {
94410036 339 next if $action =~ /^(all|distclean|realclean|force_do_it)$/; # Don't double-define
bb4e9162
YST
340 $maketext .= <<"EOF";
341$action : force_do_it
342 $perl $Build $action
343EOF
344 }
345
738349a8
SH
346 if ($self->_is_vms_mms) {
347 # Roll our own .EXPORT as MMS/MMK don't honor that directive.
348 $maketext .= "\n.FIRST\n\t\@ $noop\n";
349 for my $macro (keys %macro_to_build) {
350 $maketext .= ".IFDEF $macro\n\tDEFINE $macro \"\$($macro)\"\n.ENDIF\n";
351 }
352 $maketext .= "\n";
353 }
354 else {
355 $maketext .= "\n.EXPORT : " . join(' ', keys %macro_to_build) . "\n\n";
356 }
bb4e9162
YST
357
358 return $maketext;
359}
360
361sub fake_prereqs {
362 my $file = File::Spec->catfile('_build', 'prereqs');
363 my $fh = IO::File->new("< $file") or die "Can't read $file: $!";
364 my $prereqs = eval do {local $/; <$fh>};
365 close $fh;
366
367 my @prereq;
368 foreach my $section (qw/build_requires requires/) {
369 foreach (keys %{$prereqs->{$section}}) {
370 next if $_ eq 'perl';
371 push @prereq, "$_=>q[$prereqs->{$section}{$_}]";
372 }
373 }
374
375 return unless @prereq;
376 return "# PREREQ_PM => { " . join(", ", @prereq) . " }\n\n";
377}
378
379
380sub write_makefile {
381 my ($pack, %in) = @_;
738349a8
SH
382
383 unless (exists $in{build_class}) {
384 warn "Unknown 'build_class', defaulting to 'Module::Build'\n";
385 $in{build_class} = 'Module::Build';
386 }
387 my $class = $in{build_class};
388 $in{makefile} ||= $pack->_is_vms_mms ? 'Descrip.MMS' : 'Makefile';
389
bb4e9162
YST
390 open MAKE, "> $in{makefile}" or die "Cannot write $in{makefile}: $!";
391 print MAKE $pack->fake_prereqs;
392 print MAKE $pack->fake_makefile(%in);
393 close MAKE;
394}
395
738349a8
SH
396sub _is_vms_mms {
397 return Module::Build->is_vmsish && ($Config{make} =~ m/MM[SK]/i);
398}
399
bb4e9162
YST
4001;
401__END__
402
23837600 403=for :stopwords passthrough
bb4e9162
YST
404
405=head1 NAME
406
407Module::Build::Compat - Compatibility with ExtUtils::MakeMaker
408
409
410=head1 SYNOPSIS
411
412 # In a Build.PL :
413 use Module::Build;
414 my $build = Module::Build->new
415 ( module_name => 'Foo::Bar',
416 license => 'perl',
417 create_makefile_pl => 'passthrough' );
418 ...
419
420
421=head1 DESCRIPTION
422
23837600 423Because C<ExtUtils::MakeMaker> has been the standard way to distribute
bb4e9162 424modules for a long time, many tools (CPAN.pm, or your system
23837600 425administrator) may expect to find a working F<Makefile.PL> in every
bb4e9162 426distribution they download from CPAN. If you want to throw them a
23837600
DG
427bone, you can use C<Module::Build::Compat> to automatically generate a
428F<Makefile.PL> for you, in one of several different styles.
bb4e9162 429
23837600
DG
430C<Module::Build::Compat> also provides some code that helps out the
431F<Makefile.PL> at runtime.
bb4e9162
YST
432
433
434=head1 METHODS
435
436=over 4
437
438=item create_makefile_pl($style, $build)
439
23837600
DG
440Creates a F<Makefile.PL> in the current directory in one of several
441styles, based on the supplied C<Module::Build> object C<$build>. This is
bb4e9162 442typically controlled by passing the desired style as the
23837600
DG
443C<create_makefile_pl> parameter to C<Module::Build>'s C<new()> method;
444the F<Makefile.PL> will then be automatically created during the
bb4e9162
YST
445C<distdir> action.
446
447The currently supported styles are:
448
449=over 4
450
451=item small
452
23837600
DG
453A small F<Makefile.PL> will be created that passes all functionality
454through to the F<Build.PL> script in the same directory. The user must
455already have C<Module::Build> installed in order to use this, or else
bb4e9162
YST
456they'll get a module-not-found error.
457
458=item passthrough
459
23837600 460This is just like the C<small> option above, but if C<Module::Build> is
bb4e9162
YST
461not already installed on the user's system, the script will offer to
462use C<CPAN.pm> to download it and install it before continuing with
463the build.
464
465=item traditional
466
23837600 467A F<Makefile.PL> will be created in the "traditional" style, i.e. it will
bb4e9162 468use C<ExtUtils::MakeMaker> and won't rely on C<Module::Build> at all.
23837600 469In order to create the F<Makefile.PL>, we'll include the C<requires> and
bb4e9162
YST
470C<build_requires> dependencies as the C<PREREQ_PM> parameter.
471
472You don't want to use this style if during the C<perl Build.PL> stage
473you ask the user questions, or do some auto-sensing about the user's
23837600
DG
474environment, or if you subclass C<Module::Build> to do some
475customization, because the vanilla F<Makefile.PL> won't do any of that.
bb4e9162
YST
476
477=back
478
479=item run_build_pl(args => \@ARGV)
480
23837600 481This method runs the F<Build.PL> script, passing it any arguments the
bb4e9162 482user may have supplied to the C<perl Makefile.PL> command. Because
23837600 483C<ExtUtils::MakeMaker> and C<Module::Build> accept different arguments, this
bb4e9162
YST
484method also performs some translation between the two.
485
486C<run_build_pl()> accepts the following named parameters:
487
488=over 4
489
490=item args
491
492The C<args> parameter specifies the parameters that would usually
493appear on the command line of the C<perl Makefile.PL> command -
494typically you'll just pass a reference to C<@ARGV>.
495
496=item script
497
498This is the filename of the script to run - it defaults to C<Build.PL>.
499
500=back
501
502=item write_makefile()
503
23837600
DG
504This method writes a 'dummy' F<Makefile> that will pass all commands
505through to the corresponding C<Module::Build> actions.
bb4e9162
YST
506
507C<write_makefile()> accepts the following named parameters:
508
509=over 4
510
511=item makefile
512
513The name of the file to write - defaults to the string C<Makefile>.
514
515=back
516
517=back
518
519
520=head1 SCENARIOS
521
522So, some common scenarios are:
523
524=over 4
525
526=item 1.
527
23837600
DG
528Just include a F<Build.PL> script (without a F<Makefile.PL>
529script), and give installation directions in a F<README> or F<INSTALL>
bb4e9162 530document explaining how to install the module. In particular, explain
23837600 531that the user must install C<Module::Build> before installing your
bb4e9162
YST
532module.
533
534Note that if you do this, you may make things easier for yourself, but
535harder for people with older versions of CPAN or CPANPLUS on their
536system, because those tools generally only understand the
537F<Makefile.PL>/C<ExtUtils::MakeMaker> way of doing things.
538
539=item 2.
540
23837600 541Include a F<Build.PL> script and a "traditional" F<Makefile.PL>,
bb4e9162 542created either manually or with C<create_makefile_pl()>. Users won't
23837600
DG
543ever have to install C<Module::Build> if they use the F<Makefile.PL>, but
544they won't get to take advantage of C<Module::Build>'s extra features
bb4e9162
YST
545either.
546
94410036 547For good measure, of course, test both the F<Makefile.PL> and the
bb4e9162
YST
548F<Build.PL> before shipping.
549
550=item 3.
551
23837600
DG
552Include a F<Build.PL> script and a "pass-through" F<Makefile.PL>
553built using C<Module::Build::Compat>. This will mean that people can
bb4e9162
YST
554continue to use the "old" installation commands, and they may never
555notice that it's actually doing something else behind the scenes. It
556will also mean that your installation process is compatible with older
557versions of tools like CPAN and CPANPLUS.
558
559=back
560
561
562=head1 AUTHOR
563
77e96e88 564Ken Williams <kwilliams@cpan.org>
bb4e9162
YST
565
566
567=head1 COPYRIGHT
568
77e96e88 569Copyright (c) 2001-2006 Ken Williams. All rights reserved.
bb4e9162
YST
570
571This library is free software; you can redistribute it and/or
572modify it under the same terms as Perl itself.
573
574
575=head1 SEE ALSO
576
dc8021d3 577L<Module::Build>(3), L<ExtUtils::MakeMaker>(3)
bb4e9162
YST
578
579
580=cut