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