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