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