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