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