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