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