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