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