This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to ExtUtils-MakeMaker-6.48
[perl5.git] / lib / ExtUtils / MakeMaker.pm
CommitLineData
bf87a6a1 1# $Id$
e05e23b1
PP
2package ExtUtils::MakeMaker;
3
a592ba15
RGS
4use strict;
5
6BEGIN {require 5.006;}
57b1a898 7
8e07c86e 8require Exporter;
7292dc67 9use ExtUtils::MakeMaker::Config;
3b03c0f3 10use Carp ();
dedf98bc 11use File::Path;
e05e23b1 12
a592ba15
RGS
13our $Verbose = 0; # exported
14our @Parent; # needs to be localized
15our @Get_from_Config; # referenced by MM_Unix
2e65e370
SH
16our @MM_Sections;
17our @Overridable;
a592ba15
RGS
18my @Prepend_parent;
19my %Recognized_Att_Keys;
005c1a0e 20
b5b9b385 21our $VERSION = '6.48';
bf87a6a1
NC
22
23# Emulate something resembling CVS $Revision$
24(our $Revision = $VERSION) =~ s{_}{};
25$Revision = int $Revision * 10000;
26
a592ba15 27our $Filename = __FILE__; # referenced outside MakeMaker
7292dc67 28
a592ba15
RGS
29our @ISA = qw(Exporter);
30our @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
31our @EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists
32 &WriteEmptyMakefile);
42793c05 33
f6d6199c
MS
34# These will go away once the last of the Win32 & VMS specific code is
35# purged.
5e9e174b 36my $Is_VMS = $^O eq 'VMS';
5e9e174b 37my $Is_Win32 = $^O eq 'MSWin32';
3b03c0f3 38
9ab29e2b 39full_setup();
864a5fa8 40
f6d6199c
MS
41require ExtUtils::MM; # Things like CPAN assume loading ExtUtils::MakeMaker
42 # will give them MM.
e05e23b1 43
45bc4d3a
JH
44require ExtUtils::MY; # XXX pre-5.8 versions of ExtUtils::Embed expect
45 # loading ExtUtils::MakeMaker will give them MY.
2e65e370 46 # This will go when Embed is its own CPAN module.
45bc4d3a 47
f1387719 48
3b03c0f3
PP
49sub WriteMakefile {
50 Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
f1387719 51
f6d6199c 52 require ExtUtils::MY;
3b03c0f3 53 my %att = @_;
69ff8adf
JH
54
55 _verify_att(\%att);
56
e0678a30
MS
57 my $mm = MM->new(\%att);
58 $mm->flush;
59
60 return $mm;
3b03c0f3
PP
61}
62
69ff8adf 63
d5d4ec93
MS
64# Basic signatures of the attributes WriteMakefile takes. Each is the
65# reference type. Empty value indicate it takes a non-reference
66# scalar.
479d2113
MS
67my %Att_Sigs;
68my %Special_Sigs = (
bfdac1b8
SP
69 C => 'ARRAY',
70 CONFIG => 'ARRAY',
71 CONFIGURE => 'CODE',
72 DIR => 'ARRAY',
73 DL_FUNCS => 'HASH',
74 DL_VARS => 'ARRAY',
75 EXCLUDE_EXT => 'ARRAY',
76 EXE_FILES => 'ARRAY',
77 FUNCLIST => 'ARRAY',
78 H => 'ARRAY',
79 IMPORTS => 'HASH',
80 INCLUDE_EXT => 'ARRAY',
81 LIBS => ['ARRAY',''],
82 MAN1PODS => 'HASH',
83 MAN3PODS => 'HASH',
2e65e370
SH
84 META_ADD => 'HASH',
85 META_MERGE => 'HASH',
bfdac1b8
SP
86 PL_FILES => 'HASH',
87 PM => 'HASH',
88 PMLIBDIRS => 'ARRAY',
89 PMLIBPARENTDIRS => 'ARRAY',
90 PREREQ_PM => 'HASH',
91 SKIP => 'ARRAY',
92 TYPEMAPS => 'ARRAY',
93 XS => 'HASH',
94 VERSION => ['version',''],
479d2113 95 _KEEP_AFTER_FLUSH => '',
69ff8adf 96
bfdac1b8
SP
97 clean => 'HASH',
98 depend => 'HASH',
99 dist => 'HASH',
100 dynamic_lib=> 'HASH',
101 linkext => 'HASH',
102 macro => 'HASH',
103 postamble => 'HASH',
104 realclean => 'HASH',
105 test => 'HASH',
106 tool_autosplit => 'HASH',
69ff8adf
JH
107);
108
479d2113
MS
109@Att_Sigs{keys %Recognized_Att_Keys} = ('') x keys %Recognized_Att_Keys;
110@Att_Sigs{keys %Special_Sigs} = values %Special_Sigs;
111
69ff8adf
JH
112
113sub _verify_att {
114 my($att) = @_;
115
116 while( my($key, $val) = each %$att ) {
117 my $sig = $Att_Sigs{$key};
d5d4ec93
MS
118 unless( defined $sig ) {
119 warn "WARNING: $key is not a known parameter.\n";
120 next;
121 }
122
123 my @sigs = ref $sig ? @$sig : $sig;
bfdac1b8
SP
124 my $given = ref $val;
125 unless( grep { $given eq $_ || ($_ && eval{$val->isa($_)}) } @sigs ) {
126 my $takes = join " or ", map { _format_att($_) } @sigs;
127
128 my $has = _format_att($given);
69ff8adf
JH
129 warn "WARNING: $key takes a $takes not a $has.\n".
130 " Please inform the author.\n";
69ff8adf
JH
131 }
132 }
133}
134
bfdac1b8
SP
135
136sub _format_att {
137 my $given = shift;
138
139 return $given eq '' ? "string/number"
140 : uc $given eq $given ? "$given reference"
141 : "$given object"
142 ;
143}
144
145
a592ba15 146sub prompt ($;$) { ## no critic
479d2113 147 my($mess, $def) = @_;
e0678a30
MS
148 Carp::confess("prompt function called without an argument")
149 unless defined $mess;
479d2113
MS
150
151 my $isa_tty = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;
152
f1387719
PP
153 my $dispdef = defined $def ? "[$def] " : " ";
154 $def = defined $def ? $def : "";
479d2113 155
13bc20ff 156 local $|=1;
f6d6199c 157 local $\;
13bc20ff 158 print "$mess $dispdef";
479d2113
MS
159
160 my $ans;
161 if ($ENV{PERL_MM_USE_DEFAULT} || (!$isa_tty && eof STDIN)) {
162 print "$def\n";
163 }
164 else {
f6d6199c
MS
165 $ans = <STDIN>;
166 if( defined $ans ) {
167 chomp $ans;
168 }
169 else { # user hit ctrl-D
170 print "\n";
171 }
172 }
479d2113 173
f6d6199c 174 return (!defined $ans || $ans eq '') ? $def : $ans;
3b03c0f3
PP
175}
176
e05e23b1
PP
177sub eval_in_subdirs {
178 my($self) = @_;
a8112c7f 179 use Cwd qw(cwd abs_path);
f582e489
MS
180 my $pwd = cwd() || die "Can't figure out your cwd!";
181
3593a55e 182 local @INC = map eval {abs_path($_) if -e} || $_, @INC;
f6d6199c 183 push @INC, '.'; # '.' has to always be at the end of @INC
e05e23b1 184
5e9e174b 185 foreach my $dir (@{$self->{DIR}}){
f6d6199c 186 my($abs) = $self->catdir($pwd,$dir);
a7d1454b
RGS
187 eval { $self->eval_in_x($abs); };
188 last if $@;
e05e23b1 189 }
e05e23b1 190 chdir $pwd;
a7d1454b 191 die $@ if $@;
864a5fa8 192}
42793c05 193
e05e23b1
PP
194sub eval_in_x {
195 my($self,$dir) = @_;
6626a13a 196 chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
5e9e174b 197
f6d6199c
MS
198 {
199 package main;
200 do './Makefile.PL';
201 };
f1387719 202 if ($@) {
f6d6199c
MS
203# if ($@ =~ /prerequisites/) {
204# die "MakeMaker WARNING: $@";
205# } else {
206# warn "WARNING from evaluation of $dir/Makefile.PL: $@";
207# }
45bc4d3a 208 die "ERROR from evaluation of $dir/Makefile.PL: $@";
f1387719 209 }
e05e23b1
PP
210}
211
479d2113
MS
212
213# package name for the classes into which the first object will be blessed
214my $PACKNAME = 'PACK000';
215
e05e23b1
PP
216sub full_setup {
217 $Verbose ||= 0;
3b03c0f3 218
5e9e174b 219 my @attrib_help = qw/
3b03c0f3 220
762efda7
JD
221 AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
222 C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
2e65e370 223 EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE
75e2e551
MS
224 FULLPERL FULLPERLRUN FULLPERLRUNINST
225 FUNCLIST H IMPORTS
431b0fc4 226
45bc4d3a 227 INST_ARCHLIB INST_SCRIPT INST_BIN INST_LIB INST_MAN1DIR INST_MAN3DIR
5c161494 228 INSTALLDIRS
2977d345 229 DESTDIR PREFIX INSTALL_BASE
479d2113 230 PERLPREFIX SITEPREFIX VENDORPREFIX
5c161494
MS
231 INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
232 INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
45bc4d3a
JH
233 INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
234 INSTALLMAN1DIR INSTALLMAN3DIR
235 INSTALLSITEMAN1DIR INSTALLSITEMAN3DIR
236 INSTALLVENDORMAN1DIR INSTALLVENDORMAN3DIR
002b9267 237 INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
5c161494
MS
238 PERL_LIB PERL_ARCHLIB
239 SITELIBEXP SITEARCHEXP
431b0fc4 240
2977d345 241 INC INCLUDE_EXT LDFROM LIB LIBPERL_A LIBS LICENSE
2e65e370 242 LINKTYPE MAKE MAKEAPERL MAKEFILE MAKEFILE_OLD MAN1PODS MAN3PODS MAP_TARGET
bf87a6a1 243 META_ADD META_MERGE MIN_PERL_VERSION
2530b651 244 MYEXTLIB NAME NEEDS_LINKING NOECHO NO_META NORECURS NO_VC OBJECT OPTIMIZE
431b0fc4 245 PERL_MALLOC_OK PERL PERLMAINCC PERLRUN PERLRUNINST PERL_CORE
5c161494 246 PERL_SRC PERM_RW PERM_RWX
2977d345 247 PL_FILES PM PM_FILTER PMLIBDIRS PMLIBPARENTDIRS POLLUTE PPM_INSTALL_EXEC
5c161494 248 PPM_INSTALL_SCRIPT PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ
bb68fe9e 249 SIGN SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
f1387719 250 XS_VERSION clean depend dist dynamic_lib linkext macro realclean
762efda7 251 tool_autosplit
431b0fc4 252
084592ab
CN
253 MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
254 MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
f6d6199c 255 /;
3b03c0f3 256
875fa795 257 # IMPORTS is used under OS/2 and Win32
f1387719
PP
258
259 # @Overridable is close to @MM_Sections but not identical. The
260 # order is important. Many subroutines declare macros. These
261 # depend on each other. Let's try to collect the macros up front,
262 # then pasthru, then the rules.
263
264 # MM_Sections are the sections we have to call explicitly
265 # in Overridable we have subroutines that are used indirectly
3b03c0f3 266
e05e23b1
PP
267
268 @MM_Sections =
f6d6199c 269 qw(
3b03c0f3 270
479d2113
MS
271 post_initialize const_config constants platform_constants
272 tool_autosplit tool_xsubpp tools_other
273
274 makemakerdflt
275
276 dist macro depend cflags const_loadlibs const_cccmd
f1387719
PP
277 post_constants
278
279 pasthru
280
479d2113
MS
281 special_targets
282 c_o xs_c xs_o
af7522e5 283 top_targets blibdirs linkext dlsyms dynamic dynamic_bs
f6d6199c 284 dynamic_lib static static_lib manifypods processPL
cae6c631 285 installbin subdirs
479d2113 286 clean_subdirs clean realclean_subdirs realclean
7292dc67
RGS
287 metafile signature
288 dist_basics dist_core distdir dist_test dist_ci distmeta distsignature
8f993c78 289 install force perldepend makefile staticmake test ppd
3b03c0f3 290
f6d6199c 291 ); # loses section ordering
e05e23b1 292
3b03c0f3 293 @Overridable = @MM_Sections;
f1387719
PP
294 push @Overridable, qw[
295
af7522e5 296 libscan makeaperl needs_linking perm_rw perm_rwx
2977d345
RGS
297 subdir_x test_via_harness test_via_script
298
299 init_VERSION init_dist init_INST init_INSTALL init_DEST init_dirscan
300 init_PM init_MANPODS init_xs init_PERL init_DIRFILESEP init_linker
f6d6199c 301 ];
3b03c0f3 302
f1387719 303 push @MM_Sections, qw[
3b03c0f3 304
f1387719
PP
305 pm_to_blib selfdocument
306
f6d6199c 307 ];
f1387719
PP
308
309 # Postamble needs to be the last that was always the case
310 push @MM_Sections, "postamble";
311 push @Overridable, "postamble";
e05e23b1
PP
312
313 # All sections are valid keys.
3b03c0f3 314 @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
e05e23b1
PP
315
316 # we will use all these variables in the Makefile
317 @Get_from_Config =
f6d6199c 318 qw(
2977d345
RGS
319 ar cc cccdlflags ccdlflags dlext dlsrc exe_ext full_ar ld
320 lddlflags ldflags libc lib_ext obj_ext osname osvers ranlib
321 sitelibexp sitearchexp so
f6d6199c 322 );
e05e23b1 323
479d2113
MS
324 # 5.5.3 doesn't have any concept of vendor libs
325 push @Get_from_Config, qw( vendorarchexp vendorlibexp ) if $] >= 5.006;
326
5e9e174b 327 foreach my $item (@attrib_help){
f6d6199c 328 $Recognized_Att_Keys{$item} = 1;
e05e23b1 329 }
5e9e174b 330 foreach my $item (@Get_from_Config) {
f6d6199c
MS
331 $Recognized_Att_Keys{uc $item} = $Config{$item};
332 print "Attribute '\U$item\E' => '$Config{$item}'\n"
333 if ($Verbose >= 2);
e05e23b1
PP
334 }
335
336 #
3b03c0f3
PP
337 # When we eval a Makefile.PL in a subdirectory, that one will ask
338 # us (the parent) for the values and will prepend "..", so that
339 # all files to be installed end up below OUR ./blib
e05e23b1 340 #
e0678a30
MS
341 @Prepend_parent = qw(
342 INST_BIN INST_LIB INST_ARCHLIB INST_SCRIPT
f6d6199c
MS
343 MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
344 PERL FULLPERL
345 );
e05e23b1 346}
42793c05 347
8e07c86e
AD
348sub writeMakefile {
349 die <<END;
232e078e 350
8e07c86e
AD
351The extension you are trying to build apparently is rather old and
352most probably outdated. We detect that from the fact, that a
353subroutine "writeMakefile" is called, and this subroutine is not
354supported anymore since about October 1994.
40000a8c 355
4633a7c4
LW
356Please contact the author or look into CPAN (details about CPAN can be
357found in the FAQ and at http:/www.perl.com) for a more recent version
358of the extension. If you're really desperate, you can try to change
359the subroutine name from writeMakefile to WriteMakefile and rerun
360'perl Makefile.PL', but you're most probably left alone, when you do
361so.
42793c05 362
8e07c86e 363The MakeMaker team
1aef975c 364
42793c05 365END
8e07c86e 366}
42793c05 367
f6d6199c 368sub new {
8e07c86e
AD
369 my($class,$self) = @_;
370 my($key);
42793c05 371
479d2113
MS
372 # Store the original args passed to WriteMakefile()
373 foreach my $k (keys %$self) {
374 $self->{ARGS}{$k} = $self->{$k};
375 }
376
88d69b28 377 if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
f6d6199c 378 require Data::Dumper;
bf87a6a1
NC
379 my @what = ('PREREQ_PM');
380 push @what, 'MIN_PERL_VERSION' if $self->{MIN_PERL_VERSION};
381 print Data::Dumper->Dump([@{$self}{@what}], \@what);
919b8535 382 exit 0;
f6d6199c 383 }
88d69b28
JH
384
385 # PRINT_PREREQ is RedHatism.
386 if ("@ARGV" =~ /\bPRINT_PREREQ\b/) {
bf87a6a1
NC
387 my @prereq =
388 map { [$_, $self->{PREREQ_PM}{$_}] } keys %{$self->{PREREQ_PM}};
389 if ( $self->{MIN_PERL_VERSION} ) {
390 push @prereq, ['perl' => $self->{MIN_PERL_VERSION}];
391 }
392
393 print join(" ", map { "perl($_->[0])>=$_->[1] " }
394 sort { $a->[0] cmp $b->[0] } @prereq), "\n";
f6d6199c 395 exit 0;
88d69b28
JH
396 }
397
e05e23b1 398 print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
8e07c86e 399 if (-f "MANIFEST" && ! -f "Makefile"){
f6d6199c 400 check_manifest();
1aef975c 401 }
42793c05 402
8e07c86e 403 $self = {} unless (defined $self);
005c1a0e 404
864a5fa8 405 check_hints($self);
4633a7c4 406
bf87a6a1
NC
407 # Translate X.Y.Z to X.00Y00Z
408 if( defined $self->{MIN_PERL_VERSION} ) {
409 $self->{MIN_PERL_VERSION} =~ s{ ^ (\d+) \. (\d+) \. (\d+) $ }
410 {sprintf "%d.%03d%03d", $1, $2, $3}ex;
411 }
412
413 my $perl_version_ok = eval {
414 local $SIG{__WARN__} = sub {
415 # simulate "use warnings FATAL => 'all'" for vintage perls
416 die @_;
417 };
418 !$self->{MIN_PERL_VERSION} or $self->{MIN_PERL_VERSION} <= $]
419 };
420 if (!$perl_version_ok) {
421 if (!defined $perl_version_ok) {
422 warn <<'END';
423Warning: MIN_PERL_VERSION is not in a recognized format.
424Recommended is a quoted numerical value like '5.005' or '5.008001'.
425END
426 }
427 elsif ($self->{PREREQ_FATAL}) {
428 die sprintf <<"END", $self->{MIN_PERL_VERSION}, $];
429MakeMaker FATAL: perl version too low for this distribution.
430Required is %s. We run %s.
431END
432 }
433 else {
434 warn sprintf
435 "Warning: Perl version %s or higher required. We run %s.\n",
436 $self->{MIN_PERL_VERSION}, $];
437 }
438 }
439
c3be8c6e 440 my %configure_att; # record &{$self->{CONFIGURE}} attributes
8e07c86e 441 my(%initial_att) = %$self; # record initial attributes
005c1a0e 442
a4260cbc 443 my(%unsatisfied) = ();
5e9e174b 444 foreach my $prereq (sort keys %{$self->{PREREQ_PM}}) {
479d2113
MS
445 # 5.8.0 has a bug with require Foo::Bar alone in an eval, so an
446 # extra statement is a workaround.
a7d1454b
RGS
447 my $file = "$prereq.pm";
448 $file =~ s{::}{/}g;
449 eval { require $file };
f6d6199c 450
e0678a30
MS
451 my $pr_version = $prereq->VERSION || 0;
452
479d2113
MS
453 # convert X.Y_Z alpha version #s to X.YZ for easier comparisons
454 $pr_version =~ s/(\d+)\.(\d+)_(\d+)/$1.$2$3/;
455
f6d6199c
MS
456 if ($@) {
457 warn sprintf "Warning: prerequisite %s %s not found.\n",
458 $prereq, $self->{PREREQ_PM}{$prereq}
459 unless $self->{PREREQ_FATAL};
460 $unsatisfied{$prereq} = 'not installed';
e0678a30 461 } elsif ($pr_version < $self->{PREREQ_PM}->{$prereq} ){
45bc4d3a 462 warn sprintf "Warning: prerequisite %s %s not found. We have %s.\n",
f6d6199c 463 $prereq, $self->{PREREQ_PM}{$prereq},
e0678a30 464 ($pr_version || 'unknown version')
f6d6199c
MS
465 unless $self->{PREREQ_FATAL};
466 $unsatisfied{$prereq} = $self->{PREREQ_PM}->{$prereq} ?
467 $self->{PREREQ_PM}->{$prereq} : 'unknown version' ;
468 }
f1387719 469 }
6d6be53e
RGS
470
471 if (%unsatisfied && $self->{PREREQ_FATAL}){
472 my $failedprereqs = join "\n", map {" $_ $unsatisfied{$_}"}
473 sort { $a cmp $b } keys %unsatisfied;
474 die <<"END";
475MakeMaker FATAL: prerequisites not found.
476$failedprereqs
477
478Please install these modules first and rerun 'perl Makefile.PL'.
479END
480 }
481
8e07c86e 482 if (defined $self->{CONFIGURE}) {
f6d6199c
MS
483 if (ref $self->{CONFIGURE} eq 'CODE') {
484 %configure_att = %{&{$self->{CONFIGURE}}};
485 $self = { %$self, %configure_att };
486 } else {
487 Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
488 }
005c1a0e 489 }
a0d0e21e 490
8e07c86e
AD
491 # This is for old Makefiles written pre 5.00, will go away
492 if ( Carp::longmess("") =~ /runsubdirpl/s ){
f6d6199c 493 Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
8e07c86e 494 }
5d94fbed 495
ccd13d1e 496 my $newclass = ++$PACKNAME;
f6d6199c 497 local @Parent = @Parent; # Protect against non-local exits
8e07c86e 498 {
f6d6199c
MS
499 print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
500 mv_all_methods("MY",$newclass);
501 bless $self, $newclass;
502 push @Parent, $self;
503 require ExtUtils::MY;
a592ba15
RGS
504
505 no strict 'refs'; ## no critic;
f6d6199c 506 @{"$newclass\:\:ISA"} = 'MM';
8e07c86e 507 }
5d94fbed 508
e05e23b1 509 if (defined $Parent[-2]){
f6d6199c 510 $self->{PARENT} = $Parent[-2];
a592ba15 511 for my $key (@Prepend_parent) {
f6d6199c 512 next unless defined $self->{PARENT}{$key};
531e2ba1
JH
513
514 # Don't stomp on WriteMakefile() args.
46442182
JH
515 next if defined $self->{ARGS}{$key} and
516 $self->{ARGS}{$key} eq $self->{$key};
517
518 $self->{$key} = $self->{PARENT}{$key};
531e2ba1 519
479d2113 520 unless ($Is_VMS && $key =~ /PERL$/) {
f6d6199c
MS
521 $self->{$key} = $self->catdir("..",$self->{$key})
522 unless $self->file_name_is_absolute($self->{$key});
523 } else {
524 # PERL or FULLPERL will be a command verb or even a
525 # command with an argument instead of a full file
526 # specification under VMS. So, don't turn the command
527 # into a filespec, but do add a level to the path of
528 # the argument if not already absolute.
529 my @cmd = split /\s+/, $self->{$key};
530 $cmd[1] = $self->catfile('[-]',$cmd[1])
531 unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
532 $self->{$key} = join(' ', @cmd);
533 }
534 }
535 if ($self->{PARENT}) {
536 $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
85f2ef06 537 foreach my $opt (qw(POLLUTE PERL_CORE LINKTYPE)) {
f6d6199c
MS
538 if (exists $self->{PARENT}->{$opt}
539 and not exists $self->{$opt})
540 {
541 # inherit, but only if already unspecified
542 $self->{$opt} = $self->{PARENT}->{$opt};
543 }
544 }
545 }
546 my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
547 parse_args($self,@fm) if @fm;
8e07c86e 548 } else {
f6d6199c 549 parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
8e07c86e 550 }
bfdac1b8 551
a0d0e21e 552
8e07c86e 553 $self->{NAME} ||= $self->guess_name;
a0d0e21e 554
8e07c86e 555 ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
a0d0e21e 556
2977d345 557 $self->init_MAKE;
479d2113
MS
558 $self->init_main;
559 $self->init_VERSION;
560 $self->init_dist;
561 $self->init_INST;
562 $self->init_INSTALL;
531e2ba1 563 $self->init_DEST;
479d2113 564 $self->init_dirscan;
2977d345
RGS
565 $self->init_PM;
566 $self->init_MANPODS;
479d2113
MS
567 $self->init_xs;
568 $self->init_PERL;
569 $self->init_DIRFILESEP;
570 $self->init_linker;
2977d345 571 $self->init_ABSTRACT;
8e07c86e 572
0d8023a2 573 if (! $self->{PERL_SRC} ) {
f6d6199c
MS
574 require VMS::Filespec if $Is_VMS;
575 my($pthinks) = $self->canonpath($INC{'Config.pm'});
576 my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
577 $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
578 if ($pthinks ne $cthinks &&
579 !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
3e3baf6d 580 print "Have $pthinks expected $cthinks\n";
f6d6199c
MS
581 if ($Is_Win32) {
582 $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
583 }
584 else {
585 $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
586 }
587 print STDOUT <<END unless $self->{UNINSTALLED_PERL};
588Your perl and your Config.pm seem to have different ideas about the
589architecture they are running on.
8e07c86e 590Perl thinks: [$pthinks]
e05e23b1 591Config says: [$Config{archname}]
f6d6199c
MS
592This may or may not cause problems. Please check your installation of perl
593if you have problems building this extension.
005c1a0e 594END
f6d6199c 595 }
005c1a0e
AD
596 }
597
8e07c86e 598 $self->init_others();
479d2113 599 $self->init_platform();
e0678a30 600 $self->init_PERM();
6071deed
GS
601 my($argv) = neatvalue(\@ARGV);
602 $argv =~ s/^\[/(/;
603 $argv =~ s/\]$/)/;
75f92628 604
8e07c86e
AD
605 push @{$self->{RESULT}}, <<END;
606# This Makefile is for the $self->{NAME} extension to perl.
607#
e05e23b1
PP
608# It was generated automatically by MakeMaker version
609# $VERSION (Revision: $Revision) from the contents of
610# Makefile.PL. Don't edit this file, edit Makefile.PL instead.
8e07c86e 611#
f6d6199c 612# ANY CHANGES MADE HERE WILL BE LOST!
8e07c86e 613#
6071deed
GS
614# MakeMaker ARGV: $argv
615#
8e07c86e
AD
616# MakeMaker Parameters:
617END
a0d0e21e 618
5e9e174b 619 foreach my $key (sort keys %initial_att){
479d2113
MS
620 next if $key eq 'ARGS';
621
f6d6199c
MS
622 my($v) = neatvalue($initial_att{$key});
623 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
624 $v =~ tr/\n/ /s;
625 push @{$self->{RESULT}}, "# $key => $v";
42793c05 626 }
c3be8c6e
DK
627 undef %initial_att; # free memory
628
629 if (defined $self->{CONFIGURE}) {
630 push @{$self->{RESULT}}, <<END;
631
632# MakeMaker 'CONFIGURE' Parameters:
633END
634 if (scalar(keys %configure_att) > 0) {
5e9e174b 635 foreach my $key (sort keys %configure_att){
479d2113 636 next if $key eq 'ARGS';
c3be8c6e
DK
637 my($v) = neatvalue($configure_att{$key});
638 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
639 $v =~ tr/\n/ /s;
640 push @{$self->{RESULT}}, "# $key => $v";
641 }
642 }
643 else
644 {
645 push @{$self->{RESULT}}, "# no values returned";
646 }
647 undef %configure_att; # free memory
648 }
a0d0e21e 649
8e07c86e 650 # turn the SKIP array into a SKIPHASH hash
a592ba15 651 for my $skip (@{$self->{SKIP} || []}) {
f6d6199c 652 $self->{SKIPHASH}{$skip} = 1;
8e07c86e 653 }
3b03c0f3
PP
654 delete $self->{SKIP}; # free memory
655
656 if ($self->{PARENT}) {
479d2113 657 for (qw/install dist dist_basics dist_core distdir dist_test dist_ci/) {
f6d6199c
MS
658 $self->{SKIPHASH}{$_} = 1;
659 }
3b03c0f3 660 }
42793c05 661
8e07c86e
AD
662 # We run all the subdirectories now. They don't have much to query
663 # from the parent, but the parent has to query them: if they need linking!
8e07c86e 664 unless ($self->{NORECURS}) {
f6d6199c 665 $self->eval_in_subdirs if @{$self->{DIR}};
42793c05 666 }
a0d0e21e 667
5e9e174b 668 foreach my $section ( @MM_Sections ){
479d2113
MS
669 # Support for new foo_target() methods.
670 my $method = $section;
671 $method .= '_target' unless $self->can($method);
672
f6d6199c
MS
673 print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
674 my($skipit) = $self->skipcheck($section);
675 if ($skipit){
676 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
677 } else {
678 my(%a) = %{$self->{$section} || {}};
679 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
680 push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
6d6be53e
RGS
681 push @{$self->{RESULT}}, $self->maketext_filter(
682 $self->$method( %a )
683 );
f6d6199c 684 }
232e078e 685 }
8e07c86e 686
e05e23b1 687 push @{$self->{RESULT}}, "\n# End.";
8e07c86e 688
e05e23b1 689 $self;
232e078e
AD
690}
691
1b171b8d 692sub WriteEmptyMakefile {
1e65eb70 693 Carp::croak "WriteEmptyMakefile: Need an even number of args" if @_ % 2;
a8112c7f
IZ
694
695 my %att = @_;
696 my $self = MM->new(\%att);
bfdac1b8
SP
697
698 my $new = $self->{MAKEFILE};
1151960e
IZ
699 my $old = $self->{MAKEFILE_OLD};
700 if (-f $old) {
bfdac1b8 701 _unlink($old) or warn "unlink $old: $!";
479d2113 702 }
1151960e
IZ
703 if ( -f $new ) {
704 _rename($new, $old) or warn "rename $new => $old: $!"
a8112c7f 705 }
a592ba15
RGS
706 open my $mfh, '>', $new or die "open $new for write: $!";
707 print $mfh <<'EOP';
3a0105ce 708all :
1b171b8d 709
3a0105ce 710clean :
1b171b8d 711
3a0105ce 712install :
1b171b8d 713
3a0105ce 714makemakerdflt :
1b171b8d 715
3a0105ce 716test :
1b171b8d
NIS
717
718EOP
a592ba15 719 close $mfh or die "close $new for write: $!";
1b171b8d
NIS
720}
721
e05e23b1
PP
722sub check_manifest {
723 print STDOUT "Checking if your kit is complete...\n";
3b03c0f3 724 require ExtUtils::Manifest;
5e9e174b
MS
725 # avoid warning
726 $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
727 my(@missed) = ExtUtils::Manifest::manicheck();
728 if (@missed) {
f6d6199c
MS
729 print STDOUT "Warning: the following files are missing in your kit:\n";
730 print "\t", join "\n\t", @missed;
731 print STDOUT "\n";
732 print STDOUT "Please inform the author.\n";
8e07c86e 733 } else {
f6d6199c 734 print STDOUT "Looks good\n";
8e07c86e 735 }
8e07c86e
AD
736}
737
e05e23b1
PP
738sub parse_args{
739 my($self, @args) = @_;
5e9e174b 740 foreach (@args) {
f6d6199c 741 unless (m/(.*?)=(.*)/) {
f6d6199c
MS
742 ++$Verbose if m/^verb/;
743 next;
744 }
745 my($name, $value) = ($1, $2);
746 if ($value =~ m/^~(\w+)?/) { # tilde with optional username
747 $value =~ s [^~(\w*)]
748 [$1 ?
749 ((getpwnam($1))[7] || "~$1") :
750 (getpwuid($>))[7]
751 ]ex;
752 }
479d2113
MS
753
754 # Remember the original args passed it. It will be useful later.
755 $self->{ARGS}{uc $name} = $self->{uc $name} = $value;
8e07c86e 756 }
8e07c86e 757
e05e23b1
PP
758 # catch old-style 'potential_libs' and inform user how to 'upgrade'
759 if (defined $self->{potential_libs}){
f6d6199c
MS
760 my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
761 if ($self->{potential_libs}){
762 print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
763 } else {
764 print STDOUT "$msg deleted.\n";
765 }
766 $self->{LIBS} = [$self->{potential_libs}];
767 delete $self->{potential_libs};
8e07c86e 768 }
e05e23b1
PP
769 # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
770 if (defined $self->{ARMAYBE}){
f6d6199c
MS
771 my($armaybe) = $self->{ARMAYBE};
772 print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
773 "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
774 my(%dl) = %{$self->{dynamic_lib} || {}};
775 $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
776 delete $self->{ARMAYBE};
8e07c86e 777 }
e05e23b1 778 if (defined $self->{LDTARGET}){
f6d6199c
MS
779 print STDOUT "LDTARGET should be changed to LDFROM\n";
780 $self->{LDFROM} = $self->{LDTARGET};
781 delete $self->{LDTARGET};
8e07c86e 782 }
e05e23b1
PP
783 # Turn a DIR argument on the command line into an array
784 if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
f6d6199c
MS
785 # So they can choose from the command line, which extensions they want
786 # the grep enables them to have some colons too much in case they
787 # have to build a list with the shell
788 $self->{DIR} = [grep $_, split ":", $self->{DIR}];
8e07c86e 789 }
f1387719
PP
790 # Turn a INCLUDE_EXT argument on the command line into an array
791 if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
f6d6199c 792 $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
f1387719
PP
793 }
794 # Turn a EXCLUDE_EXT argument on the command line into an array
795 if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
f6d6199c 796 $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
f1387719 797 }
5e9e174b
MS
798
799 foreach my $mmkey (sort keys %$self){
479d2113 800 next if $mmkey eq 'ARGS';
f6d6199c
MS
801 print STDOUT " $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
802 print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
803 unless exists $Recognized_Att_Keys{$mmkey};
e05e23b1 804 }
f1387719 805 $| = 1 if $Verbose;
e05e23b1 806}
8e07c86e 807
e05e23b1
PP
808sub check_hints {
809 my($self) = @_;
810 # We allow extension-specific hints files.
864a5fa8 811
479d2113
MS
812 require File::Spec;
813 my $curdir = File::Spec->curdir;
814
815 my $hint_dir = File::Spec->catdir($curdir, "hints");
816 return unless -d $hint_dir;
8e07c86e 817
e05e23b1 818 # First we look for the best hintsfile we have
f1387719 819 my($hint)="${^O}_$Config{osvers}";
e05e23b1
PP
820 $hint =~ s/\./_/g;
821 $hint =~ s/_$//;
822 return unless $hint;
fed7345c 823
e05e23b1
PP
824 # Also try without trailing minor version numbers.
825 while (1) {
479d2113 826 last if -f File::Spec->catfile($hint_dir, "$hint.pl"); # found
e05e23b1 827 } continue {
f6d6199c 828 last unless $hint =~ s/_[^_]*$//; # nothing to cut off
e05e23b1 829 }
479d2113 830 my $hint_file = File::Spec->catfile($hint_dir, "$hint.pl");
6626a13a
MS
831
832 return unless -f $hint_file; # really there
fed7345c 833
f6d6199c
MS
834 _run_hintfile($self, $hint_file);
835}
836
837sub _run_hintfile {
a592ba15 838 our $self;
f6d6199c
MS
839 local($self) = shift; # make $self available to the hint file.
840 my($hint_file) = shift;
841
479d2113 842 local($@, $!);
39234879 843 print STDERR "Processing hints file $hint_file\n";
479d2113
MS
844
845 # Just in case the ./ isn't on the hint file, which File::Spec can
846 # often strip off, we bung the curdir into @INC
847 local @INC = (File::Spec->curdir, @INC);
848 my $ret = do $hint_file;
849 if( !defined $ret ) {
850 my $error = $@ || $!;
851 print STDERR $error;
75e2e551 852 }
e05e23b1 853}
8e07c86e 854
e05e23b1
PP
855sub mv_all_methods {
856 my($from,$to) = @_;
fed7345c 857
e05e23b1
PP
858 # Here you see the *current* list of methods that are overridable
859 # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
860 # still trying to reduce the list to some reasonable minimum --
861 # because I want to make it easier for the user. A.K.
40000a8c 862
57b1a898
MS
863 local $SIG{__WARN__} = sub {
864 # can't use 'no warnings redefined', 5.6 only
865 warn @_ unless $_[0] =~ /^Subroutine .* redefined/
866 };
5e9e174b 867 foreach my $method (@Overridable) {
fed7345c 868
f6d6199c
MS
869 # We cannot say "next" here. Nick might call MY->makeaperl
870 # which isn't defined right now
871
872 # Above statement was written at 4.23 time when Tk-b8 was
873 # around. As Tk-b9 only builds with 5.002something and MM 5 is
874 # standard, we try to enable the next line again. It was
875 # commented out until MM 5.23
876
877 next unless defined &{"${from}::$method"};
fed7345c 878
a592ba15
RGS
879 {
880 no strict 'refs'; ## no critic
881 *{"${to}::$method"} = \&{"${from}::$method"};
882
883 # If we delete a method, then it will be undefined and cannot
884 # be called. But as long as we have Makefile.PLs that rely on
885 # %MY:: being intact, we have to fill the hole with an
886 # inheriting method:
887
888 {
889 package MY;
890 my $super = "SUPER::".$method;
891 *{$method} = sub {
892 shift->$super(@_);
893 };
894 }
895 }
5d94fbed
AD
896 }
897
e05e23b1
PP
898 # We have to clean out %INC also, because the current directory is
899 # changed frequently and Graham Barr prefers to get his version
900 # out of a History.pl file which is "required" so woudn't get
901 # loaded again in another extension requiring a History.pl
a0d0e21e 902
f1387719
PP
903 # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
904 # to core dump in the middle of a require statement. The required
905 # file was Tk/MMutil.pm. The consequence is, we have to be
906 # extremely careful when we try to give perl a reason to reload a
907 # library with same name. The workaround prefers to drop nothing
908 # from %INC and teach the writers not to use such libraries.
909
910# my $inc;
911# foreach $inc (keys %INC) {
f6d6199c
MS
912# #warn "***$inc*** deleted";
913# delete $INC{$inc};
f1387719 914# }
8e07c86e
AD
915}
916
3b03c0f3 917sub skipcheck {
8e07c86e 918 my($self) = shift;
e05e23b1
PP
919 my($section) = @_;
920 if ($section eq 'dynamic') {
f6d6199c
MS
921 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
922 "in skipped section 'dynamic_bs'\n"
e05e23b1
PP
923 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
924 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
f6d6199c 925 "in skipped section 'dynamic_lib'\n"
e05e23b1 926 if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
8e07c86e 927 }
e05e23b1
PP
928 if ($section eq 'dynamic_lib') {
929 print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
f6d6199c 930 "targets in skipped section 'dynamic_bs'\n"
e05e23b1
PP
931 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
932 }
933 if ($section eq 'static') {
934 print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
f6d6199c 935 "in skipped section 'static_lib'\n"
e05e23b1 936 if $self->{SKIPHASH}{static_lib} && $Verbose;
8e07c86e 937 }
e05e23b1
PP
938 return 'skipped' if $self->{SKIPHASH}{$section};
939 return '';
8e07c86e
AD
940}
941
e05e23b1
PP
942sub flush {
943 my $self = shift;
bfdac1b8
SP
944
945 my $finalname = $self->{MAKEFILE};
1151960e 946 print STDOUT "Writing $finalname for $self->{NAME}\n";
8e07c86e 947
1151960e 948 unlink($finalname, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : ());
a592ba15
RGS
949 open(my $fh,">", "MakeMaker.tmp")
950 or die "Unable to open MakeMaker.tmp: $!";
8e07c86e 951
a592ba15
RGS
952 for my $chunk (@{$self->{RESULT}}) {
953 print $fh "$chunk\n";
8e07c86e 954 }
e05e23b1 955
a592ba15 956 close $fh;
479d2113
MS
957 _rename("MakeMaker.tmp", $finalname) or
958 warn "rename MakeMaker.tmp => $finalname: $!";
e05e23b1 959 chmod 0644, $finalname unless $Is_VMS;
3b03c0f3 960
479d2113
MS
961 my %keep = map { ($_ => 1) } qw(NEEDS_LINKING HAS_LINK_CODE);
962
e0678a30 963 if ($self->{PARENT} && !$self->{_KEEP_AFTER_FLUSH}) {
f6d6199c 964 foreach (keys %$self) { # safe memory
479d2113 965 delete $self->{$_} unless $keep{$_};
f6d6199c 966 }
3b03c0f3
PP
967 }
968
e05e23b1 969 system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
40000a8c
AD
970}
971
479d2113
MS
972
973# This is a rename for OS's where the target must be unlinked first.
974sub _rename {
975 my($src, $dest) = @_;
976 chmod 0666, $dest;
977 unlink $dest;
978 return rename $src, $dest;
979}
980
dedf98bc
MS
981# This is an unlink for OS's where the target must be writable first.
982sub _unlink {
983 my @files = @_;
984 chmod 0666, @files;
985 return unlink @files;
986}
987
479d2113 988
e05e23b1
PP
989# The following mkbootstrap() is only for installations that are calling
990# the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
991# writes Makefiles, that use ExtUtils::Mkbootstrap directly.
992sub mkbootstrap {
993 die <<END;
994!!! Your Makefile has been built such a long time ago, !!!
995!!! that is unlikely to work with current MakeMaker. !!!
996!!! Please rebuild your Makefile !!!
997END
8e07c86e 998}
005c1a0e 999
e05e23b1
PP
1000# Ditto for mksymlists() as of MakeMaker 5.17
1001sub mksymlists {
1002 die <<END;
1003!!! Your Makefile has been built such a long time ago, !!!
1004!!! that is unlikely to work with current MakeMaker. !!!
1005!!! Please rebuild your Makefile !!!
1006END
4633a7c4
LW
1007}
1008
e05e23b1
PP
1009sub neatvalue {
1010 my($v) = @_;
1011 return "undef" unless defined $v;
1012 my($t) = ref $v;
1013 return "q[$v]" unless $t;
1014 if ($t eq 'ARRAY') {
f6d6199c
MS
1015 my(@m, @neat);
1016 push @m, "[";
1017 foreach my $elem (@$v) {
1018 push @neat, "q[$elem]";
1019 }
1020 push @m, join ", ", @neat;
1021 push @m, "]";
1022 return join "", @m;
e05e23b1
PP
1023 }
1024 return "$v" unless $t eq 'HASH';
1025 my(@m, $key, $val);
3b03c0f3 1026 while (($key,$val) = each %$v){
f6d6199c
MS
1027 last unless defined $key; # cautious programming in case (undef,undef) is true
1028 push(@m,"$key=>".neatvalue($val)) ;
3b03c0f3 1029 }
e05e23b1 1030 return "{ ".join(', ',@m)." }";
4e68a208
AD
1031}
1032
e05e23b1
PP
1033sub selfdocument {
1034 my($self) = @_;
1035 my(@m);
1036 if ($Verbose){
f6d6199c
MS
1037 push @m, "\n# Full list of MakeMaker attribute values:";
1038 foreach my $key (sort keys %$self){
1039 next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
1040 my($v) = neatvalue($self->{$key});
1041 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
1042 $v =~ tr/\n/ /s;
1043 push @m, "# $key => $v";
1044 }
e05e23b1
PP
1045 }
1046 join "\n", @m;
1047}
4e68a208 1048
3b03c0f3
PP
10491;
1050
1051__END__
005c1a0e
AD
1052
1053=head1 NAME
1054
479d2113 1055ExtUtils::MakeMaker - Create a module Makefile
005c1a0e
AD
1056
1057=head1 SYNOPSIS
1058
e0678a30 1059 use ExtUtils::MakeMaker;
005c1a0e 1060
e0678a30 1061 WriteMakefile( ATTRIBUTE => VALUE [, ...] );
8e07c86e 1062
005c1a0e
AD
1063=head1 DESCRIPTION
1064
1065This utility is designed to write a Makefile for an extension module
1066from a Makefile.PL. It is based on the Makefile.SH model provided by
1067Andy Dougherty and the perl5-porters.
1068
1069It splits the task of generating the Makefile into several subroutines
1070that can be individually overridden. Each subroutine returns the text
1071it wishes to have written to the Makefile.
1072
f1387719 1073MakeMaker is object oriented. Each directory below the current
e0678a30 1074directory that contains a Makefile.PL is treated as a separate
f1387719
PP
1075object. This makes it possible to write an unlimited number of
1076Makefiles with a single invocation of WriteMakefile().
8e07c86e 1077
f1387719 1078=head2 How To Write A Makefile.PL
8e07c86e 1079
479d2113 1080See ExtUtils::MakeMaker::Tutorial.
8e07c86e 1081
bab2b58e 1082The long answer is the rest of the manpage :-)
005c1a0e
AD
1083
1084=head2 Default Makefile Behaviour
1085
f1387719 1086The generated Makefile enables the user of the extension to invoke
005c1a0e
AD
1087
1088 perl Makefile.PL # optionally "perl Makefile.PL verbose"
1089 make
8e07c86e
AD
1090 make test # optionally set TEST_VERBOSE=1
1091 make install # See below
005c1a0e
AD
1092
1093The Makefile to be produced may be altered by adding arguments of the
e05e23b1 1094form C<KEY=VALUE>. E.g.
005c1a0e 1095
58d32538 1096 perl Makefile.PL INSTALL_BASE=~
005c1a0e
AD
1097
1098Other interesting targets in the generated Makefile are
1099
1100 make config # to check if the Makefile is up-to-date
8e07c86e
AD
1101 make clean # delete local temp files (Makefile gets renamed)
1102 make realclean # delete derived files (including ./blib)
e05e23b1 1103 make ci # check in all the files in the MANIFEST file
005c1a0e
AD
1104 make dist # see below the Distribution Support section
1105
e05e23b1
PP
1106=head2 make test
1107
bab2b58e 1108MakeMaker checks for the existence of a file named F<test.pl> in the
d5d4ec93
MS
1109current directory and if it exists it execute the script with the
1110proper set of perl C<-I> options.
e05e23b1
PP
1111
1112MakeMaker also checks for any files matching glob("t/*.t"). It will
d5d4ec93
MS
1113execute all matching files in alphabetical order via the
1114L<Test::Harness> module with the C<-I> switches set correctly.
1115
1116If you'd like to see the raw output of your tests, set the
1117C<TEST_VERBOSE> variable to true.
1118
1119 make test TEST_VERBOSE=1
e05e23b1 1120
bab2b58e
AK
1121=head2 make testdb
1122
1123A useful variation of the above is the target C<testdb>. It runs the
1124test under the Perl debugger (see L<perldebug>). If the file
1125F<test.pl> exists in the current directory, it is used for the test.
1126
d5d4ec93 1127If you want to debug some other testfile, set the C<TEST_FILE> variable
bab2b58e
AK
1128thusly:
1129
1130 make testdb TEST_FILE=t/mytest.t
1131
1132By default the debugger is called using C<-d> option to perl. If you
d5d4ec93 1133want to specify some other option, set the C<TESTDB_SW> variable:
bab2b58e
AK
1134
1135 make testdb TESTDB_SW=-Dx
1136
e05e23b1 1137=head2 make install
005c1a0e 1138
8e07c86e 1139make alone puts all relevant files into directories that are named by
f6d6199c
MS
1140the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
1141INST_MAN3DIR. All these default to something below ./blib if you are
1142I<not> building below the perl source directory. If you I<are>
1143building below the perl source, INST_LIB and INST_ARCHLIB default to
1144../../lib, and INST_SCRIPT is not defined.
005c1a0e 1145
e05e23b1
PP
1146The I<install> target of the generated Makefile copies the files found
1147below each of the INST_* directories to their INSTALL*
1148counterparts. Which counterparts are chosen depends on the setting of
1149INSTALLDIRS according to the following table:
005c1a0e 1150
f6d6199c 1151 INSTALLDIRS set to
5c161494 1152 perl site vendor
e05e23b1 1153
479d2113 1154 PERLPREFIX SITEPREFIX VENDORPREFIX
5c161494
MS
1155 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
1156 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
1157 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
002b9267 1158 INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
5c161494
MS
1159 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
1160 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
005c1a0e 1161
8e07c86e
AD
1162The INSTALL... macros in turn default to their %Config
1163($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
005c1a0e 1164
3b03c0f3
PP
1165You can check the values of these variables on your system with
1166
bab2b58e 1167 perl '-V:install.*'
3b03c0f3 1168
f1387719
PP
1169And to check the sequence in which the library directories are
1170searched by perl, run
005c1a0e 1171
f1387719 1172 perl -le 'print join $/, @INC'
005c1a0e 1173
a7d1454b
RGS
1174Sometimes older versions of the module you're installing live in other
1175directories in @INC. Because Perl loads the first version of a module it
1176finds, not the newest, you might accidentally get one of these older
1177versions even after installing a brand new version. To delete I<all other
1178versions of the module you're installing> (not simply older ones) set the
1179C<UNINST> variable.
1180
1181 make install UNINST=1
1182
005c1a0e 1183
58d32538
RGS
1184=head2 INSTALL_BASE
1185
1186INSTALL_BASE can be passed into Makefile.PL to change where your
1187module will be installed. INSTALL_BASE is more like what everyone
1188else calls "prefix" than PREFIX is.
1189
1190To have everything installed in your home directory, do the following.
1191
1e65eb70
SP
1192 # Unix users, INSTALL_BASE=~ works fine
1193 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
58d32538
RGS
1194
1195Like PREFIX, it sets several INSTALL* attributes at once. Unlike
1196PREFIX it is easy to predict where the module will end up. The
1197installation pattern looks like this:
1198
1199 INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
1200 INSTALLPRIVLIB INSTALL_BASE/lib/perl5
1201 INSTALLBIN INSTALL_BASE/bin
1202 INSTALLSCRIPT INSTALL_BASE/bin
1203 INSTALLMAN1DIR INSTALL_BASE/man/man1
1204 INSTALLMAN3DIR INSTALL_BASE/man/man3
1205
1206INSTALL_BASE in MakeMaker and C<--install_base> in Module::Build (as
1207of 0.28) install to the same location. If you want MakeMaker and
1208Module::Build to install to the same location simply set INSTALL_BASE
1209and C<--install_base> to the same location.
1210
1211INSTALL_BASE was added in 6.31.
1212
1213
bab2b58e
AK
1214=head2 PREFIX and LIB attribute
1215
1216PREFIX and LIB can be used to set several INSTALL* attributes in one
58d32538 1217go. Here's an example for installing into your home directory.
bab2b58e 1218
1e65eb70
SP
1219 # Unix users, PREFIX=~ works fine
1220 perl Makefile.PL PREFIX=/path/to/your/home/dir
005c1a0e 1221
f6d6199c
MS
1222This will install all files in the module under your home directory,
1223with man pages and libraries going into an appropriate place (usually
58d32538
RGS
1224~/man and ~/lib). How the exact location is determined is complicated
1225and depends on how your Perl was configured. INSTALL_BASE works more
1226like what other build systems call "prefix" than PREFIX and we
1227recommend you use that instead.
bab2b58e
AK
1228
1229Another way to specify many INSTALL directories with a single
f6d6199c 1230parameter is LIB.
005c1a0e 1231
f6d6199c 1232 perl Makefile.PL LIB=~/lib
005c1a0e 1233
f6d6199c
MS
1234This will install the module's architecture-independent files into
1235~/lib, the architecture-dependent files into ~/lib/$archname.
005c1a0e 1236
bab2b58e 1237Note, that in both cases the tilde expansion is done by MakeMaker, not
e35b8f9e
JH
1238by perl by default, nor by make.
1239
f6d6199c
MS
1240Conflicts between parameters LIB, PREFIX and the various INSTALL*
1241arguments are resolved so that:
e35b8f9e
JH
1242
1243=over 4
1244
1245=item *
1246
1247setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
1248INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
1249
1250=item *
1251
1252without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
1253part of those INSTALL* arguments, even if the latter are explicitly
1254set (but are set to still start with C<$Config{prefix}>).
1255
1256=back
005c1a0e 1257
f6d6199c
MS
1258If the user has superuser privileges, and is not working on AFS or
1259relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
1260INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
1261the best:
005c1a0e 1262
e0678a30
MS
1263 perl Makefile.PL;
1264 make;
1265 make test
005c1a0e
AD
1266 make install
1267
8e07c86e 1268make install per default writes some documentation of what has been
e05e23b1
PP
1269done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1270can be bypassed by calling make pure_install.
8e07c86e
AD
1271
1272=head2 AFS users
1273
1274will have to specify the installation directories as these most
1275probably have changed since perl itself has been installed. They will
1276have to do this by calling
1277
e05e23b1 1278 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
f6d6199c 1279 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
8e07c86e
AD
1280 make
1281
e05e23b1
PP
1282Be careful to repeat this procedure every time you recompile an
1283extension, unless you are sure the AFS installation directories are
1284still valid.
005c1a0e 1285
8e07c86e 1286=head2 Static Linking of a new Perl Binary
005c1a0e
AD
1287
1288An extension that is built with the above steps is ready to use on
1289systems supporting dynamic loading. On systems that do not support
1290dynamic loading, any newly created extension has to be linked together
1291with the available resources. MakeMaker supports the linking process
1292by creating appropriate targets in the Makefile whenever an extension
1293is built. You can invoke the corresponding section of the makefile with
1294
1295 make perl
1296
1297That produces a new perl binary in the current directory with all
da7f727a 1298extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
e05e23b1
PP
1299and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1300UNIX, this is called Makefile.aperl (may be system dependent). If you
1301want to force the creation of a new perl, it is recommended, that you
1302delete this Makefile.aperl, so the directories are searched-through
1303for linkable libraries again.
005c1a0e
AD
1304
1305The binary can be installed into the directory where perl normally
1306resides on your machine with
1307
1308 make inst_perl
1309
1310To produce a perl binary with a different name than C<perl>, either say
1311
1312 perl Makefile.PL MAP_TARGET=myperl
1313 make myperl
1314 make inst_perl
1315
1316or say
1317
1318 perl Makefile.PL
1319 make myperl MAP_TARGET=myperl
1320 make inst_perl MAP_TARGET=myperl
1321
1322In any case you will be prompted with the correct invocation of the
1323C<inst_perl> target that installs the new binary into INSTALLBIN.
1324
8e07c86e
AD
1325make inst_perl per default writes some documentation of what has been
1326done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1327can be bypassed by calling make pure_inst_perl.
005c1a0e 1328
e05e23b1
PP
1329Warning: the inst_perl: target will most probably overwrite your
1330existing perl binary. Use with care!
005c1a0e 1331
8e07c86e
AD
1332Sometimes you might want to build a statically linked perl although
1333your system supports dynamic loading. In this case you may explicitly
1334set the linktype with the invocation of the Makefile.PL or make:
1335
1336 perl Makefile.PL LINKTYPE=static # recommended
1337
1338or
1339
1340 make LINKTYPE=static # works on most systems
1341
005c1a0e
AD
1342=head2 Determination of Perl Library and Installation Locations
1343
1344MakeMaker needs to know, or to guess, where certain things are
e05e23b1
PP
1345located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1346during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1347existing modules from), and PERL_INC (header files and C<libperl*.*>).
005c1a0e
AD
1348
1349Extensions may be built either using the contents of the perl source
e05e23b1
PP
1350directory tree or from the installed perl library. The recommended way
1351is to build extensions after you have run 'make install' on perl
1352itself. You can do that in any directory on your hard disk that is not
1353below the perl source tree. The support for extensions below the ext
1354directory of the perl distribution is only good for the standard
1355extensions that come with perl.
005c1a0e
AD
1356
1357If an extension is being built below the C<ext/> directory of the perl
e05e23b1
PP
1358source then MakeMaker will set PERL_SRC automatically (e.g.,
1359C<../..>). If PERL_SRC is defined and the extension is recognized as
1360a standard extension, then other variables default to the following:
005c1a0e
AD
1361
1362 PERL_INC = PERL_SRC
1363 PERL_LIB = PERL_SRC/lib
1364 PERL_ARCHLIB = PERL_SRC/lib
1365 INST_LIB = PERL_LIB
1366 INST_ARCHLIB = PERL_ARCHLIB
1367
1368If an extension is being built away from the perl source then MakeMaker
1369will leave PERL_SRC undefined and default to using the installed copy
1370of the perl library. The other variables default to the following:
1371
e05e23b1
PP
1372 PERL_INC = $archlibexp/CORE
1373 PERL_LIB = $privlibexp
1374 PERL_ARCHLIB = $archlibexp
1375 INST_LIB = ./blib/lib
1376 INST_ARCHLIB = ./blib/arch
005c1a0e
AD
1377
1378If perl has not yet been installed then PERL_SRC can be defined on the
1379command line as shown in the previous section.
1380
005c1a0e 1381
f1387719 1382=head2 Which architecture dependent directory?
005c1a0e 1383
f1387719
PP
1384If you don't want to keep the defaults for the INSTALL* macros,
1385MakeMaker helps you to minimize the typing needed: the usual
1386relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1387by Configure at perl compilation time. MakeMaker supports the user who
1388sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1389then MakeMaker defaults the latter to be the same subdirectory of
1390INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1391otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1392for INSTALLSITELIB and INSTALLSITEARCH.
005c1a0e 1393
f1387719
PP
1394MakeMaker gives you much more freedom than needed to configure
1395internal variables and get different results. It is worth to mention,
1396that make(1) also lets you configure most of the variables that are
1397used in the Makefile. But in the majority of situations this will not
a7665c5e 1398be necessary, and should only be done if the author of a package
f1387719 1399recommends it (or you know what you're doing).
005c1a0e 1400
e05e23b1 1401=head2 Using Attributes and Parameters
005c1a0e 1402
a884ca7c
MS
1403The following attributes may be specified as arguments to WriteMakefile()
1404or as NAME=VALUE pairs on the command line.
005c1a0e 1405
875fa795 1406=over 2
005c1a0e 1407
875fa795
JD
1408=item ABSTRACT
1409
1410One line description of the module. Will be included in PPD file.
1411
1412=item ABSTRACT_FROM
1413
1414Name of the file that contains the package description. MakeMaker looks
1415for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1416the first line in the "=head1 NAME" section. $2 becomes the abstract.
1417
e35b8f9e
JH
1418=item AUTHOR
1419
1420String containing name (and email address) of package author(s). Is used
1421in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1422
875fa795
JD
1423=item BINARY_LOCATION
1424
1425Used when creating PPD files for binary packages. It can be set to a
1426full or relative path or URL to the binary archive for a particular
1427architecture. For example:
1428
f6d6199c 1429 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
875fa795
JD
1430
1431builds a PPD package that references a binary of the C<Agent> package,
20e08411 1432located in the C<x86> directory relative to the PPD itself.
8e07c86e 1433
864a5fa8 1434=item C
8e07c86e 1435
864a5fa8
AD
1436Ref to array of *.c file names. Initialised from a directory scan
1437and the values portion of the XS attribute hash. This is not
1438currently used by MakeMaker but may be handy in Makefile.PLs.
8e07c86e 1439
84902520
TB
1440=item CCFLAGS
1441
1442String that will be included in the compiler call command line between
1443the arguments INC and OPTIMIZE.
1444
864a5fa8 1445=item CONFIG
8e07c86e 1446
864a5fa8
AD
1447Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1448config.sh. MakeMaker will add to CONFIG the following values anyway:
1449ar
1450cc
1451cccdlflags
1452ccdlflags
1453dlext
1454dlsrc
1455ld
1456lddlflags
1457ldflags
1458libc
1459lib_ext
1460obj_ext
1461ranlib
e05e23b1
PP
1462sitelibexp
1463sitearchexp
864a5fa8 1464so
8e07c86e
AD
1465
1466=item CONFIGURE
1467
e05e23b1 1468CODE reference. The subroutine should return a hash reference. The
1fef88e7 1469hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
8e07c86e
AD
1470be determined by some evaluation method.
1471
864a5fa8 1472=item DEFINE
8e07c86e 1473
864a5fa8 1474Something like C<"-DHAVE_UNISTD_H">
8e07c86e 1475
479d2113
MS
1476=item DESTDIR
1477
1478This is the root directory into which the code will be installed. It
1479I<prepends itself to the normal prefix>. For example, if your code
5dca256e
RGS
1480would normally go into F</usr/local/lib/perl> you could set DESTDIR=~/tmp/
1481and installation would go into F<~/tmp/usr/local/lib/perl>.
479d2113
MS
1482
1483This is primarily of use for people who repackage Perl modules.
1484
531e2ba1 1485NOTE: Due to the nature of make, it is important that you put the trailing
5dca256e 1486slash on your DESTDIR. F<~/tmp/> not F<~/tmp>.
479d2113 1487
864a5fa8 1488=item DIR
8e07c86e 1489
864a5fa8
AD
1490Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1491] in ext/SDBM_File
8e07c86e 1492
864a5fa8 1493=item DISTNAME
8e07c86e 1494
479d2113
MS
1495A safe filename for the package.
1496
1497Defaults to NAME above but with :: replaced with -.
1498
1499For example, Foo::Bar becomes Foo-Bar.
1500
1501=item DISTVNAME
1502
1503Your name for distributing the package with the version number
1504included. This is used by 'make dist' to name the resulting archive
1505file.
1506
1507Defaults to DISTNAME-VERSION.
1508
1509For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
1510
1511On some OS's where . has special meaning VERSION_SYM may be used in
1512place of VERSION.
8e07c86e 1513
864a5fa8 1514=item DL_FUNCS
8e07c86e 1515
875fa795
JD
1516Hashref of symbol names for routines to be made available as universal
1517symbols. Each key/value pair consists of the package name and an
1518array of routine names in that package. Used only under AIX, OS/2,
1519VMS and Win32 at present. The routine names supplied will be expanded
1520in the same way as XSUB names are expanded by the XS() macro.
1521Defaults to
8e07c86e 1522
864a5fa8 1523 {"$(NAME)" => ["boot_$(NAME)" ] }
8e07c86e 1524
864a5fa8 1525e.g.
8e07c86e 1526
864a5fa8
AD
1527 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1528 "NetconfigPtr" => [ 'DESTROY'] }
8e07c86e 1529
875fa795
JD
1530Please see the L<ExtUtils::Mksymlists> documentation for more information
1531about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1532
864a5fa8 1533=item DL_VARS
8e07c86e 1534
875fa795
JD
1535Array of symbol names for variables to be made available as universal symbols.
1536Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1537(e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
8e07c86e 1538
f1387719
PP
1539=item EXCLUDE_EXT
1540
1541Array of extension names to exclude when doing a static build. This
1542is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1543details. (e.g. [ qw( Socket POSIX ) ] )
1544
1545This attribute may be most useful when specified as a string on the
de592821 1546command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
f1387719 1547
864a5fa8 1548=item EXE_FILES
8e07c86e 1549
864a5fa8 1550Ref to array of executable files. The files will be copied to the
f1387719 1551INST_SCRIPT directory. Make realclean will delete them from there
864a5fa8 1552again.
8e07c86e 1553
2530b651
MS
1554If your executables start with something like #!perl or
1555#!/usr/bin/perl MakeMaker will change this to the path of the perl
1556'Makefile.PL' was invoked with so the programs will be sure to run
1557properly even if perl is not in /usr/bin/perl.
1558
864a5fa8
AD
1559=item FIRST_MAKEFILE
1560
479d2113
MS
1561The name of the Makefile to be produced. This is used for the second
1562Makefile that will be produced for the MAP_TARGET.
1563
1564Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
1565
1566(Note: we couldn't use MAKEFILE because dmake uses this for something
1567else).
864a5fa8
AD
1568
1569=item FULLPERL
8e07c86e 1570
75e2e551
MS
1571Perl binary able to run this extension, load XS modules, etc...
1572
1573=item FULLPERLRUN
1574
1575Like PERLRUN, except it uses FULLPERL.
1576
1577=item FULLPERLRUNINST
1578
1579Like PERLRUNINST, except it uses FULLPERL.
864a5fa8 1580
762efda7
JD
1581=item FUNCLIST
1582
1583This provides an alternate means to specify function names to be
1584exported from the extension. Its value is a reference to an
1585array of function names to be exported by the extension. These
1586names are passed through unaltered to the linker options file.
1587
864a5fa8
AD
1588=item H
1589
1590Ref to array of *.h file names. Similar to C.
1591
84902520
TB
1592=item IMPORTS
1593
875fa795 1594This attribute is used to specify names to be imported into the
69ff8adf
JH
1595extension. Takes a hash ref.
1596
1597It is only used on OS/2 and Win32.
84902520 1598
864a5fa8
AD
1599=item INC
1600
1601Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1602
f1387719
PP
1603=item INCLUDE_EXT
1604
1605Array of extension names to be included when doing a static build.
1606MakeMaker will normally build with all of the installed extensions when
1607doing a static build, and that is usually the desired behavior. If
1608INCLUDE_EXT is present then MakeMaker will build only with those extensions
1609which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
1610
1611It is not necessary to mention DynaLoader or the current extension when
1612filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
1613only DynaLoader and the current extension will be included in the build.
1614
1615This attribute may be most useful when specified as a string on the
de592821 1616command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
f1387719 1617
864a5fa8
AD
1618=item INSTALLARCHLIB
1619
e05e23b1
PP
1620Used by 'make install', which copies files from INST_ARCHLIB to this
1621directory if INSTALLDIRS is set to perl.
864a5fa8
AD
1622
1623=item INSTALLBIN
1624
5c161494
MS
1625Directory to install binary files (e.g. tkperl) into if
1626INSTALLDIRS=perl.
e05e23b1
PP
1627
1628=item INSTALLDIRS
1629
5c161494
MS
1630Determines which of the sets of installation directories to choose:
1631perl, site or vendor. Defaults to site.
8e07c86e
AD
1632
1633=item INSTALLMAN1DIR
1634
1635=item INSTALLMAN3DIR
1636
5c161494
MS
1637These directories get the man pages at 'make install' time if
1638INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
8e07c86e 1639
5c161494 1640If set to 'none', no man pages will be installed.
e0678a30 1641
864a5fa8 1642=item INSTALLPRIVLIB
8e07c86e 1643
e05e23b1
PP
1644Used by 'make install', which copies files from INST_LIB to this
1645directory if INSTALLDIRS is set to perl.
1646
5c161494
MS
1647Defaults to $Config{installprivlib}.
1648
f1387719
PP
1649=item INSTALLSCRIPT
1650
1651Used by 'make install' which copies files from INST_SCRIPT to this
002b9267 1652directory if INSTALLDIRS=perl.
f1387719 1653
875fa795 1654=item INSTALLSITEARCH
e05e23b1 1655
875fa795 1656Used by 'make install', which copies files from INST_ARCHLIB to this
e05e23b1
PP
1657directory if INSTALLDIRS is set to site (default).
1658
5c161494
MS
1659=item INSTALLSITEBIN
1660
1661Used by 'make install', which copies files from INST_BIN to this
1662directory if INSTALLDIRS is set to site (default).
1663
875fa795 1664=item INSTALLSITELIB
e05e23b1 1665
875fa795 1666Used by 'make install', which copies files from INST_LIB to this
e05e23b1 1667directory if INSTALLDIRS is set to site (default).
8e07c86e 1668
5c161494
MS
1669=item INSTALLSITEMAN1DIR
1670
1671=item INSTALLSITEMAN3DIR
1672
1673These directories get the man pages at 'make install' time if
1674INSTALLDIRS=site (default). Defaults to
1675$(SITEPREFIX)/man/man$(MAN*EXT).
1676
1677If set to 'none', no man pages will be installed.
1678
002b9267
RGS
1679=item INSTALLSITESCRIPT
1680
1681Used by 'make install' which copies files from INST_SCRIPT to this
1682directory if INSTALLDIRS is set to site (default).
1683
5c161494
MS
1684=item INSTALLVENDORARCH
1685
1686Used by 'make install', which copies files from INST_ARCHLIB to this
1687directory if INSTALLDIRS is set to vendor.
1688
1689=item INSTALLVENDORBIN
1690
1691Used by 'make install', which copies files from INST_BIN to this
1692directory if INSTALLDIRS is set to vendor.
1693
1694=item INSTALLVENDORLIB
1695
1696Used by 'make install', which copies files from INST_LIB to this
1697directory if INSTALLDIRS is set to vendor.
1698
1699=item INSTALLVENDORMAN1DIR
1700
1701=item INSTALLVENDORMAN3DIR
1702
1703These directories get the man pages at 'make install' time if
1704INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
1705
1706If set to 'none', no man pages will be installed.
1707
002b9267
RGS
1708=item INSTALLVENDORSCRIPT
1709
1710Used by 'make install' which copies files from INST_SCRIPT to this
1711directory if INSTALLDIRS is set to is set to vendor.
1712
864a5fa8 1713=item INST_ARCHLIB
8e07c86e 1714
864a5fa8 1715Same as INST_LIB for architecture dependent files.
8e07c86e 1716
f1387719
PP
1717=item INST_BIN
1718
1719Directory to put real binary files during 'make'. These will be copied
1720to INSTALLBIN during 'make install'
1721
e35b8f9e
JH
1722=item INST_LIB
1723
1724Directory where we put library files of this extension while building
1725it.
1726
864a5fa8 1727=item INST_MAN1DIR
8e07c86e 1728
864a5fa8 1729Directory to hold the man pages at 'make' time
8e07c86e 1730
864a5fa8 1731=item INST_MAN3DIR
8e07c86e 1732
864a5fa8 1733Directory to hold the man pages at 'make' time
8e07c86e 1734
f1387719
PP
1735=item INST_SCRIPT
1736
1737Directory, where executable files should be installed during
c3fed81c 1738'make'. Defaults to "./blib/script", just to have a dummy location during
f1387719
PP
1739testing. make install will copy the files in INST_SCRIPT to
1740INSTALLSCRIPT.
1741
479d2113
MS
1742=item LD
1743
1744Program to be used to link libraries for dynamic loading.
1745
1746Defaults to $Config{ld}.
1747
a884ca7c
MS
1748=item LDDLFLAGS
1749
1750Any special flags that might need to be passed to ld to create a
1751shared library suitable for dynamic loading. It is up to the makefile
1752to use it. (See L<Config/lddlflags>)
1753
1754Defaults to $Config{lddlflags}.
1755
864a5fa8 1756=item LDFROM
8e07c86e 1757
69ff8adf 1758Defaults to "$(OBJECT)" and is used in the ld command to specify
864a5fa8
AD
1759what files to link/load from (also see dynamic_lib below for how to
1760specify ld flags)
8e07c86e 1761
bab2b58e
AK
1762=item LIB
1763
e35b8f9e 1764LIB should only be set at C<perl Makefile.PL> time but is allowed as a
f6d6199c
MS
1765MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
1766and INSTALLSITELIB to that value regardless any explicit setting of
1767those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
1768are set to the corresponding architecture subdirectory.
bab2b58e 1769
762efda7
JD
1770=item LIBPERL_A
1771
1772The filename of the perllibrary that will be used together with this
1773extension. Defaults to libperl.a.
1774
8e07c86e
AD
1775=item LIBS
1776
1777An anonymous array of alternative library
1778specifications to be searched for (in order) until
864a5fa8 1779at least one library is found. E.g.
8e07c86e
AD
1780
1781 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1782
1783Mind, that any element of the array
1784contains a complete set of arguments for the ld
1785command. So do not specify
1786
1787 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1788
1789See ODBM_File/Makefile.PL for an example, where an array is needed. If
1790you specify a scalar as in
1791
1792 'LIBS' => "-ltcl -ltk -lX11"
1793
1794MakeMaker will turn it into an array with one element.
1795
2977d345
RGS
1796=item LICENSE
1797
1798The licensing terms of your distribution. Generally its "perl" for the
1799same license as Perl itself.
1800
a592ba15 1801See L<Module::Build::API> for the list of options.
2977d345
RGS
1802
1803Defaults to "unknown".
1804
864a5fa8 1805=item LINKTYPE
8e07c86e 1806
e05e23b1
PP
1807'static' or 'dynamic' (default unless usedl=undef in
1808config.sh). Should only be used to force static linking (also see
864a5fa8 1809linkext below).
8e07c86e 1810
2977d345
RGS
1811=item MAKE
1812
1813Variant of make you intend to run the generated Makefile with. This
1814parameter lets Makefile.PL know what make quirks to account for when
1815generating the Makefile.
1816
1817MakeMaker also honors the MAKE environment variable. This parameter
1818takes precedent.
1819
1820Currently the only significant values are 'dmake' and 'nmake' for Windows
1821users.
1822
1823Defaults to $Config{make}.
1824
864a5fa8 1825=item MAKEAPERL
8e07c86e 1826
864a5fa8
AD
1827Boolean which tells MakeMaker, that it should include the rules to
1828make a perl. This is handled automatically as a switch by
1829MakeMaker. The user normally does not need it.
8e07c86e 1830
479d2113
MS
1831=item MAKEFILE_OLD
1832
1833When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
1834backed up at this location.
8e07c86e 1835
479d2113 1836Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
8e07c86e 1837
864a5fa8 1838=item MAN1PODS
8e07c86e 1839
864a5fa8
AD
1840Hashref of pod-containing files. MakeMaker will default this to all
1841EXE_FILES files that include POD directives. The files listed
1842here will be converted to man pages and installed as was requested
1843at Configure time.
8e07c86e 1844
864a5fa8 1845=item MAN3PODS
8e07c86e 1846
bfa2a9ad
A
1847Hashref that assigns to *.pm and *.pod files the files into which the
1848manpages are to be written. MakeMaker parses all *.pod and *.pm files
1849for POD directives. Files that contain POD will be the default keys of
1850the MAN3PODS hashref. These will then be converted to man pages during
1851C<make> and will be installed during C<make install>.
8e07c86e 1852
864a5fa8 1853=item MAP_TARGET
8e07c86e 1854
864a5fa8
AD
1855If it is intended, that a new perl binary be produced, this variable
1856may hold a name for that binary. Defaults to perl
8e07c86e 1857
2e65e370
SH
1858=item META_ADD
1859
1860=item META_MERGE
1861
1862A hashrefs of items to add to the F<META.yml>.
1863
1864They differ in how they behave if they have the same key as the
1865default metadata. META_ADD will override the default value with it's
1866own. META_MERGE will merge its value with the default.
1867
1868Unless you want to override the defaults, prefer META_MERGE so as to
1869get the advantage of any future defaults.
1870
bf87a6a1
NC
1871=item MIN_PERL_VERSION
1872
1873The minimum required version of Perl for this distribution.
1874
1875Either 5.006001 or 5.6.1 format is acceptable.
1876
864a5fa8 1877=item MYEXTLIB
4633a7c4 1878
864a5fa8
AD
1879If the extension links to a library that it builds set this to the
1880name of the library (see SDBM_File)
4633a7c4 1881
864a5fa8 1882=item NAME
8e07c86e 1883
864a5fa8
AD
1884Perl module name for this extension (DBD::Oracle). This will default
1885to the directory name but should be explicitly defined in the
1886Makefile.PL.
8e07c86e 1887
864a5fa8 1888=item NEEDS_LINKING
8e07c86e 1889
a7665c5e 1890MakeMaker will figure out if an extension contains linkable code
864a5fa8 1891anywhere down the directory tree, and will set this variable
a7665c5e 1892accordingly, but you can speed it up a very little bit if you define
864a5fa8 1893this boolean variable yourself.
8e07c86e 1894
e05e23b1
PP
1895=item NOECHO
1896
479d2113
MS
1897Command so make does not print the literal commands its running.
1898
1899By setting it to an empty string you can generate a Makefile that
1900prints all commands. Mainly used in debugging MakeMaker itself.
1901
1902Defaults to C<@>.
e05e23b1 1903
864a5fa8 1904=item NORECURS
8e07c86e 1905
e05e23b1 1906Boolean. Attribute to inhibit descending into subdirectories.
8e07c86e 1907
1df8d179
MS
1908=item NO_META
1909
1910When true, suppresses the generation and addition to the MANIFEST of
1911the META.yml module meta-data file during 'make distdir'.
1912
1913Defaults to false.
1914
762efda7
JD
1915=item NO_VC
1916
a7665c5e 1917In general, any generated Makefile checks for the current version of
762efda7
JD
1918MakeMaker and the version the Makefile was built under. If NO_VC is
1919set, the version check is neglected. Do not write this into your
1920Makefile.PL, use it interactively instead.
1921
864a5fa8 1922=item OBJECT
8e07c86e 1923
864a5fa8
AD
1924List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1925string containing all object files, e.g. "tkpBind.o
1926tkpButton.o tkpCanvas.o"
8e07c86e 1927
e35b8f9e
JH
1928(Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1929
3b03c0f3
PP
1930=item OPTIMIZE
1931
1932Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1933passed to subdirectory makes.
1934
864a5fa8 1935=item PERL
8e07c86e 1936
864a5fa8 1937Perl binary for tasks that can be done by miniperl
8e07c86e 1938
da7f727a
JH
1939=item PERL_CORE
1940
1941Set only when MakeMaker is building the extensions of the Perl core
1942distribution.
1943
864a5fa8 1944=item PERLMAINCC
005c1a0e 1945
864a5fa8
AD
1946The call to the program that is able to compile perlmain.c. Defaults
1947to $(CC).
005c1a0e 1948
864a5fa8 1949=item PERL_ARCHLIB
005c1a0e 1950
da7f727a
JH
1951Same as for PERL_LIB, but for architecture dependent files.
1952
1953Used only when MakeMaker is building the extensions of the Perl core
1954distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
1955and adding it would get in the way of PERL5LIB).
8e07c86e 1956
864a5fa8 1957=item PERL_LIB
8e07c86e 1958
864a5fa8 1959Directory containing the Perl library to use.
8e07c86e 1960
da7f727a
JH
1961Used only when MakeMaker is building the extensions of the Perl core
1962distribution (because normally $(PERL_LIB) is automatically in @INC,
1963and adding it would get in the way of PERL5LIB).
1964
e35b8f9e
JH
1965=item PERL_MALLOC_OK
1966
1967defaults to 0. Should be set to TRUE if the extension can work with
1968the memory allocation routines substituted by the Perl malloc() subsystem.
1969This should be applicable to most extensions with exceptions of those
1970
1971=over 4
1972
1973=item *
1974
1975with bugs in memory allocations which are caught by Perl's malloc();
1976
1977=item *
1978
1979which interact with the memory allocator in other ways than via
1980malloc(), realloc(), free(), calloc(), sbrk() and brk();
1981
1982=item *
1983
1984which rely on special alignment which is not provided by Perl's malloc().
1985
1986=back
1987
1988B<NOTE.> Negligence to set this flag in I<any one> of loaded extension
1989nullifies many advantages of Perl's malloc(), such as better usage of
1990system resources, error detection, memory usage reporting, catchable failure
1991of memory allocations, etc.
1992
479d2113
MS
1993=item PERLPREFIX
1994
1995Directory under which core modules are to be installed.
1996
1997Defaults to $Config{installprefixexp} falling back to
1998$Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1999$Config{installprefixexp} not exist.
2000
2001Overridden by PREFIX.
2002
da7f727a
JH
2003=item PERLRUN
2004
75e2e551
MS
2005Use this instead of $(PERL) when you wish to run perl. It will set up
2006extra necessary flags for you.
f6d6199c 2007
ffbaec2a 2008=item PERLRUNINST
f6d6199c 2009
75e2e551
MS
2010Use this instead of $(PERL) when you wish to run perl to work with
2011modules. It will add things like -I$(INST_ARCH) and other necessary
2012flags so perl can see the modules you're about to install.
f6d6199c 2013
864a5fa8 2014=item PERL_SRC
8e07c86e 2015
864a5fa8
AD
2016Directory containing the Perl source code (use of this should be
2017avoided, it may be undefined)
8e07c86e 2018
2366100d
A
2019=item PERM_RW
2020
de592821 2021Desired permission for read/writable files. Defaults to C<644>.
2366100d
A
2022See also L<MM_Unix/perm_rw>.
2023
2024=item PERM_RWX
2025
2026Desired permission for executable files. Defaults to C<755>.
2027See also L<MM_Unix/perm_rwx>.
2028
864a5fa8 2029=item PL_FILES
8e07c86e 2030
7292dc67
RGS
2031MakeMaker can run programs to generate files for you at build time.
2032By default any file named *.PL (except Makefile.PL and Build.PL) in
2033the top level directory will be assumed to be a Perl program and run
2034passing its own basename in as an argument. For example...
2035
2036 perl foo.PL foo
2037
2038This behavior can be overridden by supplying your own set of files to
2039search. PL_FILES accepts a hash ref, the key being the file to run
2040and the value is passed in as the first argument when the PL file is run.
2041
41e5fcb0 2042 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
7292dc67
RGS
2043
2044Would run bin/foobar.PL like this:
2045
2046 perl bin/foobar.PL bin/foobar
2047
2048If multiple files from one program are desired an array ref can be used.
2049
41e5fcb0 2050 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
8e07c86e 2051
7292dc67 2052In this case the program will be run multiple times using each target file.
8e07c86e 2053
7292dc67
RGS
2054 perl bin/foobar.PL bin/foobar1
2055 perl bin/foobar.PL bin/foobar2
3aa35033 2056
4325052d
RGS
2057PL files are normally run B<after> pm_to_blib and include INST_LIB and
2058INST_ARCH in its C<@INC> so the just built modules can be
2059accessed... unless the PL file is making a module (or anything else in
2060PM) in which case it is run B<before> pm_to_blib and does not include
2061INST_LIB and INST_ARCH in its C<@INC>. This apparently odd behavior
2062is there for backwards compatibility (and its somewhat DWIM).
41e5fcb0 2063
8e07c86e 2064
864a5fa8 2065=item PM
8e07c86e 2066
864a5fa8 2067Hashref of .pm files and *.pl files to be installed. e.g.
8e07c86e 2068
864a5fa8 2069 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
8e07c86e 2070
a3cb178b
GS
2071By default this will include *.pm and *.pl and the files found in
2072the PMLIBDIRS directories. Defining PM in the
864a5fa8 2073Makefile.PL will override PMLIBDIRS.
8e07c86e 2074
864a5fa8 2075=item PMLIBDIRS
8e07c86e 2076
864a5fa8 2077Ref to array of subdirectories containing library files. Defaults to
a3cb178b 2078[ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
864a5fa8
AD
2079they contain will be installed in the corresponding location in the
2080library. A libscan() method can be used to alter the behaviour.
2081Defining PM in the Makefile.PL will override PMLIBDIRS.
8e07c86e 2082
e35b8f9e
JH
2083(Where BASEEXT is the last component of NAME.)
2084
131aa089
RM
2085=item PM_FILTER
2086
2087A filter program, in the traditional Unix sense (input from stdin, output
2088to stdout) that is passed on each .pm file during the build (in the
2089pm_to_blib() phase). It is empty by default, meaning no filtering is done.
2090
2091Great care is necessary when defining the command if quoting needs to be
2092done. For instance, you would need to say:
2093
2094 {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
2095
3c4b39be 2096to remove all the leading comments on the fly during the build. The
131aa089
RM
2097extra \\ are necessary, unfortunately, because this variable is interpolated
2098within the context of a Perl program built on the command line, and double
2099quotes are what is used with the -e switch to build that command line. The
2100# is escaped for the Makefile, since what is going to be generated will then
2101be:
2102
2103 PM_FILTER = grep -v \"^\#\"
2104
2105Without the \\ before the #, we'd have the start of a Makefile comment,
2106and the macro would be incorrectly defined.
2107
2aea4d40
JD
2108=item POLLUTE
2109
2110Release 5.005 grandfathered old global symbol names by providing preprocessor
a7665c5e 2111macros for extension source compatibility. As of release 5.6, these
2aea4d40
JD
2112preprocessor definitions are not available by default. The POLLUTE flag
2113specifies that the old names should still be defined:
2114
2115 perl Makefile.PL POLLUTE=1
2116
2117Please inform the module author if this is necessary to successfully install
a7665c5e 2118a module under 5.6 or later.
2aea4d40 2119
875fa795
JD
2120=item PPM_INSTALL_EXEC
2121
20e08411 2122Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
875fa795
JD
2123
2124=item PPM_INSTALL_SCRIPT
2125
2126Name of the script that gets executed by the Perl Package Manager after
2127the installation of a package.
2128
864a5fa8 2129=item PREFIX
8e07c86e 2130
f6d6199c
MS
2131This overrides all the default install locations. Man pages,
2132libraries, scripts, etc... MakeMaker will try to make an educated
2133guess about where to place things under the new PREFIX based on your
2134Config defaults. Failing that, it will fall back to a structure
2135which should be sensible for your platform.
2136
2137If you specify LIB or any INSTALL* variables they will not be effected
2138by the PREFIX.
a4260cbc 2139
b2340c53
K
2140=item PREREQ_FATAL
2141
2142Bool. If this parameter is true, failing to have the required modules
bfdac1b8
SP
2143(or the right versions thereof) will be fatal. C<perl Makefile.PL>
2144will C<die> instead of simply informing the user of the missing dependencies.
b2340c53 2145
bfdac1b8
SP
2146It is I<extremely> rare to have to use C<PREREQ_FATAL>. Its use by module
2147authors is I<strongly discouraged> and should never be used lightly.
2148Module installation tools have ways of resolving umet dependencies but
2149to do that they need a F<Makefile>. Using C<PREREQ_FATAL> breaks this.
2150That's bad.
b2340c53 2151
bfdac1b8
SP
2152The only situation where it is appropriate is when you have
2153dependencies that are indispensible to actually I<write> a
2154F<Makefile>. For example, MakeMaker's F<Makefile.PL> needs L<File::Spec>.
2155If its not available it cannot write the F<Makefile>.
b2340c53 2156
bfdac1b8
SP
2157Note: see L<Test::Harness> for a shortcut for stopping tests early
2158if you are missing dependencies and are afraid that users might
2159use your module with an incomplete environment.
b2340c53 2160
d5d4ec93
MS
2161=item PREREQ_PM
2162
2163Hashref: Names of modules that need to be available to run this
2164extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
2165desired version is the value. If the required version number is 0, we
2166only check if any version is installed already.
2167
88d69b28
JH
2168=item PREREQ_PRINT
2169
2170Bool. If this parameter is true, the prerequisites will be printed to
2c91f887
JH
2171stdout and MakeMaker will exit. The output format is an evalable hash
2172ref.
88d69b28 2173
bf87a6a1
NC
2174 $PREREQ_PM = {
2175 'A::B' => Vers1,
2176 'C::D' => Vers2,
2177 ...
2178 };
2179
2180If a distribution defines a minimal required perl version, this is
2181added to the output as an additional line of the form:
2182
2183 $MIN_PERL_VERSION = '5.008001';
88d69b28
JH
2184
2185=item PRINT_PREREQ
2186
2187RedHatism for C<PREREQ_PRINT>. The output format is different, though:
2188
2189 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
2190
bf87a6a1
NC
2191A minimal required perl version, if present, will look like this:
2192
2193 perl(perl)>=5.008001
2194
5c161494
MS
2195=item SITEPREFIX
2196
479d2113
MS
2197Like PERLPREFIX, but only for the site install locations.
2198
2199Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
2200an explicit siteprefix in the Config. In those cases
2201$Config{installprefix} will be used.
5c161494 2202
479d2113 2203Overridable by PREFIX
5c161494 2204
bb68fe9e
AT
2205=item SIGN
2206
7292dc67
RGS
2207When true, perform the generation and addition to the MANIFEST of the
2208SIGNATURE file in the distdir during 'make distdir', via 'cpansign
2209-s'.
bb68fe9e
AT
2210
2211Note that you need to install the Module::Signature module to
2212perform this operation.
2213
2214Defaults to false.
2215
864a5fa8 2216=item SKIP
8e07c86e 2217
da7f727a 2218Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
a7665c5e
GS
2219Makefile. Caution! Do not use the SKIP attribute for the negligible
2220speedup. It may seriously damage the resulting Makefile. Only use it
f1387719 2221if you really need it.
8e07c86e 2222
864a5fa8 2223=item TYPEMAPS
8e07c86e 2224
864a5fa8
AD
2225Ref to array of typemap file names. Use this when the typemaps are
2226in some directory other than the current directory or when they are
2227not named B<typemap>. The last typemap in the list takes
2228precedence. A typemap in the current directory has highest
2229precedence, even if it isn't listed in TYPEMAPS. The default system
2230typemap has lowest precedence.
8e07c86e 2231
5c161494
MS
2232=item VENDORPREFIX
2233
479d2113
MS
2234Like PERLPREFIX, but only for the vendor install locations.
2235
2236Defaults to $Config{vendorprefixexp}.
5c161494 2237
479d2113 2238Overridable by PREFIX
5c161494 2239
45bc4d3a
JH
2240=item VERBINST
2241
2242If true, make install will be verbose
2243
864a5fa8 2244=item VERSION
8e07c86e 2245
864a5fa8
AD
2246Your version number for distributing the package. This defaults to
22470.1.
8e07c86e 2248
0d8023a2
PP
2249=item VERSION_FROM
2250
2251Instead of specifying the VERSION in the Makefile.PL you can let
2252MakeMaker parse a file to determine the version number. The parsing
2253routine requires that the file named by VERSION_FROM contains one
2254single line to compute the version number. The first line in the file
2255that contains the regular expression
2256
84902520 2257 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
0d8023a2
PP
2258
2259will be evaluated with eval() and the value of the named variable
2260B<after> the eval() will be assigned to the VERSION attribute of the
2261MakeMaker object. The following lines will be parsed o.k.:
2262
a592ba15
RGS
2263 $VERSION = '1.00';
2264 *VERSION = \'1.01';
bf87a6a1 2265 ($VERSION) = q$Revision$ =~ /(\d+)/g;
0d8023a2 2266 $FOO::VERSION = '1.10';
84902520 2267 *FOO::VERSION = \'1.11';
0d8023a2
PP
2268
2269but these will fail:
2270
a592ba15
RGS
2271 # Bad
2272 my $VERSION = '1.01';
2273 local $VERSION = '1.02';
0d8023a2
PP
2274 local $FOO::VERSION = '1.30';
2275
a592ba15 2276"Version strings" are incompatible should not be used.
bfdac1b8 2277
a592ba15
RGS
2278 # Bad
2279 $VERSION = 1.2.3;
2280 $VERSION = v1.2.3;
bfdac1b8 2281
a592ba15
RGS
2282L<version> objects are fine. As of MakeMaker 6.35 version.pm will be
2283automatically loaded, but you must declare the dependency on version.pm.
2284For compatibility with older MakeMaker you should load on the same line
2285as $VERSION is declared.
bfdac1b8
SP
2286
2287 # All on one line
2288 use version; our $VERSION = qv(1.2.3);
2289
e35b8f9e
JH
2290(Putting C<my> or C<local> on the preceding line will work o.k.)
2291
84902520
TB
2292The file named in VERSION_FROM is not added as a dependency to
2293Makefile. This is not really correct, but it would be a major pain
2294during development to have to rewrite the Makefile for any smallish
2295change in that file. If you want to make sure that the Makefile
2296contains the correct VERSION macro after any change of the file, you
2297would have to do something like
2298
2299 depend => { Makefile => '$(VERSION_FROM)' }
2300
2301See attribute C<depend> below.
0d8023a2 2302
479d2113
MS
2303=item VERSION_SYM
2304
2305A sanitized VERSION with . replaced by _. For places where . has
2306special meaning (some filesystems, RCS labels, etc...)
2307
864a5fa8 2308=item XS
8e07c86e 2309
864a5fa8 2310Hashref of .xs files. MakeMaker will default this. e.g.
8e07c86e 2311
864a5fa8 2312 {'name_of_file.xs' => 'name_of_file.c'}
8e07c86e 2313
864a5fa8
AD
2314The .c files will automatically be included in the list of files
2315deleted by a make clean.
4633a7c4 2316
864a5fa8 2317=item XSOPT
8e07c86e 2318
864a5fa8
AD
2319String of options to pass to xsubpp. This might include C<-C++> or
2320C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
2321that purpose.
8e07c86e 2322
864a5fa8 2323=item XSPROTOARG
4633a7c4 2324
4e68a208 2325May be set to an empty string, which is identical to C<-prototypes>, or
864a5fa8 2326C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
4e68a208
AD
2327defaults to the empty string.
2328
0d8023a2
PP
2329=item XS_VERSION
2330
2331Your version number for the .xs file of this package. This defaults
2332to the value of the VERSION attribute.
2333
8e07c86e
AD
2334=back
2335
2336=head2 Additional lowercase attributes
2337
2338can be used to pass parameters to the methods which implement that
531e2ba1
JH
2339part of the Makefile. Parameters are specified as a hash ref but are
2340passed to the method as a hash.
8e07c86e
AD
2341
2342=over 2
2343
864a5fa8 2344=item clean
8e07c86e 2345
864a5fa8
AD
2346 {FILES => "*.xyz foo"}
2347
c07a80fd
PP
2348=item depend
2349
3c4b39be 2350 {ANY_TARGET => ANY_DEPENDENCY, ...}
c07a80fd 2351
e35b8f9e
JH
2352(ANY_TARGET must not be given a double-colon rule by MakeMaker.)
2353
864a5fa8
AD
2354=item dist
2355
5f8e730b 2356 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
3b03c0f3 2357 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
f1387719 2358 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
864a5fa8
AD
2359
2360If you specify COMPRESS, then SUFFIX should also be altered, as it is
2361needed to tell make the target file of the compression. Setting
2362DIST_CP to ln can be useful, if you need to preserve the timestamps on
2363your files. DIST_CP can take the values 'cp', which copies the file,
2364'ln', which links the file, and 'best' which copies symbolic links and
2365links the rest. Default is 'best'.
2366
2367=item dynamic_lib
2368
0d8023a2 2369 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
8e07c86e 2370
8e07c86e
AD
2371=item linkext
2372
2373 {LINKTYPE => 'static', 'dynamic' or ''}
2374
864a5fa8 2375NB: Extensions that have nothing but *.pm files had to say
8e07c86e
AD
2376
2377 {LINKTYPE => ''}
2378
864a5fa8 2379with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
a7665c5e 2380can be deleted safely. MakeMaker recognizes when there's nothing to
864a5fa8 2381be linked.
8e07c86e 2382
864a5fa8 2383=item macro
8e07c86e 2384
864a5fa8 2385 {ANY_MACRO => ANY_VALUE, ...}
8e07c86e 2386
531e2ba1
JH
2387=item postamble
2388
2389Anything put here will be passed to MY::postamble() if you have one.
2390
8e07c86e
AD
2391=item realclean
2392
2393 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
2394
f2f614a6
GS
2395=item test
2396
2397 {TESTS => 't/*.t'}
2398
8e07c86e
AD
2399=item tool_autosplit
2400
f2f614a6 2401 {MAXLEN => 8}
005c1a0e
AD
2402
2403=back
2404
2405=head2 Overriding MakeMaker Methods
2406
2407If you cannot achieve the desired Makefile behaviour by specifying
2408attributes you may define private subroutines in the Makefile.PL.
e0678a30 2409Each subroutine returns the text it wishes to have written to
005c1a0e
AD
2410the Makefile. To override a section of the Makefile you can
2411either say:
2412
f6d6199c 2413 sub MY::c_o { "new literal text" }
005c1a0e
AD
2414
2415or you can edit the default by saying something like:
2416
e0678a30
MS
2417 package MY; # so that "SUPER" works right
2418 sub c_o {
f6d6199c
MS
2419 my $inherited = shift->SUPER::c_o(@_);
2420 $inherited =~ s/old text/new text/;
2421 $inherited;
2422 }
8e07c86e 2423
bdda3fbd
PJ
2424If you are running experiments with embedding perl as a library into
2425other applications, you might find MakeMaker is not sufficient. You'd
2426better have a look at ExtUtils::Embed which is a collection of utilities
2427for embedding.
005c1a0e
AD
2428
2429If you still need a different solution, try to develop another
bdda3fbd 2430subroutine that fits your needs and submit the diffs to
a7d1454b 2431C<makemaker@perl.org>
005c1a0e 2432
e0678a30
MS
2433For a complete description of all MakeMaker methods see
2434L<ExtUtils::MM_Unix>.
3b03c0f3
PP
2435
2436Here is a simple example of how to add a new target to the generated
2437Makefile:
2438
2439 sub MY::postamble {
e0678a30 2440 return <<'MAKE_FRAG';
3b03c0f3 2441 $(MYEXTLIB): sdbm/Makefile
f6d6199c 2442 cd sdbm && $(MAKE) all
e0678a30
MS
2443
2444 MAKE_FRAG
3b03c0f3
PP
2445 }
2446
a884ca7c
MS
2447=head2 The End Of Cargo Cult Programming
2448
2449WriteMakefile() now does some basic sanity checks on its parameters to
2450protect against typos and malformatted values. This means some things
2451which happened to work in the past will now throw warnings and
2452possibly produce internal errors.
2453
2454Some of the most common mistakes:
2455
2456=over 2
2457
76ca89ed 2458=item C<< MAN3PODS => ' ' >>
a884ca7c 2459
3c4b39be 2460This is commonly used to suppress the creation of man pages. MAN3PODS
a884ca7c
MS
2461takes a hash ref not a string, but the above worked by accident in old
2462versions of MakeMaker.
2463
76ca89ed 2464The correct code is C<< MAN3PODS => { } >>.
a884ca7c
MS
2465
2466=back
2467
3b03c0f3 2468
f1387719
PP
2469=head2 Hintsfile support
2470
2471MakeMaker.pm uses the architecture specific information from
2472Config.pm. In addition it evaluates architecture specific hints files
2473in a C<hints/> directory. The hints files are expected to be named
2474like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
2475name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
2476MakeMaker within the WriteMakefile() subroutine, and can be used to
2477execute commands as well as to include special variables. The rules
2478which hintsfile is chosen are the same as in Configure.
2479
2480The hintsfile is eval()ed immediately after the arguments given to
2481WriteMakefile are stuffed into a hash reference $self but before this
2482reference becomes blessed. So if you want to do the equivalent to
2483override or create an attribute you would say something like
2484
2485 $self->{LIBS} = ['-ldbm -lucb -lc'];
2486
005c1a0e
AD
2487=head2 Distribution Support
2488
2489For authors of extensions MakeMaker provides several Makefile
2490targets. Most of the support comes from the ExtUtils::Manifest module,
2491where additional documentation can be found.
2492
2493=over 4
2494
2495=item make distcheck
8e07c86e 2496
005c1a0e
AD
2497reports which files are below the build directory but not in the
2498MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
2499details)
2500
4633a7c4
LW
2501=item make skipcheck
2502
2503reports which files are skipped due to the entries in the
2504C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
2505details)
2506
005c1a0e 2507=item make distclean
8e07c86e 2508
005c1a0e 2509does a realclean first and then the distcheck. Note that this is not
a7665c5e 2510needed to build a new distribution as long as you are sure that the
005c1a0e
AD
2511MANIFEST file is ok.
2512
2513=item make manifest
8e07c86e 2514
005c1a0e
AD
2515rewrites the MANIFEST file, adding all remaining files found (See
2516ExtUtils::Manifest::mkmanifest() for details)
2517
2518=item make distdir
8e07c86e 2519
005c1a0e
AD
2520Copies all the files that are in the MANIFEST file to a newly created
2521directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
2522exists, it will be removed first.
2523
7292dc67 2524Additionally, it will create a META.yml module meta-data file in the
bfdac1b8 2525distdir and add this to the distdir's MANIFEST. You can shut this
7292dc67 2526behavior off with the NO_META flag.
1df8d179 2527
f6d6199c 2528=item make disttest
8e07c86e
AD
2529
2530Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
4633a7c4 2531a make test in that directory.
8e07c86e 2532
005c1a0e 2533=item make tardist
8e07c86e 2534
3b03c0f3 2535First does a distdir. Then a command $(PREOP) which defaults to a null
bfdac1b8 2536command, followed by $(TO_UNIX), which defaults to a null command under
f1387719
PP
2537UNIX, and will convert files in distribution directory to UNIX format
2538otherwise. Next it runs C<tar> on that directory into a tarfile and
3b03c0f3
PP
2539deletes the directory. Finishes with a command $(POSTOP) which
2540defaults to a null command.
005c1a0e
AD
2541
2542=item make dist
8e07c86e 2543
005c1a0e
AD
2544Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
2545
2546=item make uutardist
8e07c86e 2547
005c1a0e
AD
2548Runs a tardist first and uuencodes the tarfile.
2549
2550=item make shdist
8e07c86e 2551
3b03c0f3
PP
2552First does a distdir. Then a command $(PREOP) which defaults to a null
2553command. Next it runs C<shar> on that directory into a sharfile and
2554deletes the intermediate directory again. Finishes with a command
2555$(POSTOP) which defaults to a null command. Note: For shdist to work
2556properly a C<shar> program that can handle directories is mandatory.
2557
2558=item make zipdist
2559
2560First does a distdir. Then a command $(PREOP) which defaults to a null
2561command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
2562zipfile. Then deletes that directory. Finishes with a command
2563$(POSTOP) which defaults to a null command.
005c1a0e
AD
2564
2565=item make ci
8e07c86e
AD
2566
2567Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2568
2569=back
005c1a0e
AD
2570
2571Customization of the dist targets can be done by specifying a hash
2572reference to the dist attribute of the WriteMakefile call. The
2573following parameters are recognized:
2574
8e07c86e 2575 CI ('ci -u')
5f8e730b 2576 COMPRESS ('gzip --best')
005c1a0e 2577 POSTOP ('@ :')
8e07c86e 2578 PREOP ('@ :')
f1387719 2579 TO_UNIX (depends on the system)
8e07c86e
AD
2580 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
2581 SHAR ('shar')
5f8e730b 2582 SUFFIX ('.gz')
8e07c86e
AD
2583 TAR ('tar')
2584 TARFLAGS ('cvf')
3b03c0f3
PP
2585 ZIP ('zip')
2586 ZIPFLAGS ('-r')
005c1a0e
AD
2587
2588An example:
2589
5f8e730b 2590 WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
005c1a0e 2591
1df8d179
MS
2592
2593=head2 Module Meta-Data
2594
2595Long plaguing users of MakeMaker based modules has been the problem of
2596getting basic information about the module out of the sources
2597I<without> running the F<Makefile.PL> and doing a bunch of messy
2598heuristics on the resulting F<Makefile>. To this end a simple module
2599meta-data file has been introduced, F<META.yml>.
2600
2601F<META.yml> is a YAML document (see http://www.yaml.org) containing
2602basic information about the module (name, version, prerequisites...)
2603in an easy to read format. The format is developed and defined by the
64964e6d
JH
2604Module::Build developers (see
2605http://module-build.sourceforge.net/META-spec.html)
1df8d179
MS
2606
2607MakeMaker will automatically generate a F<META.yml> file for you and
2608add it to your F<MANIFEST> as part of the 'distdir' target (and thus
2609the 'dist' target). This is intended to seamlessly and rapidly
2610populate CPAN with module meta-data. If you wish to shut this feature
2611off, set the C<NO_META> C<WriteMakefile()> flag to true.
2612
2613
1b171b8d
NIS
2614=head2 Disabling an extension
2615
2616If some events detected in F<Makefile.PL> imply that there is no way
2617to create the Module, but this is a normal state of things, then you
2618can create a F<Makefile> which does nothing, but succeeds on all the
2619"usual" build targets. To do so, use
2620
1e65eb70
SP
2621 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
2622 WriteEmptyMakefile();
1b171b8d
NIS
2623
2624instead of WriteMakefile().
2625
2626This may be useful if other modules expect this module to be I<built>
2627OK, as opposed to I<work> OK (say, this system-dependent module builds
2628in a subdirectory of some other distribution, or is listed as a
2629dependency in a CPAN::Bundle, but the functionality is supported by
2630different means on the current architecture).
2631
479d2113
MS
2632=head2 Other Handy Functions
2633
2634=over 4
2635
2636=item prompt
2637
2638 my $value = prompt($message);
2639 my $value = prompt($message, $default);
2640
2641The C<prompt()> function provides an easy way to request user input
2642used to write a makefile. It displays the $message as a prompt for
2643input. If a $default is provided it will be used as a default. The
2644function returns the $value selected by the user.
2645
2646If C<prompt()> detects that it is not running interactively and there
2647is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
2648is set to true, the $default will be used without prompting. This
2649prevents automated processes from blocking on user input.
2650
2651If no $default is provided an empty string will be used instead.
2652
2653=back
2654
2655
6ce21ffa
GS
2656=head1 ENVIRONMENT
2657
479d2113 2658=over 4
6ce21ffa 2659
2443aee5 2660=item PERL_MM_OPT
6ce21ffa
GS
2661
2662Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2663C<WriteMakefile()>. The string is split on whitespace, and the result
2664is processed before any actual command line arguments are processed.
2665
9d05ba64
GA
2666=item PERL_MM_USE_DEFAULT
2667
2668If set to a true value then MakeMaker's prompt function will
2669always return the default without waiting for user input.
2670
41e5fcb0
RGS
2671=item PERL_CORE
2672
2673Same as the PERL_CORE parameter. The parameter overrides this.
2674
6ce21ffa
GS
2675=back
2676
f1387719
PP
2677=head1 SEE ALSO
2678
562c8117
SP
2679L<Module::Build> is a pure-Perl alternative to MakeMaker which does
2680not rely on make or any other external utility. It is easier to
2681extend to suit your needs.
2682
2683L<Module::Install> is a wrapper around MakeMaker which adds features
2684not normally available.
2685
2686L<ExtUtils::ModuleMaker> and L<Module::Starter> are both modules to
2687help you setup your distribution.
005c1a0e 2688
e05e23b1 2689=head1 AUTHORS
fed7345c 2690
a7d1454b
RGS
2691Andy Dougherty C<doughera@lafayette.edu>, Andreas KE<ouml>nig
2692C<andreas.koenig@mind.de>, Tim Bunce C<timb@cpan.org>. VMS
2693support by Charles Bailey C<bailey@newman.upenn.edu>. OS/2 support
2694by Ilya Zakharevich C<ilya@math.ohio-state.edu>.
de90321e 2695
a7d1454b 2696Currently maintained by Michael G Schwern C<schwern@pobox.com>
f6d6199c 2697
a7d1454b 2698Send patches and ideas to C<makemaker@perl.org>.
e8012c20 2699
e0678a30
MS
2700Send bug reports via http://rt.cpan.org/. Please send your
2701generated Makefile along with your report.
2702
a7d1454b 2703For more up-to-date information, see L<http://www.makemaker.org>.
fed7345c 2704
479d2113
MS
2705=head1 LICENSE
2706
2707This program is free software; you can redistribute it and/or
2708modify it under the same terms as Perl itself.
2709
a7d1454b 2710See L<http://www.perl.com/perl/misc/Artistic.html>
479d2113
MS
2711
2712
005c1a0e 2713=cut