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