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