This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Doc patch.
[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#
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';
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
AK
984This will install the module's architecture-independent files into
985~/lib, the architecture-dependent files into ~/lib/$archname/auto.
986
987Another way to specify many INSTALL directories with a single
988parameter is PREFIX.
005c1a0e 989
8e07c86e 990 perl Makefile.PL PREFIX=~
005c1a0e 991
0d8023a2
PP
992This will replace the string specified by $Config{prefix} in all
993$Config{install*} values.
005c1a0e 994
bab2b58e 995Note, that in both cases the tilde expansion is done by MakeMaker, not
de592821 996by perl by default, nor by make. Conflicts between parameters LIB,
0b27bdda
RS
997PREFIX and the various INSTALL* arguments are resolved such that
998INSTALL* takes precedence.
005c1a0e 999
005c1a0e
AD
1000If the user has superuser privileges, and is not working on AFS
1001(Andrew File System) or relatives, then the defaults for
f1387719 1002INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSCRIPT, etc. will be appropriate,
005c1a0e
AD
1003and this incantation will be the best:
1004
1005 perl Makefile.PL; make; make test
1006 make install
1007
8e07c86e 1008make install per default writes some documentation of what has been
e05e23b1
PP
1009done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1010can be bypassed by calling make pure_install.
8e07c86e
AD
1011
1012=head2 AFS users
1013
1014will have to specify the installation directories as these most
1015probably have changed since perl itself has been installed. They will
1016have to do this by calling
1017
e05e23b1 1018 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
f1387719 1019 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
8e07c86e
AD
1020 make
1021
e05e23b1
PP
1022Be careful to repeat this procedure every time you recompile an
1023extension, unless you are sure the AFS installation directories are
1024still valid.
005c1a0e 1025
8e07c86e 1026=head2 Static Linking of a new Perl Binary
005c1a0e
AD
1027
1028An extension that is built with the above steps is ready to use on
1029systems supporting dynamic loading. On systems that do not support
1030dynamic loading, any newly created extension has to be linked together
1031with the available resources. MakeMaker supports the linking process
1032by creating appropriate targets in the Makefile whenever an extension
1033is built. You can invoke the corresponding section of the makefile with
1034
1035 make perl
1036
1037That produces a new perl binary in the current directory with all
e05e23b1
PP
1038extensions linked in that can be found in INST_ARCHLIB , SITELIBEXP,
1039and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1040UNIX, this is called Makefile.aperl (may be system dependent). If you
1041want to force the creation of a new perl, it is recommended, that you
1042delete this Makefile.aperl, so the directories are searched-through
1043for linkable libraries again.
005c1a0e
AD
1044
1045The binary can be installed into the directory where perl normally
1046resides on your machine with
1047
1048 make inst_perl
1049
1050To produce a perl binary with a different name than C<perl>, either say
1051
1052 perl Makefile.PL MAP_TARGET=myperl
1053 make myperl
1054 make inst_perl
1055
1056or say
1057
1058 perl Makefile.PL
1059 make myperl MAP_TARGET=myperl
1060 make inst_perl MAP_TARGET=myperl
1061
1062In any case you will be prompted with the correct invocation of the
1063C<inst_perl> target that installs the new binary into INSTALLBIN.
1064
8e07c86e
AD
1065make inst_perl per default writes some documentation of what has been
1066done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1067can be bypassed by calling make pure_inst_perl.
005c1a0e 1068
e05e23b1
PP
1069Warning: the inst_perl: target will most probably overwrite your
1070existing perl binary. Use with care!
005c1a0e 1071
8e07c86e
AD
1072Sometimes you might want to build a statically linked perl although
1073your system supports dynamic loading. In this case you may explicitly
1074set the linktype with the invocation of the Makefile.PL or make:
1075
1076 perl Makefile.PL LINKTYPE=static # recommended
1077
1078or
1079
1080 make LINKTYPE=static # works on most systems
1081
005c1a0e
AD
1082=head2 Determination of Perl Library and Installation Locations
1083
1084MakeMaker needs to know, or to guess, where certain things are
e05e23b1
PP
1085located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1086during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1087existing modules from), and PERL_INC (header files and C<libperl*.*>).
005c1a0e
AD
1088
1089Extensions may be built either using the contents of the perl source
e05e23b1
PP
1090directory tree or from the installed perl library. The recommended way
1091is to build extensions after you have run 'make install' on perl
1092itself. You can do that in any directory on your hard disk that is not
1093below the perl source tree. The support for extensions below the ext
1094directory of the perl distribution is only good for the standard
1095extensions that come with perl.
005c1a0e
AD
1096
1097If an extension is being built below the C<ext/> directory of the perl
e05e23b1
PP
1098source then MakeMaker will set PERL_SRC automatically (e.g.,
1099C<../..>). If PERL_SRC is defined and the extension is recognized as
1100a standard extension, then other variables default to the following:
005c1a0e
AD
1101
1102 PERL_INC = PERL_SRC
1103 PERL_LIB = PERL_SRC/lib
1104 PERL_ARCHLIB = PERL_SRC/lib
1105 INST_LIB = PERL_LIB
1106 INST_ARCHLIB = PERL_ARCHLIB
1107
1108If an extension is being built away from the perl source then MakeMaker
1109will leave PERL_SRC undefined and default to using the installed copy
1110of the perl library. The other variables default to the following:
1111
e05e23b1
PP
1112 PERL_INC = $archlibexp/CORE
1113 PERL_LIB = $privlibexp
1114 PERL_ARCHLIB = $archlibexp
1115 INST_LIB = ./blib/lib
1116 INST_ARCHLIB = ./blib/arch
005c1a0e
AD
1117
1118If perl has not yet been installed then PERL_SRC can be defined on the
1119command line as shown in the previous section.
1120
005c1a0e 1121
f1387719 1122=head2 Which architecture dependent directory?
005c1a0e 1123
f1387719
PP
1124If you don't want to keep the defaults for the INSTALL* macros,
1125MakeMaker helps you to minimize the typing needed: the usual
1126relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1127by Configure at perl compilation time. MakeMaker supports the user who
1128sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1129then MakeMaker defaults the latter to be the same subdirectory of
1130INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1131otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1132for INSTALLSITELIB and INSTALLSITEARCH.
005c1a0e 1133
f1387719
PP
1134MakeMaker gives you much more freedom than needed to configure
1135internal variables and get different results. It is worth to mention,
1136that make(1) also lets you configure most of the variables that are
1137used in the Makefile. But in the majority of situations this will not
a7665c5e 1138be necessary, and should only be done if the author of a package
f1387719 1139recommends it (or you know what you're doing).
005c1a0e 1140
e05e23b1 1141=head2 Using Attributes and Parameters
005c1a0e
AD
1142
1143The following attributes can be specified as arguments to WriteMakefile()
1144or as NAME=VALUE pairs on the command line:
1145
875fa795 1146=over 2
005c1a0e 1147
875fa795 1148=item AUTHOR
8e07c86e 1149
875fa795
JD
1150String containing name (and email address) of package author(s). Is used
1151in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1152
1153=item ABSTRACT
1154
1155One line description of the module. Will be included in PPD file.
1156
1157=item ABSTRACT_FROM
1158
1159Name of the file that contains the package description. MakeMaker looks
1160for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1161the first line in the "=head1 NAME" section. $2 becomes the abstract.
1162
1163=item BINARY_LOCATION
1164
1165Used when creating PPD files for binary packages. It can be set to a
1166full or relative path or URL to the binary archive for a particular
1167architecture. For example:
1168
1169 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1170
1171builds a PPD package that references a binary of the C<Agent> package,
20e08411 1172located in the C<x86> directory relative to the PPD itself.
8e07c86e 1173
864a5fa8 1174=item C
8e07c86e 1175
864a5fa8
AD
1176Ref to array of *.c file names. Initialised from a directory scan
1177and the values portion of the XS attribute hash. This is not
1178currently used by MakeMaker but may be handy in Makefile.PLs.
8e07c86e 1179
875fa795
JD
1180=item CAPI
1181
c5be433b
GS
1182[This attribute is obsolete in Perl 5.6. PERL_OBJECT builds are C-compatible
1183by default.]
1184
875fa795
JD
1185Switch to force usage of the Perl C API even when compiling for PERL_OBJECT.
1186
65d36135
GS
1187Note that this attribute is passed through to any recursive build,
1188but if and only if the submodule's Makefile.PL itself makes no mention
1189of the 'CAPI' attribute.
1190
84902520
TB
1191=item CCFLAGS
1192
1193String that will be included in the compiler call command line between
1194the arguments INC and OPTIMIZE.
1195
864a5fa8 1196=item CONFIG
8e07c86e 1197
864a5fa8
AD
1198Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1199config.sh. MakeMaker will add to CONFIG the following values anyway:
1200ar
1201cc
1202cccdlflags
1203ccdlflags
1204dlext
1205dlsrc
1206ld
1207lddlflags
1208ldflags
1209libc
1210lib_ext
1211obj_ext
1212ranlib
e05e23b1
PP
1213sitelibexp
1214sitearchexp
864a5fa8 1215so
8e07c86e
AD
1216
1217=item CONFIGURE
1218
e05e23b1 1219CODE reference. The subroutine should return a hash reference. The
1fef88e7 1220hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
8e07c86e
AD
1221be determined by some evaluation method.
1222
864a5fa8 1223=item DEFINE
8e07c86e 1224
864a5fa8 1225Something like C<"-DHAVE_UNISTD_H">
8e07c86e 1226
864a5fa8 1227=item DIR
8e07c86e 1228
864a5fa8
AD
1229Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1230] in ext/SDBM_File
8e07c86e 1231
864a5fa8 1232=item DISTNAME
8e07c86e 1233
e05e23b1 1234Your name for distributing the package (by tar file). This defaults to
864a5fa8 1235NAME above.
8e07c86e 1236
864a5fa8 1237=item DL_FUNCS
8e07c86e 1238
875fa795
JD
1239Hashref of symbol names for routines to be made available as universal
1240symbols. Each key/value pair consists of the package name and an
1241array of routine names in that package. Used only under AIX, OS/2,
1242VMS and Win32 at present. The routine names supplied will be expanded
1243in the same way as XSUB names are expanded by the XS() macro.
1244Defaults to
8e07c86e 1245
864a5fa8 1246 {"$(NAME)" => ["boot_$(NAME)" ] }
8e07c86e 1247
864a5fa8 1248e.g.
8e07c86e 1249
864a5fa8
AD
1250 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1251 "NetconfigPtr" => [ 'DESTROY'] }
8e07c86e 1252
875fa795
JD
1253Please see the L<ExtUtils::Mksymlists> documentation for more information
1254about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1255
864a5fa8 1256=item DL_VARS
8e07c86e 1257
875fa795
JD
1258Array of symbol names for variables to be made available as universal symbols.
1259Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1260(e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
8e07c86e 1261
f1387719
PP
1262=item EXCLUDE_EXT
1263
1264Array of extension names to exclude when doing a static build. This
1265is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1266details. (e.g. [ qw( Socket POSIX ) ] )
1267
1268This attribute may be most useful when specified as a string on the
de592821 1269command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
f1387719 1270
864a5fa8 1271=item EXE_FILES
8e07c86e 1272
864a5fa8 1273Ref to array of executable files. The files will be copied to the
f1387719 1274INST_SCRIPT directory. Make realclean will delete them from there
864a5fa8 1275again.
8e07c86e 1276
864a5fa8
AD
1277=item FIRST_MAKEFILE
1278
1279The name of the Makefile to be produced. Defaults to the contents of
1280MAKEFILE, but can be overridden. This is used for the second Makefile
1281that will be produced for the MAP_TARGET.
1282
1283=item FULLPERL
8e07c86e 1284
864a5fa8
AD
1285Perl binary able to run this extension.
1286
762efda7
JD
1287=item FUNCLIST
1288
1289This provides an alternate means to specify function names to be
1290exported from the extension. Its value is a reference to an
1291array of function names to be exported by the extension. These
1292names are passed through unaltered to the linker options file.
1293
864a5fa8
AD
1294=item H
1295
1296Ref to array of *.h file names. Similar to C.
1297
cae6c631
JD
1298=item HTMLLIBPODS
1299
1300Hashref of .pm and .pod files. MakeMaker will default this to all
1301 .pod and any .pm files that include POD directives. The files listed
1302here will be converted to HTML format and installed as was requested
1303at Configure time.
1304
1305=item HTMLSCRIPTPODS
1306
1307Hashref of pod-containing files. MakeMaker will default this to all
1308EXE_FILES files that include POD directives. The files listed
1309here will be converted to HTML format and installed as was requested
1310at Configure time.
1311
84902520
TB
1312=item IMPORTS
1313
875fa795
JD
1314This attribute is used to specify names to be imported into the
1315extension. It is only used on OS/2 and Win32.
84902520 1316
864a5fa8
AD
1317=item INC
1318
1319Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1320
f1387719
PP
1321=item INCLUDE_EXT
1322
1323Array of extension names to be included when doing a static build.
1324MakeMaker will normally build with all of the installed extensions when
1325doing a static build, and that is usually the desired behavior. If
1326INCLUDE_EXT is present then MakeMaker will build only with those extensions
1327which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
1328
1329It is not necessary to mention DynaLoader or the current extension when
1330filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
1331only DynaLoader and the current extension will be included in the build.
1332
1333This attribute may be most useful when specified as a string on the
de592821 1334command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
f1387719 1335
864a5fa8
AD
1336=item INSTALLARCHLIB
1337
e05e23b1
PP
1338Used by 'make install', which copies files from INST_ARCHLIB to this
1339directory if INSTALLDIRS is set to perl.
864a5fa8
AD
1340
1341=item INSTALLBIN
1342
f1387719 1343Directory to install binary files (e.g. tkperl) into.
e05e23b1
PP
1344
1345=item INSTALLDIRS
1346
1347Determines which of the two sets of installation directories to
1348choose: installprivlib and installarchlib versus installsitelib and
1349installsitearch. The first pair is chosen with INSTALLDIRS=perl, the
1350second with INSTALLDIRS=site. Default is site.
8e07c86e 1351
cae6c631
JD
1352=item INSTALLHTMLPRIVLIBDIR
1353
1354This directory gets the HTML pages at 'make install' time. Defaults to
1355$Config{installhtmlprivlibdir}.
1356
1357=item INSTALLHTMLSCRIPTDIR
1358
1359This directory gets the HTML pages at 'make install' time. Defaults to
1360$Config{installhtmlscriptdir}.
1361
1362=item INSTALLHTMLSITELIBDIR
1363
1364This directory gets the HTML pages at 'make install' time. Defaults to
1365$Config{installhtmlsitelibdir}.
1366
1367
8e07c86e
AD
1368=item INSTALLMAN1DIR
1369
864a5fa8
AD
1370This directory gets the man pages at 'make install' time. Defaults to
1371$Config{installman1dir}.
1372
8e07c86e
AD
1373=item INSTALLMAN3DIR
1374
864a5fa8
AD
1375This directory gets the man pages at 'make install' time. Defaults to
1376$Config{installman3dir}.
8e07c86e 1377
864a5fa8 1378=item INSTALLPRIVLIB
8e07c86e 1379
e05e23b1
PP
1380Used by 'make install', which copies files from INST_LIB to this
1381directory if INSTALLDIRS is set to perl.
1382
f1387719
PP
1383=item INSTALLSCRIPT
1384
1385Used by 'make install' which copies files from INST_SCRIPT to this
1386directory.
1387
875fa795 1388=item INSTALLSITEARCH
e05e23b1 1389
875fa795 1390Used by 'make install', which copies files from INST_ARCHLIB to this
e05e23b1
PP
1391directory if INSTALLDIRS is set to site (default).
1392
875fa795 1393=item INSTALLSITELIB
e05e23b1 1394
875fa795 1395Used by 'make install', which copies files from INST_LIB to this
e05e23b1 1396directory if INSTALLDIRS is set to site (default).
8e07c86e 1397
864a5fa8 1398=item INST_ARCHLIB
8e07c86e 1399
864a5fa8 1400Same as INST_LIB for architecture dependent files.
8e07c86e 1401
f1387719
PP
1402=item INST_BIN
1403
1404Directory to put real binary files during 'make'. These will be copied
1405to INSTALLBIN during 'make install'
1406
864a5fa8 1407=item INST_EXE
8e07c86e 1408
f1387719
PP
1409Old name for INST_SCRIPT. Deprecated. Please use INST_SCRIPT if you
1410need to use it.
8e07c86e 1411
864a5fa8 1412=item INST_LIB
8e07c86e 1413
864a5fa8
AD
1414Directory where we put library files of this extension while building
1415it.
8e07c86e 1416
cae6c631
JD
1417=item INST_HTMLLIBDIR
1418
1419Directory to hold the man pages in HTML format at 'make' time
1420
1421=item INST_HTMLSCRIPTDIR
1422
1423Directory to hold the man pages in HTML format at 'make' time
1424
864a5fa8 1425=item INST_MAN1DIR
8e07c86e 1426
864a5fa8 1427Directory to hold the man pages at 'make' time
8e07c86e 1428
864a5fa8 1429=item INST_MAN3DIR
8e07c86e 1430
864a5fa8 1431Directory to hold the man pages at 'make' time
8e07c86e 1432
f1387719
PP
1433=item INST_SCRIPT
1434
1435Directory, where executable files should be installed during
c3fed81c 1436'make'. Defaults to "./blib/script", just to have a dummy location during
f1387719
PP
1437testing. make install will copy the files in INST_SCRIPT to
1438INSTALLSCRIPT.
1439
ee13e175
JH
1440=item PERL_MALLOC_OK
1441
1442defaults to 0. Should be set to TRUE if the extension can work with
1443the memory allocation routines substituted by the Perl malloc() subsystem.
1444This should be applicable to most extensions with exceptions of those
1445
1446=over
1447
1448=item *
1449
1450with bugs in memory allocations which are caught by Perl's malloc();
1451
1452=item *
1453
1454which interact with the memory allocator in other ways than via
1455malloc(), realloc(), free(), calloc(), sbrk() and brk();
1456
1457=item *
1458
1459which rely on special alignment which is not provided by Perl's malloc().
1460
1461=back
1462
1463B<NOTE.> Negligence to set this flag in I<any one> of loaded extension
1464nullifies many advantages of Perl's malloc(), such as better usage of
1465system resources, error detection, memory usage reporting, catchable failure
1466of memory allocations, etc.
1467
864a5fa8 1468=item LDFROM
8e07c86e 1469
864a5fa8
AD
1470defaults to "$(OBJECT)" and is used in the ld command to specify
1471what files to link/load from (also see dynamic_lib below for how to
1472specify ld flags)
8e07c86e 1473
bab2b58e
AK
1474=item LIB
1475
1476LIB can only be set at C<perl Makefile.PL> time. It has the effect of
1477setting both INSTALLPRIVLIB and INSTALLSITELIB to that value regardless any
1478
762efda7
JD
1479=item LIBPERL_A
1480
1481The filename of the perllibrary that will be used together with this
1482extension. Defaults to libperl.a.
1483
8e07c86e
AD
1484=item LIBS
1485
1486An anonymous array of alternative library
1487specifications to be searched for (in order) until
864a5fa8 1488at least one library is found. E.g.
8e07c86e
AD
1489
1490 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1491
1492Mind, that any element of the array
1493contains a complete set of arguments for the ld
1494command. So do not specify
1495
1496 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1497
1498See ODBM_File/Makefile.PL for an example, where an array is needed. If
1499you specify a scalar as in
1500
1501 'LIBS' => "-ltcl -ltk -lX11"
1502
1503MakeMaker will turn it into an array with one element.
1504
864a5fa8 1505=item LINKTYPE
8e07c86e 1506
e05e23b1
PP
1507'static' or 'dynamic' (default unless usedl=undef in
1508config.sh). Should only be used to force static linking (also see
864a5fa8 1509linkext below).
8e07c86e 1510
864a5fa8 1511=item MAKEAPERL
8e07c86e 1512
864a5fa8
AD
1513Boolean which tells MakeMaker, that it should include the rules to
1514make a perl. This is handled automatically as a switch by
1515MakeMaker. The user normally does not need it.
8e07c86e 1516
864a5fa8 1517=item MAKEFILE
8e07c86e 1518
864a5fa8 1519The name of the Makefile to be produced.
8e07c86e 1520
864a5fa8 1521=item MAN1PODS
8e07c86e 1522
864a5fa8
AD
1523Hashref of pod-containing files. MakeMaker will default this to all
1524EXE_FILES files that include POD directives. The files listed
1525here will be converted to man pages and installed as was requested
1526at Configure time.
8e07c86e 1527
864a5fa8 1528=item MAN3PODS
8e07c86e 1529
864a5fa8
AD
1530Hashref of .pm and .pod files. MakeMaker will default this to all
1531 .pod and any .pm files that include POD directives. The files listed
1532here will be converted to man pages and installed as was requested
1533at Configure time.
8e07c86e 1534
864a5fa8 1535=item MAP_TARGET
8e07c86e 1536
864a5fa8
AD
1537If it is intended, that a new perl binary be produced, this variable
1538may hold a name for that binary. Defaults to perl
8e07c86e 1539
864a5fa8 1540=item MYEXTLIB
4633a7c4 1541
864a5fa8
AD
1542If the extension links to a library that it builds set this to the
1543name of the library (see SDBM_File)
4633a7c4 1544
864a5fa8 1545=item NAME
8e07c86e 1546
864a5fa8
AD
1547Perl module name for this extension (DBD::Oracle). This will default
1548to the directory name but should be explicitly defined in the
1549Makefile.PL.
8e07c86e 1550
864a5fa8 1551=item NEEDS_LINKING
8e07c86e 1552
a7665c5e 1553MakeMaker will figure out if an extension contains linkable code
864a5fa8 1554anywhere down the directory tree, and will set this variable
a7665c5e 1555accordingly, but you can speed it up a very little bit if you define
864a5fa8 1556this boolean variable yourself.
8e07c86e 1557
e05e23b1
PP
1558=item NOECHO
1559
f1387719 1560Defaults to C<@>. By setting it to an empty string you can generate a
e05e23b1
PP
1561Makefile that echos all commands. Mainly used in debugging MakeMaker
1562itself.
1563
864a5fa8 1564=item NORECURS
8e07c86e 1565
e05e23b1 1566Boolean. Attribute to inhibit descending into subdirectories.
8e07c86e 1567
762efda7
JD
1568=item NO_VC
1569
a7665c5e 1570In general, any generated Makefile checks for the current version of
762efda7
JD
1571MakeMaker and the version the Makefile was built under. If NO_VC is
1572set, the version check is neglected. Do not write this into your
1573Makefile.PL, use it interactively instead.
1574
864a5fa8 1575=item OBJECT
8e07c86e 1576
864a5fa8
AD
1577List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1578string containing all object files, e.g. "tkpBind.o
1579tkpButton.o tkpCanvas.o"
8e07c86e 1580
3b03c0f3
PP
1581=item OPTIMIZE
1582
1583Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1584passed to subdirectory makes.
1585
864a5fa8 1586=item PERL
8e07c86e 1587
864a5fa8 1588Perl binary for tasks that can be done by miniperl
8e07c86e 1589
864a5fa8 1590=item PERLMAINCC
005c1a0e 1591
864a5fa8
AD
1592The call to the program that is able to compile perlmain.c. Defaults
1593to $(CC).
005c1a0e 1594
864a5fa8 1595=item PERL_ARCHLIB
005c1a0e 1596
a7665c5e 1597Same as above for architecture dependent files.
8e07c86e 1598
864a5fa8 1599=item PERL_LIB
8e07c86e 1600
864a5fa8 1601Directory containing the Perl library to use.
8e07c86e 1602
864a5fa8 1603=item PERL_SRC
8e07c86e 1604
864a5fa8
AD
1605Directory containing the Perl source code (use of this should be
1606avoided, it may be undefined)
8e07c86e 1607
2366100d
A
1608=item PERM_RW
1609
de592821 1610Desired permission for read/writable files. Defaults to C<644>.
2366100d
A
1611See also L<MM_Unix/perm_rw>.
1612
1613=item PERM_RWX
1614
1615Desired permission for executable files. Defaults to C<755>.
1616See also L<MM_Unix/perm_rwx>.
1617
864a5fa8 1618=item PL_FILES
8e07c86e 1619
864a5fa8
AD
1620Ref to hash of files to be processed as perl programs. MakeMaker
1621will default to any found *.PL file (except Makefile.PL) being keys
1622and the basename of the file being the value. E.g.
8e07c86e 1623
864a5fa8 1624 {'foobar.PL' => 'foobar'}
8e07c86e 1625
864a5fa8 1626The *.PL files are expected to produce output to the target files
3aa35033
GS
1627themselves. If multiple files can be generated from the same *.PL
1628file then the value in the hash can be a reference to an array of
1629target file names. E.g.
1630
1631 {'foobar.PL' => ['foobar1','foobar2']}
8e07c86e 1632
864a5fa8 1633=item PM
8e07c86e 1634
864a5fa8 1635Hashref of .pm files and *.pl files to be installed. e.g.
8e07c86e 1636
864a5fa8 1637 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
8e07c86e 1638
a3cb178b
GS
1639By default this will include *.pm and *.pl and the files found in
1640the PMLIBDIRS directories. Defining PM in the
864a5fa8 1641Makefile.PL will override PMLIBDIRS.
8e07c86e 1642
864a5fa8 1643=item PMLIBDIRS
8e07c86e 1644
864a5fa8 1645Ref to array of subdirectories containing library files. Defaults to
a3cb178b 1646[ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
864a5fa8
AD
1647they contain will be installed in the corresponding location in the
1648library. A libscan() method can be used to alter the behaviour.
1649Defining PM in the Makefile.PL will override PMLIBDIRS.
8e07c86e 1650
2aea4d40
JD
1651=item POLLUTE
1652
1653Release 5.005 grandfathered old global symbol names by providing preprocessor
a7665c5e 1654macros for extension source compatibility. As of release 5.6, these
2aea4d40
JD
1655preprocessor definitions are not available by default. The POLLUTE flag
1656specifies that the old names should still be defined:
1657
1658 perl Makefile.PL POLLUTE=1
1659
1660Please inform the module author if this is necessary to successfully install
a7665c5e 1661a module under 5.6 or later.
2aea4d40 1662
875fa795
JD
1663=item PPM_INSTALL_EXEC
1664
20e08411 1665Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
875fa795
JD
1666
1667=item PPM_INSTALL_SCRIPT
1668
1669Name of the script that gets executed by the Perl Package Manager after
1670the installation of a package.
1671
864a5fa8 1672=item PREFIX
8e07c86e 1673
864a5fa8 1674Can be used to set the three INSTALL* attributes in one go (except for
e05e23b1
PP
1675probably INSTALLMAN1DIR, if it is not below PREFIX according to
1676%Config). They will have PREFIX as a common directory node and will
1677branch from that node into lib/, lib/ARCHNAME or whatever Configure
1678decided at the build time of your perl (unless you override one of
1679them, of course).
8e07c86e 1680
f1387719 1681=item PREREQ_PM
8e07c86e 1682
f1387719
PP
1683Hashref: Names of modules that need to be available to run this
1684extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
1685desired version is the value. If the required version number is 0, we
1686only check if any version is installed already.
8e07c86e 1687
864a5fa8 1688=item SKIP
8e07c86e 1689
864a5fa8 1690Arryref. E.g. [qw(name1 name2)] skip (do not write) sections of the
a7665c5e
GS
1691Makefile. Caution! Do not use the SKIP attribute for the negligible
1692speedup. It may seriously damage the resulting Makefile. Only use it
f1387719 1693if you really need it.
8e07c86e 1694
864a5fa8 1695=item TYPEMAPS
8e07c86e 1696
864a5fa8
AD
1697Ref to array of typemap file names. Use this when the typemaps are
1698in some directory other than the current directory or when they are
1699not named B<typemap>. The last typemap in the list takes
1700precedence. A typemap in the current directory has highest
1701precedence, even if it isn't listed in TYPEMAPS. The default system
1702typemap has lowest precedence.
8e07c86e 1703
864a5fa8 1704=item VERSION
8e07c86e 1705
864a5fa8
AD
1706Your version number for distributing the package. This defaults to
17070.1.
8e07c86e 1708
0d8023a2
PP
1709=item VERSION_FROM
1710
1711Instead of specifying the VERSION in the Makefile.PL you can let
1712MakeMaker parse a file to determine the version number. The parsing
1713routine requires that the file named by VERSION_FROM contains one
1714single line to compute the version number. The first line in the file
1715that contains the regular expression
1716
84902520 1717 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
0d8023a2
PP
1718
1719will be evaluated with eval() and the value of the named variable
1720B<after> the eval() will be assigned to the VERSION attribute of the
1721MakeMaker object. The following lines will be parsed o.k.:
1722
1723 $VERSION = '1.00';
84902520 1724 *VERSION = \'1.01';
2366100d 1725 ( $VERSION ) = '$Revision: 1.222 $ ' =~ /\$Revision:\s+([^\s]+)/;
0d8023a2 1726 $FOO::VERSION = '1.10';
84902520 1727 *FOO::VERSION = \'1.11';
0d8023a2
PP
1728
1729but these will fail:
1730
1731 my $VERSION = '1.01';
1732 local $VERSION = '1.02';
1733 local $FOO::VERSION = '1.30';
1734
84902520
TB
1735The file named in VERSION_FROM is not added as a dependency to
1736Makefile. This is not really correct, but it would be a major pain
1737during development to have to rewrite the Makefile for any smallish
1738change in that file. If you want to make sure that the Makefile
1739contains the correct VERSION macro after any change of the file, you
1740would have to do something like
1741
1742 depend => { Makefile => '$(VERSION_FROM)' }
1743
1744See attribute C<depend> below.
0d8023a2 1745
864a5fa8 1746=item XS
8e07c86e 1747
864a5fa8 1748Hashref of .xs files. MakeMaker will default this. e.g.
8e07c86e 1749
864a5fa8 1750 {'name_of_file.xs' => 'name_of_file.c'}
8e07c86e 1751
864a5fa8
AD
1752The .c files will automatically be included in the list of files
1753deleted by a make clean.
4633a7c4 1754
864a5fa8 1755=item XSOPT
8e07c86e 1756
864a5fa8
AD
1757String of options to pass to xsubpp. This might include C<-C++> or
1758C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
1759that purpose.
8e07c86e 1760
864a5fa8 1761=item XSPROTOARG
4633a7c4 1762
4e68a208 1763May be set to an empty string, which is identical to C<-prototypes>, or
864a5fa8 1764C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
4e68a208
AD
1765defaults to the empty string.
1766
0d8023a2
PP
1767=item XS_VERSION
1768
1769Your version number for the .xs file of this package. This defaults
1770to the value of the VERSION attribute.
1771
8e07c86e
AD
1772=back
1773
1774=head2 Additional lowercase attributes
1775
1776can be used to pass parameters to the methods which implement that
f1387719 1777part of the Makefile.
8e07c86e
AD
1778
1779=over 2
1780
864a5fa8 1781=item clean
8e07c86e 1782
864a5fa8
AD
1783 {FILES => "*.xyz foo"}
1784
c07a80fd
PP
1785=item depend
1786
1787 {ANY_TARGET => ANY_DEPENDECY, ...}
1788
864a5fa8
AD
1789=item dist
1790
5f8e730b 1791 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
3b03c0f3 1792 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
f1387719 1793 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
864a5fa8
AD
1794
1795If you specify COMPRESS, then SUFFIX should also be altered, as it is
1796needed to tell make the target file of the compression. Setting
1797DIST_CP to ln can be useful, if you need to preserve the timestamps on
1798your files. DIST_CP can take the values 'cp', which copies the file,
1799'ln', which links the file, and 'best' which copies symbolic links and
1800links the rest. Default is 'best'.
1801
1802=item dynamic_lib
1803
0d8023a2 1804 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
8e07c86e 1805
8e07c86e
AD
1806=item linkext
1807
1808 {LINKTYPE => 'static', 'dynamic' or ''}
1809
864a5fa8 1810NB: Extensions that have nothing but *.pm files had to say
8e07c86e
AD
1811
1812 {LINKTYPE => ''}
1813
864a5fa8 1814with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
a7665c5e 1815can be deleted safely. MakeMaker recognizes when there's nothing to
864a5fa8 1816be linked.
8e07c86e 1817
864a5fa8 1818=item macro
8e07c86e 1819
864a5fa8 1820 {ANY_MACRO => ANY_VALUE, ...}
8e07c86e
AD
1821
1822=item realclean
1823
1824 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1825
f2f614a6
GS
1826=item test
1827
1828 {TESTS => 't/*.t'}
1829
8e07c86e
AD
1830=item tool_autosplit
1831
f2f614a6 1832 {MAXLEN => 8}
005c1a0e
AD
1833
1834=back
1835
1836=head2 Overriding MakeMaker Methods
1837
1838If you cannot achieve the desired Makefile behaviour by specifying
1839attributes you may define private subroutines in the Makefile.PL.
1840Each subroutines returns the text it wishes to have written to
1841the Makefile. To override a section of the Makefile you can
1842either say:
1843
1844 sub MY::c_o { "new literal text" }
1845
1846or you can edit the default by saying something like:
1847
8e07c86e 1848 sub MY::c_o {
14870ecd
CS
1849 package MY; # so that "SUPER" works right
1850 my $inherited = shift->SUPER::c_o(@_);
f1387719
PP
1851 $inherited =~ s/old text/new text/;
1852 $inherited;
8e07c86e
AD
1853 }
1854
bdda3fbd
PJ
1855If you are running experiments with embedding perl as a library into
1856other applications, you might find MakeMaker is not sufficient. You'd
1857better have a look at ExtUtils::Embed which is a collection of utilities
1858for embedding.
005c1a0e
AD
1859
1860If you still need a different solution, try to develop another
bdda3fbd
PJ
1861subroutine that fits your needs and submit the diffs to
1862F<perl5-porters@perl.org> or F<comp.lang.perl.moderated> as appropriate.
005c1a0e 1863
3b03c0f3
PP
1864For a complete description of all MakeMaker methods see L<ExtUtils::MM_Unix>.
1865
1866Here is a simple example of how to add a new target to the generated
1867Makefile:
1868
1869 sub MY::postamble {
1870 '
1871 $(MYEXTLIB): sdbm/Makefile
1872 cd sdbm && $(MAKE) all
1873 ';
1874 }
1875
1876
f1387719
PP
1877=head2 Hintsfile support
1878
1879MakeMaker.pm uses the architecture specific information from
1880Config.pm. In addition it evaluates architecture specific hints files
1881in a C<hints/> directory. The hints files are expected to be named
1882like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
1883name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
1884MakeMaker within the WriteMakefile() subroutine, and can be used to
1885execute commands as well as to include special variables. The rules
1886which hintsfile is chosen are the same as in Configure.
1887
1888The hintsfile is eval()ed immediately after the arguments given to
1889WriteMakefile are stuffed into a hash reference $self but before this
1890reference becomes blessed. So if you want to do the equivalent to
1891override or create an attribute you would say something like
1892
1893 $self->{LIBS} = ['-ldbm -lucb -lc'];
1894
005c1a0e
AD
1895=head2 Distribution Support
1896
1897For authors of extensions MakeMaker provides several Makefile
1898targets. Most of the support comes from the ExtUtils::Manifest module,
1899where additional documentation can be found.
1900
1901=over 4
1902
1903=item make distcheck
8e07c86e 1904
005c1a0e
AD
1905reports which files are below the build directory but not in the
1906MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
1907details)
1908
4633a7c4
LW
1909=item make skipcheck
1910
1911reports which files are skipped due to the entries in the
1912C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
1913details)
1914
005c1a0e 1915=item make distclean
8e07c86e 1916
005c1a0e 1917does a realclean first and then the distcheck. Note that this is not
a7665c5e 1918needed to build a new distribution as long as you are sure that the
005c1a0e
AD
1919MANIFEST file is ok.
1920
1921=item make manifest
8e07c86e 1922
005c1a0e
AD
1923rewrites the MANIFEST file, adding all remaining files found (See
1924ExtUtils::Manifest::mkmanifest() for details)
1925
1926=item make distdir
8e07c86e 1927
005c1a0e
AD
1928Copies all the files that are in the MANIFEST file to a newly created
1929directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
1930exists, it will be removed first.
1931
8e07c86e
AD
1932=item make disttest
1933
1934Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
4633a7c4 1935a make test in that directory.
8e07c86e 1936
005c1a0e 1937=item make tardist
8e07c86e 1938
3b03c0f3 1939First does a distdir. Then a command $(PREOP) which defaults to a null
f1387719
PP
1940command, followed by $(TOUNIX), which defaults to a null command under
1941UNIX, and will convert files in distribution directory to UNIX format
1942otherwise. Next it runs C<tar> on that directory into a tarfile and
3b03c0f3
PP
1943deletes the directory. Finishes with a command $(POSTOP) which
1944defaults to a null command.
005c1a0e
AD
1945
1946=item make dist
8e07c86e 1947
005c1a0e
AD
1948Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1949
1950=item make uutardist
8e07c86e 1951
005c1a0e
AD
1952Runs a tardist first and uuencodes the tarfile.
1953
1954=item make shdist
8e07c86e 1955
3b03c0f3
PP
1956First does a distdir. Then a command $(PREOP) which defaults to a null
1957command. Next it runs C<shar> on that directory into a sharfile and
1958deletes the intermediate directory again. Finishes with a command
1959$(POSTOP) which defaults to a null command. Note: For shdist to work
1960properly a C<shar> program that can handle directories is mandatory.
1961
1962=item make zipdist
1963
1964First does a distdir. Then a command $(PREOP) which defaults to a null
1965command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
1966zipfile. Then deletes that directory. Finishes with a command
1967$(POSTOP) which defaults to a null command.
005c1a0e
AD
1968
1969=item make ci
8e07c86e
AD
1970
1971Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1972
1973=back
005c1a0e
AD
1974
1975Customization of the dist targets can be done by specifying a hash
1976reference to the dist attribute of the WriteMakefile call. The
1977following parameters are recognized:
1978
8e07c86e 1979 CI ('ci -u')
5f8e730b 1980 COMPRESS ('gzip --best')
005c1a0e 1981 POSTOP ('@ :')
8e07c86e 1982 PREOP ('@ :')
f1387719 1983 TO_UNIX (depends on the system)
8e07c86e
AD
1984 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1985 SHAR ('shar')
5f8e730b 1986 SUFFIX ('.gz')
8e07c86e
AD
1987 TAR ('tar')
1988 TARFLAGS ('cvf')
3b03c0f3
PP
1989 ZIP ('zip')
1990 ZIPFLAGS ('-r')
005c1a0e
AD
1991
1992An example:
1993
5f8e730b 1994 WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
005c1a0e 1995
1b171b8d
NIS
1996=head2 Disabling an extension
1997
1998If some events detected in F<Makefile.PL> imply that there is no way
1999to create the Module, but this is a normal state of things, then you
2000can create a F<Makefile> which does nothing, but succeeds on all the
2001"usual" build targets. To do so, use
2002
2003 ExtUtils::MakeMaker::WriteEmptyMakefile();
2004
2005instead of WriteMakefile().
2006
2007This may be useful if other modules expect this module to be I<built>
2008OK, as opposed to I<work> OK (say, this system-dependent module builds
2009in a subdirectory of some other distribution, or is listed as a
2010dependency in a CPAN::Bundle, but the functionality is supported by
2011different means on the current architecture).
2012
6ce21ffa
GS
2013=head1 ENVIRONMENT
2014
2015=over 8
2016
2443aee5 2017=item PERL_MM_OPT
6ce21ffa
GS
2018
2019Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2020C<WriteMakefile()>. The string is split on whitespace, and the result
2021is processed before any actual command line arguments are processed.
2022
2023=back
2024
f1387719
PP
2025=head1 SEE ALSO
2026
2027ExtUtils::MM_Unix, ExtUtils::Manifest, ExtUtils::testlib,
bdda3fbd 2028ExtUtils::Install, ExtUtils::Embed
005c1a0e 2029
e05e23b1 2030=head1 AUTHORS
fed7345c 2031
352854fa
CS
2032Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, Andreas KE<ouml>nig
2033<F<A.Koenig@franz.ww.TU-Berlin.DE>>, Tim Bunce <F<Tim.Bunce@ig.co.uk>>.
bd3fa61c 2034VMS support by Charles Bailey <F<bailey@newman.upenn.edu>>. OS/2
352854fa 2035support by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>. Contact the
e05e23b1
PP
2036makemaker mailing list C<mailto:makemaker@franz.ww.tu-berlin.de>, if
2037you have any questions.
fed7345c 2038
005c1a0e 2039=cut