This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [PATCH 5.8.2 @21574] OS/2 build
[perl5.git] / lib / ExtUtils / MakeMaker.pm
CommitLineData
e05e23b1
PP
1package ExtUtils::MakeMaker;
2
57b1a898
MS
3BEGIN {require 5.005_03;}
4
30361541
JH
5$VERSION = '6.17';
6($Revision) = q$Revision: 1.133 $ =~ /Revision:\s+(\S+)/;
005c1a0e 7
8e07c86e 8require Exporter;
3b03c0f3
PP
9use Config;
10use Carp ();
dedf98bc 11use File::Path;
e05e23b1
PP
12
13use vars qw(
f6d6199c 14 @ISA @EXPORT @EXPORT_OK
dedf98bc
MS
15 $Revision $VERSION $Verbose %Config
16 @Prepend_parent @Parent
5e9e174b 17 %Recognized_Att_Keys @Get_from_Config @MM_Sections @Overridable
dedf98bc 18 $Filename
f6d6199c 19 );
5e9e174b 20use strict;
005c1a0e 21
e05e23b1
PP
22@ISA = qw(Exporter);
23@EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
f6d6199c 24@EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists);
42793c05 25
f6d6199c
MS
26# These will go away once the last of the Win32 & VMS specific code is
27# purged.
5e9e174b 28my $Is_VMS = $^O eq 'VMS';
5e9e174b 29my $Is_Win32 = $^O eq 'MSWin32';
3b03c0f3 30
dedf98bc
MS
31# Our filename for diagnostic and debugging purposes. More reliable
32# than %INC (think caseless filesystems)
33$Filename = __FILE__;
34
9ab29e2b 35full_setup();
864a5fa8 36
f6d6199c
MS
37require ExtUtils::MM; # Things like CPAN assume loading ExtUtils::MakeMaker
38 # will give them MM.
e05e23b1 39
45bc4d3a
JH
40require ExtUtils::MY; # XXX pre-5.8 versions of ExtUtils::Embed expect
41 # loading ExtUtils::MakeMaker will give them MY.
42 # This will go when Embed is it's own CPAN module.
43
f1387719 44
3b03c0f3
PP
45sub WriteMakefile {
46 Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
f1387719 47
f6d6199c 48 require ExtUtils::MY;
3b03c0f3 49 my %att = @_;
69ff8adf
JH
50
51 _verify_att(\%att);
52
e0678a30
MS
53 my $mm = MM->new(\%att);
54 $mm->flush;
55
56 return $mm;
3b03c0f3
PP
57}
58
69ff8adf 59
d5d4ec93
MS
60# Basic signatures of the attributes WriteMakefile takes. Each is the
61# reference type. Empty value indicate it takes a non-reference
62# scalar.
479d2113
MS
63my %Att_Sigs;
64my %Special_Sigs = (
d5d4ec93 65 C => 'array',
d5d4ec93
MS
66 CONFIG => 'array',
67 CONFIGURE => 'code',
d5d4ec93 68 DIR => 'array',
d5d4ec93
MS
69 DL_FUNCS => 'hash',
70 DL_VARS => 'array',
71 EXCLUDE_EXT => 'array',
72 EXE_FILES => 'array',
d5d4ec93
MS
73 FUNCLIST => 'array',
74 H => 'array',
75 IMPORTS => 'hash',
d5d4ec93 76 INCLUDE_EXT => 'array',
d5d4ec93 77 LIBS => ['array',''],
d5d4ec93
MS
78 MAN1PODS => 'hash',
79 MAN3PODS => 'hash',
d5d4ec93
MS
80 PL_FILES => 'hash',
81 PM => 'hash',
82 PMLIBDIRS => 'array',
d5d4ec93 83 PREREQ_PM => 'hash',
d5d4ec93
MS
84 SKIP => 'array',
85 TYPEMAPS => 'array',
d5d4ec93 86 XS => 'hash',
479d2113 87 _KEEP_AFTER_FLUSH => '',
69ff8adf
JH
88
89 clean => 'hash',
90 depend => 'hash',
91 dist => 'hash',
92 dynamic_lib=> 'hash',
93 linkext => 'hash',
94 macro => 'hash',
531e2ba1 95 postamble => 'hash',
69ff8adf
JH
96 realclean => 'hash',
97 test => 'hash',
98 tool_autosplit => 'hash',
99);
100
479d2113
MS
101@Att_Sigs{keys %Recognized_Att_Keys} = ('') x keys %Recognized_Att_Keys;
102@Att_Sigs{keys %Special_Sigs} = values %Special_Sigs;
103
69ff8adf
JH
104
105sub _verify_att {
106 my($att) = @_;
107
108 while( my($key, $val) = each %$att ) {
109 my $sig = $Att_Sigs{$key};
d5d4ec93
MS
110 unless( defined $sig ) {
111 warn "WARNING: $key is not a known parameter.\n";
112 next;
113 }
114
115 my @sigs = ref $sig ? @$sig : $sig;
116 my $given = lc ref $val;
69ff8adf 117 unless( grep $given eq $_, @sigs ) {
d5d4ec93
MS
118 my $takes = join " or ", map { $_ ne '' ? "$_ reference"
119 : "string/number"
69ff8adf 120 } @sigs;
d5d4ec93
MS
121 my $has = $given ne '' ? "$given reference"
122 : "string/number";
69ff8adf
JH
123 warn "WARNING: $key takes a $takes not a $has.\n".
124 " Please inform the author.\n";
69ff8adf
JH
125 }
126 }
127}
128
f1387719 129sub prompt ($;$) {
479d2113 130 my($mess, $def) = @_;
e0678a30
MS
131 Carp::confess("prompt function called without an argument")
132 unless defined $mess;
479d2113
MS
133
134 my $isa_tty = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;
135
f1387719
PP
136 my $dispdef = defined $def ? "[$def] " : " ";
137 $def = defined $def ? $def : "";
479d2113 138
13bc20ff 139 local $|=1;
f6d6199c 140 local $\;
13bc20ff 141 print "$mess $dispdef";
479d2113
MS
142
143 my $ans;
144 if ($ENV{PERL_MM_USE_DEFAULT} || (!$isa_tty && eof STDIN)) {
145 print "$def\n";
146 }
147 else {
f6d6199c
MS
148 $ans = <STDIN>;
149 if( defined $ans ) {
150 chomp $ans;
151 }
152 else { # user hit ctrl-D
153 print "\n";
154 }
155 }
479d2113 156
f6d6199c 157 return (!defined $ans || $ans eq '') ? $def : $ans;
3b03c0f3
PP
158}
159
e05e23b1
PP
160sub eval_in_subdirs {
161 my($self) = @_;
a8112c7f 162 use Cwd qw(cwd abs_path);
f582e489
MS
163 my $pwd = cwd() || die "Can't figure out your cwd!";
164
3593a55e 165 local @INC = map eval {abs_path($_) if -e} || $_, @INC;
f6d6199c 166 push @INC, '.'; # '.' has to always be at the end of @INC
e05e23b1 167
5e9e174b 168 foreach my $dir (@{$self->{DIR}}){
f6d6199c
MS
169 my($abs) = $self->catdir($pwd,$dir);
170 $self->eval_in_x($abs);
e05e23b1 171 }
e05e23b1 172 chdir $pwd;
864a5fa8 173}
42793c05 174
e05e23b1
PP
175sub eval_in_x {
176 my($self,$dir) = @_;
6626a13a 177 chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
5e9e174b 178
f6d6199c
MS
179 {
180 package main;
181 do './Makefile.PL';
182 };
f1387719 183 if ($@) {
f6d6199c
MS
184# if ($@ =~ /prerequisites/) {
185# die "MakeMaker WARNING: $@";
186# } else {
187# warn "WARNING from evaluation of $dir/Makefile.PL: $@";
188# }
45bc4d3a 189 die "ERROR from evaluation of $dir/Makefile.PL: $@";
f1387719 190 }
e05e23b1
PP
191}
192
479d2113
MS
193
194# package name for the classes into which the first object will be blessed
195my $PACKNAME = 'PACK000';
196
e05e23b1
PP
197sub full_setup {
198 $Verbose ||= 0;
3b03c0f3 199
5e9e174b 200 my @attrib_help = qw/
3b03c0f3 201
762efda7
JD
202 AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
203 C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
479d2113 204 EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE
75e2e551
MS
205 FULLPERL FULLPERLRUN FULLPERLRUNINST
206 FUNCLIST H IMPORTS
431b0fc4 207
45bc4d3a 208 INST_ARCHLIB INST_SCRIPT INST_BIN INST_LIB INST_MAN1DIR INST_MAN3DIR
5c161494 209 INSTALLDIRS
479d2113
MS
210 DESTDIR PREFIX
211 PERLPREFIX SITEPREFIX VENDORPREFIX
5c161494
MS
212 INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
213 INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
45bc4d3a
JH
214 INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
215 INSTALLMAN1DIR INSTALLMAN3DIR
216 INSTALLSITEMAN1DIR INSTALLSITEMAN3DIR
217 INSTALLVENDORMAN1DIR INSTALLVENDORMAN3DIR
218 INSTALLSCRIPT
5c161494
MS
219 PERL_LIB PERL_ARCHLIB
220 SITELIBEXP SITEARCHEXP
431b0fc4 221
5c161494 222 INC INCLUDE_EXT LDFROM LIB LIBPERL_A LIBS
2530b651
MS
223 LINKTYPE MAKEAPERL MAKEFILE MAKEFILE_OLD MAN1PODS MAN3PODS MAP_TARGET
224 MYEXTLIB NAME NEEDS_LINKING NOECHO NO_META NORECURS NO_VC OBJECT OPTIMIZE
431b0fc4 225 PERL_MALLOC_OK PERL PERLMAINCC PERLRUN PERLRUNINST PERL_CORE
5c161494 226 PERL_SRC PERM_RW PERM_RWX
131aa089 227 PL_FILES PM PM_FILTER PMLIBDIRS POLLUTE PPM_INSTALL_EXEC
5c161494 228 PPM_INSTALL_SCRIPT PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ
bb68fe9e 229 SIGN SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
f1387719 230 XS_VERSION clean depend dist dynamic_lib linkext macro realclean
762efda7 231 tool_autosplit
431b0fc4 232
084592ab
CN
233 MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
234 MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
f6d6199c 235 /;
3b03c0f3 236
875fa795 237 # IMPORTS is used under OS/2 and Win32
f1387719
PP
238
239 # @Overridable is close to @MM_Sections but not identical. The
240 # order is important. Many subroutines declare macros. These
241 # depend on each other. Let's try to collect the macros up front,
242 # then pasthru, then the rules.
243
244 # MM_Sections are the sections we have to call explicitly
245 # in Overridable we have subroutines that are used indirectly
3b03c0f3 246
e05e23b1
PP
247
248 @MM_Sections =
f6d6199c 249 qw(
3b03c0f3 250
479d2113
MS
251 post_initialize const_config constants platform_constants
252 tool_autosplit tool_xsubpp tools_other
253
254 makemakerdflt
255
256 dist macro depend cflags const_loadlibs const_cccmd
f1387719
PP
257 post_constants
258
259 pasthru
260
479d2113
MS
261 special_targets
262 c_o xs_c xs_o
263 top_targets linkext dlsyms dynamic dynamic_bs
f6d6199c 264 dynamic_lib static static_lib manifypods processPL
cae6c631 265 installbin subdirs
479d2113
MS
266 clean_subdirs clean realclean_subdirs realclean
267 metafile metafile_addtomanifest
bb68fe9e 268 signature signature_addtomanifest
479d2113 269 dist_basics dist_core distdir dist_test dist_ci
8f993c78 270 install force perldepend makefile staticmake test ppd
3b03c0f3 271
f6d6199c 272 ); # loses section ordering
e05e23b1 273
3b03c0f3 274 @Overridable = @MM_Sections;
f1387719
PP
275 push @Overridable, qw[
276
2366100d 277 dir_target libscan makeaperl needs_linking perm_rw perm_rwx
75e2e551 278 subdir_x test_via_harness test_via_script init_PERL
f6d6199c 279 ];
3b03c0f3 280
f1387719 281 push @MM_Sections, qw[
3b03c0f3 282
f1387719
PP
283 pm_to_blib selfdocument
284
f6d6199c 285 ];
f1387719
PP
286
287 # Postamble needs to be the last that was always the case
288 push @MM_Sections, "postamble";
289 push @Overridable, "postamble";
e05e23b1
PP
290
291 # All sections are valid keys.
3b03c0f3 292 @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
e05e23b1
PP
293
294 # we will use all these variables in the Makefile
295 @Get_from_Config =
f6d6199c
MS
296 qw(
297 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
298 lib_ext obj_ext osname osvers ranlib sitelibexp sitearchexp so
299 exe_ext full_ar
300 );
e05e23b1 301
479d2113
MS
302 # 5.5.3 doesn't have any concept of vendor libs
303 push @Get_from_Config, qw( vendorarchexp vendorlibexp ) if $] >= 5.006;
304
5e9e174b 305 foreach my $item (@attrib_help){
f6d6199c 306 $Recognized_Att_Keys{$item} = 1;
e05e23b1 307 }
5e9e174b 308 foreach my $item (@Get_from_Config) {
f6d6199c
MS
309 $Recognized_Att_Keys{uc $item} = $Config{$item};
310 print "Attribute '\U$item\E' => '$Config{$item}'\n"
311 if ($Verbose >= 2);
e05e23b1
PP
312 }
313
314 #
3b03c0f3
PP
315 # When we eval a Makefile.PL in a subdirectory, that one will ask
316 # us (the parent) for the values and will prepend "..", so that
317 # all files to be installed end up below OUR ./blib
e05e23b1 318 #
e0678a30
MS
319 @Prepend_parent = qw(
320 INST_BIN INST_LIB INST_ARCHLIB INST_SCRIPT
f6d6199c
MS
321 MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
322 PERL FULLPERL
323 );
e05e23b1 324}
42793c05 325
8e07c86e
AD
326sub writeMakefile {
327 die <<END;
232e078e 328
8e07c86e
AD
329The extension you are trying to build apparently is rather old and
330most probably outdated. We detect that from the fact, that a
331subroutine "writeMakefile" is called, and this subroutine is not
332supported anymore since about October 1994.
40000a8c 333
4633a7c4
LW
334Please contact the author or look into CPAN (details about CPAN can be
335found in the FAQ and at http:/www.perl.com) for a more recent version
336of the extension. If you're really desperate, you can try to change
337the subroutine name from writeMakefile to WriteMakefile and rerun
338'perl Makefile.PL', but you're most probably left alone, when you do
339so.
42793c05 340
8e07c86e 341The MakeMaker team
1aef975c 342
42793c05 343END
8e07c86e 344}
42793c05 345
f6d6199c 346sub new {
8e07c86e
AD
347 my($class,$self) = @_;
348 my($key);
42793c05 349
479d2113
MS
350 # Store the original args passed to WriteMakefile()
351 foreach my $k (keys %$self) {
352 $self->{ARGS}{$k} = $self->{$k};
353 }
354
88d69b28 355 if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
f6d6199c 356 require Data::Dumper;
88d69b28 357 print Data::Dumper->Dump([$self->{PREREQ_PM}], [qw(PREREQ_PM)]);
919b8535 358 exit 0;
f6d6199c 359 }
88d69b28
JH
360
361 # PRINT_PREREQ is RedHatism.
362 if ("@ARGV" =~ /\bPRINT_PREREQ\b/) {
2c91f887
JH
363 print join(" ", map { "perl($_)>=$self->{PREREQ_PM}->{$_} " }
364 sort keys %{$self->{PREREQ_PM}}), "\n";
f6d6199c 365 exit 0;
88d69b28
JH
366 }
367
e05e23b1 368 print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
8e07c86e 369 if (-f "MANIFEST" && ! -f "Makefile"){
f6d6199c 370 check_manifest();
1aef975c 371 }
42793c05 372
8e07c86e 373 $self = {} unless (defined $self);
005c1a0e 374
864a5fa8 375 check_hints($self);
4633a7c4 376
c3be8c6e 377 my %configure_att; # record &{$self->{CONFIGURE}} attributes
8e07c86e 378 my(%initial_att) = %$self; # record initial attributes
005c1a0e 379
a4260cbc 380 my(%unsatisfied) = ();
5e9e174b 381 foreach my $prereq (sort keys %{$self->{PREREQ_PM}}) {
479d2113
MS
382 # 5.8.0 has a bug with require Foo::Bar alone in an eval, so an
383 # extra statement is a workaround.
384 eval "require $prereq; 0";
f6d6199c 385
e0678a30
MS
386 my $pr_version = $prereq->VERSION || 0;
387
479d2113
MS
388 # convert X.Y_Z alpha version #s to X.YZ for easier comparisons
389 $pr_version =~ s/(\d+)\.(\d+)_(\d+)/$1.$2$3/;
390
f6d6199c
MS
391 if ($@) {
392 warn sprintf "Warning: prerequisite %s %s not found.\n",
393 $prereq, $self->{PREREQ_PM}{$prereq}
394 unless $self->{PREREQ_FATAL};
395 $unsatisfied{$prereq} = 'not installed';
e0678a30 396 } elsif ($pr_version < $self->{PREREQ_PM}->{$prereq} ){
45bc4d3a 397 warn sprintf "Warning: prerequisite %s %s not found. We have %s.\n",
f6d6199c 398 $prereq, $self->{PREREQ_PM}{$prereq},
e0678a30 399 ($pr_version || 'unknown version')
f6d6199c
MS
400 unless $self->{PREREQ_FATAL};
401 $unsatisfied{$prereq} = $self->{PREREQ_PM}->{$prereq} ?
402 $self->{PREREQ_PM}->{$prereq} : 'unknown version' ;
403 }
f1387719 404 }
a4260cbc 405 if (%unsatisfied && $self->{PREREQ_FATAL}){
f6d6199c
MS
406 my $failedprereqs = join ', ', map {"$_ $unsatisfied{$_}"}
407 keys %unsatisfied;
408 die qq{MakeMaker FATAL: prerequisites not found ($failedprereqs)\n
409 Please install these modules first and rerun 'perl Makefile.PL'.\n};
a4260cbc 410 }
f1387719 411
8e07c86e 412 if (defined $self->{CONFIGURE}) {
f6d6199c
MS
413 if (ref $self->{CONFIGURE} eq 'CODE') {
414 %configure_att = %{&{$self->{CONFIGURE}}};
415 $self = { %$self, %configure_att };
416 } else {
417 Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
418 }
005c1a0e 419 }
a0d0e21e 420
8e07c86e
AD
421 # This is for old Makefiles written pre 5.00, will go away
422 if ( Carp::longmess("") =~ /runsubdirpl/s ){
f6d6199c 423 Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
8e07c86e 424 }
5d94fbed 425
ccd13d1e 426 my $newclass = ++$PACKNAME;
f6d6199c 427 local @Parent = @Parent; # Protect against non-local exits
8e07c86e 428 {
f6d6199c
MS
429 no strict 'refs';
430 print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
431 mv_all_methods("MY",$newclass);
432 bless $self, $newclass;
433 push @Parent, $self;
434 require ExtUtils::MY;
435 @{"$newclass\:\:ISA"} = 'MM';
8e07c86e 436 }
5d94fbed 437
e05e23b1 438 if (defined $Parent[-2]){
f6d6199c
MS
439 $self->{PARENT} = $Parent[-2];
440 my $key;
e0678a30 441 for $key (@Prepend_parent) {
f6d6199c 442 next unless defined $self->{PARENT}{$key};
531e2ba1
JH
443
444 # Don't stomp on WriteMakefile() args.
46442182
JH
445 next if defined $self->{ARGS}{$key} and
446 $self->{ARGS}{$key} eq $self->{$key};
447
448 $self->{$key} = $self->{PARENT}{$key};
531e2ba1 449
479d2113 450 unless ($Is_VMS && $key =~ /PERL$/) {
f6d6199c
MS
451 $self->{$key} = $self->catdir("..",$self->{$key})
452 unless $self->file_name_is_absolute($self->{$key});
453 } else {
454 # PERL or FULLPERL will be a command verb or even a
455 # command with an argument instead of a full file
456 # specification under VMS. So, don't turn the command
457 # into a filespec, but do add a level to the path of
458 # the argument if not already absolute.
459 my @cmd = split /\s+/, $self->{$key};
460 $cmd[1] = $self->catfile('[-]',$cmd[1])
461 unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
462 $self->{$key} = join(' ', @cmd);
463 }
464 }
465 if ($self->{PARENT}) {
466 $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
467 foreach my $opt (qw(POLLUTE PERL_CORE)) {
468 if (exists $self->{PARENT}->{$opt}
469 and not exists $self->{$opt})
470 {
471 # inherit, but only if already unspecified
472 $self->{$opt} = $self->{PARENT}->{$opt};
473 }
474 }
475 }
476 my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
477 parse_args($self,@fm) if @fm;
8e07c86e 478 } else {
f6d6199c 479 parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
8e07c86e 480 }
a0d0e21e 481
8e07c86e 482 $self->{NAME} ||= $self->guess_name;
a0d0e21e 483
8e07c86e 484 ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
a0d0e21e 485
479d2113
MS
486 $self->init_main;
487 $self->init_VERSION;
488 $self->init_dist;
489 $self->init_INST;
490 $self->init_INSTALL;
531e2ba1 491 $self->init_DEST;
479d2113
MS
492 $self->init_dirscan;
493 $self->init_xs;
494 $self->init_PERL;
495 $self->init_DIRFILESEP;
496 $self->init_linker;
8e07c86e 497
0d8023a2 498 if (! $self->{PERL_SRC} ) {
f6d6199c
MS
499 require VMS::Filespec if $Is_VMS;
500 my($pthinks) = $self->canonpath($INC{'Config.pm'});
501 my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
502 $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
503 if ($pthinks ne $cthinks &&
504 !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
3e3baf6d 505 print "Have $pthinks expected $cthinks\n";
f6d6199c
MS
506 if ($Is_Win32) {
507 $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
508 }
509 else {
510 $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
511 }
512 print STDOUT <<END unless $self->{UNINSTALLED_PERL};
513Your perl and your Config.pm seem to have different ideas about the
514architecture they are running on.
8e07c86e 515Perl thinks: [$pthinks]
e05e23b1 516Config says: [$Config{archname}]
f6d6199c
MS
517This may or may not cause problems. Please check your installation of perl
518if you have problems building this extension.
005c1a0e 519END
f6d6199c 520 }
005c1a0e
AD
521 }
522
8e07c86e 523 $self->init_others();
479d2113 524 $self->init_platform();
e0678a30 525 $self->init_PERM();
6071deed
GS
526 my($argv) = neatvalue(\@ARGV);
527 $argv =~ s/^\[/(/;
528 $argv =~ s/\]$/)/;
75f92628 529
8e07c86e
AD
530 push @{$self->{RESULT}}, <<END;
531# This Makefile is for the $self->{NAME} extension to perl.
532#
e05e23b1
PP
533# It was generated automatically by MakeMaker version
534# $VERSION (Revision: $Revision) from the contents of
535# Makefile.PL. Don't edit this file, edit Makefile.PL instead.
8e07c86e 536#
f6d6199c 537# ANY CHANGES MADE HERE WILL BE LOST!
8e07c86e 538#
6071deed
GS
539# MakeMaker ARGV: $argv
540#
8e07c86e
AD
541# MakeMaker Parameters:
542END
a0d0e21e 543
5e9e174b 544 foreach my $key (sort keys %initial_att){
479d2113
MS
545 next if $key eq 'ARGS';
546
f6d6199c
MS
547 my($v) = neatvalue($initial_att{$key});
548 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
549 $v =~ tr/\n/ /s;
550 push @{$self->{RESULT}}, "# $key => $v";
42793c05 551 }
c3be8c6e
DK
552 undef %initial_att; # free memory
553
554 if (defined $self->{CONFIGURE}) {
555 push @{$self->{RESULT}}, <<END;
556
557# MakeMaker 'CONFIGURE' Parameters:
558END
559 if (scalar(keys %configure_att) > 0) {
5e9e174b 560 foreach my $key (sort keys %configure_att){
479d2113 561 next if $key eq 'ARGS';
c3be8c6e
DK
562 my($v) = neatvalue($configure_att{$key});
563 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
564 $v =~ tr/\n/ /s;
565 push @{$self->{RESULT}}, "# $key => $v";
566 }
567 }
568 else
569 {
570 push @{$self->{RESULT}}, "# no values returned";
571 }
572 undef %configure_att; # free memory
573 }
a0d0e21e 574
8e07c86e
AD
575 # turn the SKIP array into a SKIPHASH hash
576 my (%skip,$skip);
577 for $skip (@{$self->{SKIP} || []}) {
f6d6199c 578 $self->{SKIPHASH}{$skip} = 1;
8e07c86e 579 }
3b03c0f3
PP
580 delete $self->{SKIP}; # free memory
581
582 if ($self->{PARENT}) {
479d2113 583 for (qw/install dist dist_basics dist_core distdir dist_test dist_ci/) {
f6d6199c
MS
584 $self->{SKIPHASH}{$_} = 1;
585 }
3b03c0f3 586 }
42793c05 587
8e07c86e
AD
588 # We run all the subdirectories now. They don't have much to query
589 # from the parent, but the parent has to query them: if they need linking!
8e07c86e 590 unless ($self->{NORECURS}) {
f6d6199c 591 $self->eval_in_subdirs if @{$self->{DIR}};
42793c05 592 }
a0d0e21e 593
5e9e174b 594 foreach my $section ( @MM_Sections ){
479d2113
MS
595 # Support for new foo_target() methods.
596 my $method = $section;
597 $method .= '_target' unless $self->can($method);
598
f6d6199c
MS
599 print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
600 my($skipit) = $self->skipcheck($section);
601 if ($skipit){
602 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
603 } else {
604 my(%a) = %{$self->{$section} || {}};
605 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
606 push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
479d2113 607 push @{$self->{RESULT}}, $self->nicetext($self->$method( %a ));
f6d6199c 608 }
232e078e 609 }
8e07c86e 610
e05e23b1 611 push @{$self->{RESULT}}, "\n# End.";
8e07c86e 612
e05e23b1 613 $self;
232e078e
AD
614}
615
1b171b8d 616sub WriteEmptyMakefile {
a8112c7f 617 Carp::croak "WriteEmptyMakefile: Need even number of args" if @_ % 2;
a8112c7f
IZ
618
619 my %att = @_;
620 my $self = MM->new(\%att);
479d2113 621 if (-f $self->{MAKEFILE_OLD}) {
dedf98bc
MS
622 _unlink($self->{MAKEFILE_OLD}) or
623 warn "unlink $self->{MAKEFILE_OLD}: $!";
479d2113
MS
624 }
625 if ( -f $self->{MAKEFILE} ) {
dedf98bc
MS
626 _rename($self->{MAKEFILE}, $self->{MAKEFILE_OLD}) or
627 warn "rename $self->{MAKEFILE} => $self->{MAKEFILE_OLD}: $!"
a8112c7f 628 }
57b1a898 629 open MF, '>'.$self->{MAKEFILE} or die "open $self->{MAKEFILE} for write: $!";
a8112c7f 630 print MF <<'EOP';
1b171b8d
NIS
631all:
632
633clean:
634
635install:
636
637makemakerdflt:
638
639test:
640
641EOP
a8112c7f 642 close MF or die "close $self->{MAKEFILE} for write: $!";
1b171b8d
NIS
643}
644
e05e23b1
PP
645sub check_manifest {
646 print STDOUT "Checking if your kit is complete...\n";
3b03c0f3 647 require ExtUtils::Manifest;
5e9e174b
MS
648 # avoid warning
649 $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
650 my(@missed) = ExtUtils::Manifest::manicheck();
651 if (@missed) {
f6d6199c
MS
652 print STDOUT "Warning: the following files are missing in your kit:\n";
653 print "\t", join "\n\t", @missed;
654 print STDOUT "\n";
655 print STDOUT "Please inform the author.\n";
8e07c86e 656 } else {
f6d6199c 657 print STDOUT "Looks good\n";
8e07c86e 658 }
8e07c86e
AD
659}
660
e05e23b1
PP
661sub parse_args{
662 my($self, @args) = @_;
5e9e174b 663 foreach (@args) {
f6d6199c 664 unless (m/(.*?)=(.*)/) {
f6d6199c
MS
665 ++$Verbose if m/^verb/;
666 next;
667 }
668 my($name, $value) = ($1, $2);
669 if ($value =~ m/^~(\w+)?/) { # tilde with optional username
670 $value =~ s [^~(\w*)]
671 [$1 ?
672 ((getpwnam($1))[7] || "~$1") :
673 (getpwuid($>))[7]
674 ]ex;
675 }
479d2113
MS
676
677 # Remember the original args passed it. It will be useful later.
678 $self->{ARGS}{uc $name} = $self->{uc $name} = $value;
8e07c86e 679 }
8e07c86e 680
e05e23b1
PP
681 # catch old-style 'potential_libs' and inform user how to 'upgrade'
682 if (defined $self->{potential_libs}){
f6d6199c
MS
683 my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
684 if ($self->{potential_libs}){
685 print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
686 } else {
687 print STDOUT "$msg deleted.\n";
688 }
689 $self->{LIBS} = [$self->{potential_libs}];
690 delete $self->{potential_libs};
8e07c86e 691 }
e05e23b1
PP
692 # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
693 if (defined $self->{ARMAYBE}){
f6d6199c
MS
694 my($armaybe) = $self->{ARMAYBE};
695 print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
696 "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
697 my(%dl) = %{$self->{dynamic_lib} || {}};
698 $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
699 delete $self->{ARMAYBE};
8e07c86e 700 }
e05e23b1 701 if (defined $self->{LDTARGET}){
f6d6199c
MS
702 print STDOUT "LDTARGET should be changed to LDFROM\n";
703 $self->{LDFROM} = $self->{LDTARGET};
704 delete $self->{LDTARGET};
8e07c86e 705 }
e05e23b1
PP
706 # Turn a DIR argument on the command line into an array
707 if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
f6d6199c
MS
708 # So they can choose from the command line, which extensions they want
709 # the grep enables them to have some colons too much in case they
710 # have to build a list with the shell
711 $self->{DIR} = [grep $_, split ":", $self->{DIR}];
8e07c86e 712 }
f1387719
PP
713 # Turn a INCLUDE_EXT argument on the command line into an array
714 if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
f6d6199c 715 $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
f1387719
PP
716 }
717 # Turn a EXCLUDE_EXT argument on the command line into an array
718 if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
f6d6199c 719 $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
f1387719 720 }
5e9e174b
MS
721
722 foreach my $mmkey (sort keys %$self){
479d2113 723 next if $mmkey eq 'ARGS';
f6d6199c
MS
724 print STDOUT " $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
725 print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
726 unless exists $Recognized_Att_Keys{$mmkey};
e05e23b1 727 }
f1387719 728 $| = 1 if $Verbose;
e05e23b1 729}
8e07c86e 730
e05e23b1
PP
731sub check_hints {
732 my($self) = @_;
733 # We allow extension-specific hints files.
864a5fa8 734
479d2113
MS
735 require File::Spec;
736 my $curdir = File::Spec->curdir;
737
738 my $hint_dir = File::Spec->catdir($curdir, "hints");
739 return unless -d $hint_dir;
8e07c86e 740
e05e23b1 741 # First we look for the best hintsfile we have
f1387719 742 my($hint)="${^O}_$Config{osvers}";
e05e23b1
PP
743 $hint =~ s/\./_/g;
744 $hint =~ s/_$//;
745 return unless $hint;
fed7345c 746
e05e23b1
PP
747 # Also try without trailing minor version numbers.
748 while (1) {
479d2113 749 last if -f File::Spec->catfile($hint_dir, "$hint.pl"); # found
e05e23b1 750 } continue {
f6d6199c 751 last unless $hint =~ s/_[^_]*$//; # nothing to cut off
e05e23b1 752 }
479d2113 753 my $hint_file = File::Spec->catfile($hint_dir, "$hint.pl");
6626a13a
MS
754
755 return unless -f $hint_file; # really there
fed7345c 756
f6d6199c
MS
757 _run_hintfile($self, $hint_file);
758}
759
760sub _run_hintfile {
57b1a898 761 no strict 'vars';
f6d6199c
MS
762 local($self) = shift; # make $self available to the hint file.
763 my($hint_file) = shift;
764
479d2113 765 local($@, $!);
39234879 766 print STDERR "Processing hints file $hint_file\n";
479d2113
MS
767
768 # Just in case the ./ isn't on the hint file, which File::Spec can
769 # often strip off, we bung the curdir into @INC
770 local @INC = (File::Spec->curdir, @INC);
771 my $ret = do $hint_file;
772 if( !defined $ret ) {
773 my $error = $@ || $!;
774 print STDERR $error;
75e2e551 775 }
e05e23b1 776}
8e07c86e 777
e05e23b1
PP
778sub mv_all_methods {
779 my($from,$to) = @_;
5e9e174b 780 no strict 'refs';
e05e23b1 781 my($symtab) = \%{"${from}::"};
fed7345c 782
e05e23b1
PP
783 # Here you see the *current* list of methods that are overridable
784 # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
785 # still trying to reduce the list to some reasonable minimum --
786 # because I want to make it easier for the user. A.K.
40000a8c 787
57b1a898
MS
788 local $SIG{__WARN__} = sub {
789 # can't use 'no warnings redefined', 5.6 only
790 warn @_ unless $_[0] =~ /^Subroutine .* redefined/
791 };
5e9e174b 792 foreach my $method (@Overridable) {
fed7345c 793
f6d6199c
MS
794 # We cannot say "next" here. Nick might call MY->makeaperl
795 # which isn't defined right now
796
797 # Above statement was written at 4.23 time when Tk-b8 was
798 # around. As Tk-b9 only builds with 5.002something and MM 5 is
799 # standard, we try to enable the next line again. It was
800 # commented out until MM 5.23
801
802 next unless defined &{"${from}::$method"};
fed7345c 803
f6d6199c 804 *{"${to}::$method"} = \&{"${from}::$method"};
3b03c0f3 805
f6d6199c
MS
806 # delete would do, if we were sure, nobody ever called
807 # MY->makeaperl directly
fed7345c 808
f6d6199c 809 # delete $symtab->{$method};
8e07c86e 810
f6d6199c
MS
811 # If we delete a method, then it will be undefined and cannot
812 # be called. But as long as we have Makefile.PLs that rely on
813 # %MY:: being intact, we have to fill the hole with an
814 # inheriting method:
fed7345c 815
f6d6199c 816 eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
5d94fbed
AD
817 }
818
e05e23b1
PP
819 # We have to clean out %INC also, because the current directory is
820 # changed frequently and Graham Barr prefers to get his version
821 # out of a History.pl file which is "required" so woudn't get
822 # loaded again in another extension requiring a History.pl
a0d0e21e 823
f1387719
PP
824 # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
825 # to core dump in the middle of a require statement. The required
826 # file was Tk/MMutil.pm. The consequence is, we have to be
827 # extremely careful when we try to give perl a reason to reload a
828 # library with same name. The workaround prefers to drop nothing
829 # from %INC and teach the writers not to use such libraries.
830
831# my $inc;
832# foreach $inc (keys %INC) {
f6d6199c
MS
833# #warn "***$inc*** deleted";
834# delete $INC{$inc};
f1387719 835# }
8e07c86e
AD
836}
837
3b03c0f3 838sub skipcheck {
8e07c86e 839 my($self) = shift;
e05e23b1
PP
840 my($section) = @_;
841 if ($section eq 'dynamic') {
f6d6199c
MS
842 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
843 "in skipped section 'dynamic_bs'\n"
e05e23b1
PP
844 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
845 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
f6d6199c 846 "in skipped section 'dynamic_lib'\n"
e05e23b1 847 if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
8e07c86e 848 }
e05e23b1
PP
849 if ($section eq 'dynamic_lib') {
850 print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
f6d6199c 851 "targets in skipped section 'dynamic_bs'\n"
e05e23b1
PP
852 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
853 }
854 if ($section eq 'static') {
855 print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
f6d6199c 856 "in skipped section 'static_lib'\n"
e05e23b1 857 if $self->{SKIPHASH}{static_lib} && $Verbose;
8e07c86e 858 }
e05e23b1
PP
859 return 'skipped' if $self->{SKIPHASH}{$section};
860 return '';
8e07c86e
AD
861}
862
e05e23b1
PP
863sub flush {
864 my $self = shift;
865 my($chunk);
3b03c0f3 866 local *FH;
e05e23b1 867 print STDOUT "Writing $self->{MAKEFILE} for $self->{NAME}\n";
8e07c86e 868
e05e23b1 869 unlink($self->{MAKEFILE}, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : '');
3b03c0f3 870 open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
8e07c86e 871
e05e23b1 872 for $chunk (@{$self->{RESULT}}) {
f6d6199c 873 print FH "$chunk\n";
8e07c86e 874 }
e05e23b1 875
3b03c0f3 876 close FH;
e05e23b1 877 my($finalname) = $self->{MAKEFILE};
479d2113
MS
878 _rename("MakeMaker.tmp", $finalname) or
879 warn "rename MakeMaker.tmp => $finalname: $!";
e05e23b1 880 chmod 0644, $finalname unless $Is_VMS;
3b03c0f3 881
479d2113
MS
882 my %keep = map { ($_ => 1) } qw(NEEDS_LINKING HAS_LINK_CODE);
883
e0678a30 884 if ($self->{PARENT} && !$self->{_KEEP_AFTER_FLUSH}) {
f6d6199c 885 foreach (keys %$self) { # safe memory
479d2113 886 delete $self->{$_} unless $keep{$_};
f6d6199c 887 }
3b03c0f3
PP
888 }
889
e05e23b1 890 system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
40000a8c
AD
891}
892
479d2113
MS
893
894# This is a rename for OS's where the target must be unlinked first.
895sub _rename {
896 my($src, $dest) = @_;
897 chmod 0666, $dest;
898 unlink $dest;
899 return rename $src, $dest;
900}
901
dedf98bc
MS
902# This is an unlink for OS's where the target must be writable first.
903sub _unlink {
904 my @files = @_;
905 chmod 0666, @files;
906 return unlink @files;
907}
908
479d2113 909
e05e23b1
PP
910# The following mkbootstrap() is only for installations that are calling
911# the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
912# writes Makefiles, that use ExtUtils::Mkbootstrap directly.
913sub mkbootstrap {
914 die <<END;
915!!! Your Makefile has been built such a long time ago, !!!
916!!! that is unlikely to work with current MakeMaker. !!!
917!!! Please rebuild your Makefile !!!
918END
8e07c86e 919}
005c1a0e 920
e05e23b1
PP
921# Ditto for mksymlists() as of MakeMaker 5.17
922sub mksymlists {
923 die <<END;
924!!! Your Makefile has been built such a long time ago, !!!
925!!! that is unlikely to work with current MakeMaker. !!!
926!!! Please rebuild your Makefile !!!
927END
4633a7c4
LW
928}
929
e05e23b1
PP
930sub neatvalue {
931 my($v) = @_;
932 return "undef" unless defined $v;
933 my($t) = ref $v;
934 return "q[$v]" unless $t;
935 if ($t eq 'ARRAY') {
f6d6199c
MS
936 my(@m, @neat);
937 push @m, "[";
938 foreach my $elem (@$v) {
939 push @neat, "q[$elem]";
940 }
941 push @m, join ", ", @neat;
942 push @m, "]";
943 return join "", @m;
e05e23b1
PP
944 }
945 return "$v" unless $t eq 'HASH';
946 my(@m, $key, $val);
3b03c0f3 947 while (($key,$val) = each %$v){
f6d6199c
MS
948 last unless defined $key; # cautious programming in case (undef,undef) is true
949 push(@m,"$key=>".neatvalue($val)) ;
3b03c0f3 950 }
e05e23b1 951 return "{ ".join(', ',@m)." }";
4e68a208
AD
952}
953
e05e23b1
PP
954sub selfdocument {
955 my($self) = @_;
956 my(@m);
957 if ($Verbose){
f6d6199c
MS
958 push @m, "\n# Full list of MakeMaker attribute values:";
959 foreach my $key (sort keys %$self){
960 next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
961 my($v) = neatvalue($self->{$key});
962 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
963 $v =~ tr/\n/ /s;
964 push @m, "# $key => $v";
965 }
e05e23b1
PP
966 }
967 join "\n", @m;
968}
4e68a208 969
3b03c0f3
PP
9701;
971
972__END__
005c1a0e
AD
973
974=head1 NAME
975
479d2113 976ExtUtils::MakeMaker - Create a module Makefile
005c1a0e
AD
977
978=head1 SYNOPSIS
979
e0678a30 980 use ExtUtils::MakeMaker;
005c1a0e 981
e0678a30 982 WriteMakefile( ATTRIBUTE => VALUE [, ...] );
8e07c86e 983
005c1a0e
AD
984=head1 DESCRIPTION
985
986This utility is designed to write a Makefile for an extension module
987from a Makefile.PL. It is based on the Makefile.SH model provided by
988Andy Dougherty and the perl5-porters.
989
990It splits the task of generating the Makefile into several subroutines
991that can be individually overridden. Each subroutine returns the text
992it wishes to have written to the Makefile.
993
f1387719 994MakeMaker is object oriented. Each directory below the current
e0678a30 995directory that contains a Makefile.PL is treated as a separate
f1387719
PP
996object. This makes it possible to write an unlimited number of
997Makefiles with a single invocation of WriteMakefile().
8e07c86e 998
f1387719 999=head2 How To Write A Makefile.PL
8e07c86e 1000
479d2113 1001See ExtUtils::MakeMaker::Tutorial.
8e07c86e 1002
bab2b58e 1003The long answer is the rest of the manpage :-)
005c1a0e
AD
1004
1005=head2 Default Makefile Behaviour
1006
f1387719 1007The generated Makefile enables the user of the extension to invoke
005c1a0e
AD
1008
1009 perl Makefile.PL # optionally "perl Makefile.PL verbose"
1010 make
8e07c86e
AD
1011 make test # optionally set TEST_VERBOSE=1
1012 make install # See below
005c1a0e
AD
1013
1014The Makefile to be produced may be altered by adding arguments of the
e05e23b1 1015form C<KEY=VALUE>. E.g.
005c1a0e 1016
e05e23b1 1017 perl Makefile.PL PREFIX=/tmp/myperl5
005c1a0e
AD
1018
1019Other interesting targets in the generated Makefile are
1020
1021 make config # to check if the Makefile is up-to-date
8e07c86e
AD
1022 make clean # delete local temp files (Makefile gets renamed)
1023 make realclean # delete derived files (including ./blib)
e05e23b1 1024 make ci # check in all the files in the MANIFEST file
005c1a0e
AD
1025 make dist # see below the Distribution Support section
1026
e05e23b1
PP
1027=head2 make test
1028
bab2b58e 1029MakeMaker checks for the existence of a file named F<test.pl> in the
d5d4ec93
MS
1030current directory and if it exists it execute the script with the
1031proper set of perl C<-I> options.
e05e23b1
PP
1032
1033MakeMaker also checks for any files matching glob("t/*.t"). It will
d5d4ec93
MS
1034execute all matching files in alphabetical order via the
1035L<Test::Harness> module with the C<-I> switches set correctly.
1036
1037If you'd like to see the raw output of your tests, set the
1038C<TEST_VERBOSE> variable to true.
1039
1040 make test TEST_VERBOSE=1
e05e23b1 1041
bab2b58e
AK
1042=head2 make testdb
1043
1044A useful variation of the above is the target C<testdb>. It runs the
1045test under the Perl debugger (see L<perldebug>). If the file
1046F<test.pl> exists in the current directory, it is used for the test.
1047
d5d4ec93 1048If you want to debug some other testfile, set the C<TEST_FILE> variable
bab2b58e
AK
1049thusly:
1050
1051 make testdb TEST_FILE=t/mytest.t
1052
1053By default the debugger is called using C<-d> option to perl. If you
d5d4ec93 1054want to specify some other option, set the C<TESTDB_SW> variable:
bab2b58e
AK
1055
1056 make testdb TESTDB_SW=-Dx
1057
e05e23b1 1058=head2 make install
005c1a0e 1059
8e07c86e 1060make alone puts all relevant files into directories that are named by
f6d6199c
MS
1061the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
1062INST_MAN3DIR. All these default to something below ./blib if you are
1063I<not> building below the perl source directory. If you I<are>
1064building below the perl source, INST_LIB and INST_ARCHLIB default to
1065../../lib, and INST_SCRIPT is not defined.
005c1a0e 1066
e05e23b1
PP
1067The I<install> target of the generated Makefile copies the files found
1068below each of the INST_* directories to their INSTALL*
1069counterparts. Which counterparts are chosen depends on the setting of
1070INSTALLDIRS according to the following table:
005c1a0e 1071
f6d6199c 1072 INSTALLDIRS set to
5c161494 1073 perl site vendor
e05e23b1 1074
479d2113 1075 PERLPREFIX SITEPREFIX VENDORPREFIX
5c161494
MS
1076 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
1077 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
1078 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
1079 INST_SCRIPT INSTALLSCRIPT INSTALLSCRIPT INSTALLSCRIPT
1080 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
1081 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
005c1a0e 1082
8e07c86e
AD
1083The INSTALL... macros in turn default to their %Config
1084($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
005c1a0e 1085
3b03c0f3
PP
1086You can check the values of these variables on your system with
1087
bab2b58e 1088 perl '-V:install.*'
3b03c0f3 1089
f1387719
PP
1090And to check the sequence in which the library directories are
1091searched by perl, run
005c1a0e 1092
f1387719 1093 perl -le 'print join $/, @INC'
005c1a0e 1094
005c1a0e 1095
bab2b58e
AK
1096=head2 PREFIX and LIB attribute
1097
1098PREFIX and LIB can be used to set several INSTALL* attributes in one
1099go. The quickest way to install a module in a non-standard place might
1100be
1101
f6d6199c 1102 perl Makefile.PL PREFIX=~
005c1a0e 1103
f6d6199c
MS
1104This will install all files in the module under your home directory,
1105with man pages and libraries going into an appropriate place (usually
1106~/man and ~/lib).
bab2b58e
AK
1107
1108Another way to specify many INSTALL directories with a single
f6d6199c 1109parameter is LIB.
005c1a0e 1110
f6d6199c 1111 perl Makefile.PL LIB=~/lib
005c1a0e 1112
f6d6199c
MS
1113This will install the module's architecture-independent files into
1114~/lib, the architecture-dependent files into ~/lib/$archname.
005c1a0e 1115
bab2b58e 1116Note, that in both cases the tilde expansion is done by MakeMaker, not
e35b8f9e
JH
1117by perl by default, nor by make.
1118
f6d6199c
MS
1119Conflicts between parameters LIB, PREFIX and the various INSTALL*
1120arguments are resolved so that:
e35b8f9e
JH
1121
1122=over 4
1123
1124=item *
1125
1126setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
1127INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
1128
1129=item *
1130
1131without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
1132part of those INSTALL* arguments, even if the latter are explicitly
1133set (but are set to still start with C<$Config{prefix}>).
1134
1135=back
005c1a0e 1136
f6d6199c
MS
1137If the user has superuser privileges, and is not working on AFS or
1138relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
1139INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
1140the best:
005c1a0e 1141
e0678a30
MS
1142 perl Makefile.PL;
1143 make;
1144 make test
005c1a0e
AD
1145 make install
1146
8e07c86e 1147make install per default writes some documentation of what has been
e05e23b1
PP
1148done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1149can be bypassed by calling make pure_install.
8e07c86e
AD
1150
1151=head2 AFS users
1152
1153will have to specify the installation directories as these most
1154probably have changed since perl itself has been installed. They will
1155have to do this by calling
1156
e05e23b1 1157 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
f6d6199c 1158 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
8e07c86e
AD
1159 make
1160
e05e23b1
PP
1161Be careful to repeat this procedure every time you recompile an
1162extension, unless you are sure the AFS installation directories are
1163still valid.
005c1a0e 1164
8e07c86e 1165=head2 Static Linking of a new Perl Binary
005c1a0e
AD
1166
1167An extension that is built with the above steps is ready to use on
1168systems supporting dynamic loading. On systems that do not support
1169dynamic loading, any newly created extension has to be linked together
1170with the available resources. MakeMaker supports the linking process
1171by creating appropriate targets in the Makefile whenever an extension
1172is built. You can invoke the corresponding section of the makefile with
1173
1174 make perl
1175
1176That produces a new perl binary in the current directory with all
da7f727a 1177extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
e05e23b1
PP
1178and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1179UNIX, this is called Makefile.aperl (may be system dependent). If you
1180want to force the creation of a new perl, it is recommended, that you
1181delete this Makefile.aperl, so the directories are searched-through
1182for linkable libraries again.
005c1a0e
AD
1183
1184The binary can be installed into the directory where perl normally
1185resides on your machine with
1186
1187 make inst_perl
1188
1189To produce a perl binary with a different name than C<perl>, either say
1190
1191 perl Makefile.PL MAP_TARGET=myperl
1192 make myperl
1193 make inst_perl
1194
1195or say
1196
1197 perl Makefile.PL
1198 make myperl MAP_TARGET=myperl
1199 make inst_perl MAP_TARGET=myperl
1200
1201In any case you will be prompted with the correct invocation of the
1202C<inst_perl> target that installs the new binary into INSTALLBIN.
1203
8e07c86e
AD
1204make inst_perl per default writes some documentation of what has been
1205done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1206can be bypassed by calling make pure_inst_perl.
005c1a0e 1207
e05e23b1
PP
1208Warning: the inst_perl: target will most probably overwrite your
1209existing perl binary. Use with care!
005c1a0e 1210
8e07c86e
AD
1211Sometimes you might want to build a statically linked perl although
1212your system supports dynamic loading. In this case you may explicitly
1213set the linktype with the invocation of the Makefile.PL or make:
1214
1215 perl Makefile.PL LINKTYPE=static # recommended
1216
1217or
1218
1219 make LINKTYPE=static # works on most systems
1220
005c1a0e
AD
1221=head2 Determination of Perl Library and Installation Locations
1222
1223MakeMaker needs to know, or to guess, where certain things are
e05e23b1
PP
1224located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1225during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1226existing modules from), and PERL_INC (header files and C<libperl*.*>).
005c1a0e
AD
1227
1228Extensions may be built either using the contents of the perl source
e05e23b1
PP
1229directory tree or from the installed perl library. The recommended way
1230is to build extensions after you have run 'make install' on perl
1231itself. You can do that in any directory on your hard disk that is not
1232below the perl source tree. The support for extensions below the ext
1233directory of the perl distribution is only good for the standard
1234extensions that come with perl.
005c1a0e
AD
1235
1236If an extension is being built below the C<ext/> directory of the perl
e05e23b1
PP
1237source then MakeMaker will set PERL_SRC automatically (e.g.,
1238C<../..>). If PERL_SRC is defined and the extension is recognized as
1239a standard extension, then other variables default to the following:
005c1a0e
AD
1240
1241 PERL_INC = PERL_SRC
1242 PERL_LIB = PERL_SRC/lib
1243 PERL_ARCHLIB = PERL_SRC/lib
1244 INST_LIB = PERL_LIB
1245 INST_ARCHLIB = PERL_ARCHLIB
1246
1247If an extension is being built away from the perl source then MakeMaker
1248will leave PERL_SRC undefined and default to using the installed copy
1249of the perl library. The other variables default to the following:
1250
e05e23b1
PP
1251 PERL_INC = $archlibexp/CORE
1252 PERL_LIB = $privlibexp
1253 PERL_ARCHLIB = $archlibexp
1254 INST_LIB = ./blib/lib
1255 INST_ARCHLIB = ./blib/arch
005c1a0e
AD
1256
1257If perl has not yet been installed then PERL_SRC can be defined on the
1258command line as shown in the previous section.
1259
005c1a0e 1260
f1387719 1261=head2 Which architecture dependent directory?
005c1a0e 1262
f1387719
PP
1263If you don't want to keep the defaults for the INSTALL* macros,
1264MakeMaker helps you to minimize the typing needed: the usual
1265relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1266by Configure at perl compilation time. MakeMaker supports the user who
1267sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1268then MakeMaker defaults the latter to be the same subdirectory of
1269INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1270otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1271for INSTALLSITELIB and INSTALLSITEARCH.
005c1a0e 1272
f1387719
PP
1273MakeMaker gives you much more freedom than needed to configure
1274internal variables and get different results. It is worth to mention,
1275that make(1) also lets you configure most of the variables that are
1276used in the Makefile. But in the majority of situations this will not
a7665c5e 1277be necessary, and should only be done if the author of a package
f1387719 1278recommends it (or you know what you're doing).
005c1a0e 1279
e05e23b1 1280=head2 Using Attributes and Parameters
005c1a0e 1281
a884ca7c
MS
1282The following attributes may be specified as arguments to WriteMakefile()
1283or as NAME=VALUE pairs on the command line.
005c1a0e 1284
875fa795 1285=over 2
005c1a0e 1286
875fa795
JD
1287=item ABSTRACT
1288
1289One line description of the module. Will be included in PPD file.
1290
1291=item ABSTRACT_FROM
1292
1293Name of the file that contains the package description. MakeMaker looks
1294for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1295the first line in the "=head1 NAME" section. $2 becomes the abstract.
1296
e35b8f9e
JH
1297=item AUTHOR
1298
1299String containing name (and email address) of package author(s). Is used
1300in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1301
875fa795
JD
1302=item BINARY_LOCATION
1303
1304Used when creating PPD files for binary packages. It can be set to a
1305full or relative path or URL to the binary archive for a particular
1306architecture. For example:
1307
f6d6199c 1308 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
875fa795
JD
1309
1310builds a PPD package that references a binary of the C<Agent> package,
20e08411 1311located in the C<x86> directory relative to the PPD itself.
8e07c86e 1312
864a5fa8 1313=item C
8e07c86e 1314
864a5fa8
AD
1315Ref to array of *.c file names. Initialised from a directory scan
1316and the values portion of the XS attribute hash. This is not
1317currently used by MakeMaker but may be handy in Makefile.PLs.
8e07c86e 1318
84902520
TB
1319=item CCFLAGS
1320
1321String that will be included in the compiler call command line between
1322the arguments INC and OPTIMIZE.
1323
864a5fa8 1324=item CONFIG
8e07c86e 1325
864a5fa8
AD
1326Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1327config.sh. MakeMaker will add to CONFIG the following values anyway:
1328ar
1329cc
1330cccdlflags
1331ccdlflags
1332dlext
1333dlsrc
1334ld
1335lddlflags
1336ldflags
1337libc
1338lib_ext
1339obj_ext
1340ranlib
e05e23b1
PP
1341sitelibexp
1342sitearchexp
864a5fa8 1343so
8e07c86e
AD
1344
1345=item CONFIGURE
1346
e05e23b1 1347CODE reference. The subroutine should return a hash reference. The
1fef88e7 1348hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
8e07c86e
AD
1349be determined by some evaluation method.
1350
864a5fa8 1351=item DEFINE
8e07c86e 1352
864a5fa8 1353Something like C<"-DHAVE_UNISTD_H">
8e07c86e 1354
479d2113
MS
1355=item DESTDIR
1356
1357This is the root directory into which the code will be installed. It
1358I<prepends itself to the normal prefix>. For example, if your code
531e2ba1 1359would normally go into /usr/local/lib/perl you could set DESTDIR=/tmp/
479d2113
MS
1360and installation would go into /tmp/usr/local/lib/perl.
1361
1362This is primarily of use for people who repackage Perl modules.
1363
531e2ba1
JH
1364NOTE: Due to the nature of make, it is important that you put the trailing
1365slash on your DESTDIR. "/tmp/" not "/tmp".
479d2113 1366
864a5fa8 1367=item DIR
8e07c86e 1368
864a5fa8
AD
1369Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1370] in ext/SDBM_File
8e07c86e 1371
864a5fa8 1372=item DISTNAME
8e07c86e 1373
479d2113
MS
1374A safe filename for the package.
1375
1376Defaults to NAME above but with :: replaced with -.
1377
1378For example, Foo::Bar becomes Foo-Bar.
1379
1380=item DISTVNAME
1381
1382Your name for distributing the package with the version number
1383included. This is used by 'make dist' to name the resulting archive
1384file.
1385
1386Defaults to DISTNAME-VERSION.
1387
1388For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
1389
1390On some OS's where . has special meaning VERSION_SYM may be used in
1391place of VERSION.
8e07c86e 1392
864a5fa8 1393=item DL_FUNCS
8e07c86e 1394
875fa795
JD
1395Hashref of symbol names for routines to be made available as universal
1396symbols. Each key/value pair consists of the package name and an
1397array of routine names in that package. Used only under AIX, OS/2,
1398VMS and Win32 at present. The routine names supplied will be expanded
1399in the same way as XSUB names are expanded by the XS() macro.
1400Defaults to
8e07c86e 1401
864a5fa8 1402 {"$(NAME)" => ["boot_$(NAME)" ] }
8e07c86e 1403
864a5fa8 1404e.g.
8e07c86e 1405
864a5fa8
AD
1406 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1407 "NetconfigPtr" => [ 'DESTROY'] }
8e07c86e 1408
875fa795
JD
1409Please see the L<ExtUtils::Mksymlists> documentation for more information
1410about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1411
864a5fa8 1412=item DL_VARS
8e07c86e 1413
875fa795
JD
1414Array of symbol names for variables to be made available as universal symbols.
1415Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1416(e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
8e07c86e 1417
f1387719
PP
1418=item EXCLUDE_EXT
1419
1420Array of extension names to exclude when doing a static build. This
1421is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1422details. (e.g. [ qw( Socket POSIX ) ] )
1423
1424This attribute may be most useful when specified as a string on the
de592821 1425command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
f1387719 1426
864a5fa8 1427=item EXE_FILES
8e07c86e 1428
864a5fa8 1429Ref to array of executable files. The files will be copied to the
f1387719 1430INST_SCRIPT directory. Make realclean will delete them from there
864a5fa8 1431again.
8e07c86e 1432
2530b651
MS
1433If your executables start with something like #!perl or
1434#!/usr/bin/perl MakeMaker will change this to the path of the perl
1435'Makefile.PL' was invoked with so the programs will be sure to run
1436properly even if perl is not in /usr/bin/perl.
1437
864a5fa8
AD
1438=item FIRST_MAKEFILE
1439
479d2113
MS
1440The name of the Makefile to be produced. This is used for the second
1441Makefile that will be produced for the MAP_TARGET.
1442
1443Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
1444
1445(Note: we couldn't use MAKEFILE because dmake uses this for something
1446else).
864a5fa8
AD
1447
1448=item FULLPERL
8e07c86e 1449
75e2e551
MS
1450Perl binary able to run this extension, load XS modules, etc...
1451
1452=item FULLPERLRUN
1453
1454Like PERLRUN, except it uses FULLPERL.
1455
1456=item FULLPERLRUNINST
1457
1458Like PERLRUNINST, except it uses FULLPERL.
864a5fa8 1459
762efda7
JD
1460=item FUNCLIST
1461
1462This provides an alternate means to specify function names to be
1463exported from the extension. Its value is a reference to an
1464array of function names to be exported by the extension. These
1465names are passed through unaltered to the linker options file.
1466
864a5fa8
AD
1467=item H
1468
1469Ref to array of *.h file names. Similar to C.
1470
84902520
TB
1471=item IMPORTS
1472
875fa795 1473This attribute is used to specify names to be imported into the
69ff8adf
JH
1474extension. Takes a hash ref.
1475
1476It is only used on OS/2 and Win32.
84902520 1477
864a5fa8
AD
1478=item INC
1479
1480Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1481
f1387719
PP
1482=item INCLUDE_EXT
1483
1484Array of extension names to be included when doing a static build.
1485MakeMaker will normally build with all of the installed extensions when
1486doing a static build, and that is usually the desired behavior. If
1487INCLUDE_EXT is present then MakeMaker will build only with those extensions
1488which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
1489
1490It is not necessary to mention DynaLoader or the current extension when
1491filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
1492only DynaLoader and the current extension will be included in the build.
1493
1494This attribute may be most useful when specified as a string on the
de592821 1495command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
f1387719 1496
864a5fa8
AD
1497=item INSTALLARCHLIB
1498
e05e23b1
PP
1499Used by 'make install', which copies files from INST_ARCHLIB to this
1500directory if INSTALLDIRS is set to perl.
864a5fa8
AD
1501
1502=item INSTALLBIN
1503
5c161494
MS
1504Directory to install binary files (e.g. tkperl) into if
1505INSTALLDIRS=perl.
e05e23b1
PP
1506
1507=item INSTALLDIRS
1508
5c161494
MS
1509Determines which of the sets of installation directories to choose:
1510perl, site or vendor. Defaults to site.
8e07c86e
AD
1511
1512=item INSTALLMAN1DIR
1513
1514=item INSTALLMAN3DIR
1515
5c161494
MS
1516These directories get the man pages at 'make install' time if
1517INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
8e07c86e 1518
5c161494 1519If set to 'none', no man pages will be installed.
e0678a30 1520
864a5fa8 1521=item INSTALLPRIVLIB
8e07c86e 1522
e05e23b1
PP
1523Used by 'make install', which copies files from INST_LIB to this
1524directory if INSTALLDIRS is set to perl.
1525
5c161494
MS
1526Defaults to $Config{installprivlib}.
1527
f1387719
PP
1528=item INSTALLSCRIPT
1529
1530Used by 'make install' which copies files from INST_SCRIPT to this
1531directory.
1532
875fa795 1533=item INSTALLSITEARCH
e05e23b1 1534
875fa795 1535Used by 'make install', which copies files from INST_ARCHLIB to this
e05e23b1
PP
1536directory if INSTALLDIRS is set to site (default).
1537
5c161494
MS
1538=item INSTALLSITEBIN
1539
1540Used by 'make install', which copies files from INST_BIN to this
1541directory if INSTALLDIRS is set to site (default).
1542
875fa795 1543=item INSTALLSITELIB
e05e23b1 1544
875fa795 1545Used by 'make install', which copies files from INST_LIB to this
e05e23b1 1546directory if INSTALLDIRS is set to site (default).
8e07c86e 1547
5c161494
MS
1548=item INSTALLSITEMAN1DIR
1549
1550=item INSTALLSITEMAN3DIR
1551
1552These directories get the man pages at 'make install' time if
1553INSTALLDIRS=site (default). Defaults to
1554$(SITEPREFIX)/man/man$(MAN*EXT).
1555
1556If set to 'none', no man pages will be installed.
1557
1558=item INSTALLVENDORARCH
1559
1560Used by 'make install', which copies files from INST_ARCHLIB to this
1561directory if INSTALLDIRS is set to vendor.
1562
1563=item INSTALLVENDORBIN
1564
1565Used by 'make install', which copies files from INST_BIN to this
1566directory if INSTALLDIRS is set to vendor.
1567
1568=item INSTALLVENDORLIB
1569
1570Used by 'make install', which copies files from INST_LIB to this
1571directory if INSTALLDIRS is set to vendor.
1572
1573=item INSTALLVENDORMAN1DIR
1574
1575=item INSTALLVENDORMAN3DIR
1576
1577These directories get the man pages at 'make install' time if
1578INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
1579
1580If set to 'none', no man pages will be installed.
1581
864a5fa8 1582=item INST_ARCHLIB
8e07c86e 1583
864a5fa8 1584Same as INST_LIB for architecture dependent files.
8e07c86e 1585
f1387719
PP
1586=item INST_BIN
1587
1588Directory to put real binary files during 'make'. These will be copied
1589to INSTALLBIN during 'make install'
1590
e35b8f9e
JH
1591=item INST_LIB
1592
1593Directory where we put library files of this extension while building
1594it.
1595
864a5fa8 1596=item INST_MAN1DIR
8e07c86e 1597
864a5fa8 1598Directory to hold the man pages at 'make' time
8e07c86e 1599
864a5fa8 1600=item INST_MAN3DIR
8e07c86e 1601
864a5fa8 1602Directory to hold the man pages at 'make' time
8e07c86e 1603
f1387719
PP
1604=item INST_SCRIPT
1605
1606Directory, where executable files should be installed during
c3fed81c 1607'make'. Defaults to "./blib/script", just to have a dummy location during
f1387719
PP
1608testing. make install will copy the files in INST_SCRIPT to
1609INSTALLSCRIPT.
1610
479d2113
MS
1611=item LD
1612
1613Program to be used to link libraries for dynamic loading.
1614
1615Defaults to $Config{ld}.
1616
a884ca7c
MS
1617=item LDDLFLAGS
1618
1619Any special flags that might need to be passed to ld to create a
1620shared library suitable for dynamic loading. It is up to the makefile
1621to use it. (See L<Config/lddlflags>)
1622
1623Defaults to $Config{lddlflags}.
1624
864a5fa8 1625=item LDFROM
8e07c86e 1626
69ff8adf 1627Defaults to "$(OBJECT)" and is used in the ld command to specify
864a5fa8
AD
1628what files to link/load from (also see dynamic_lib below for how to
1629specify ld flags)
8e07c86e 1630
bab2b58e
AK
1631=item LIB
1632
e35b8f9e 1633LIB should only be set at C<perl Makefile.PL> time but is allowed as a
f6d6199c
MS
1634MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
1635and INSTALLSITELIB to that value regardless any explicit setting of
1636those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
1637are set to the corresponding architecture subdirectory.
bab2b58e 1638
762efda7
JD
1639=item LIBPERL_A
1640
1641The filename of the perllibrary that will be used together with this
1642extension. Defaults to libperl.a.
1643
8e07c86e
AD
1644=item LIBS
1645
1646An anonymous array of alternative library
1647specifications to be searched for (in order) until
864a5fa8 1648at least one library is found. E.g.
8e07c86e
AD
1649
1650 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1651
1652Mind, that any element of the array
1653contains a complete set of arguments for the ld
1654command. So do not specify
1655
1656 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1657
1658See ODBM_File/Makefile.PL for an example, where an array is needed. If
1659you specify a scalar as in
1660
1661 'LIBS' => "-ltcl -ltk -lX11"
1662
1663MakeMaker will turn it into an array with one element.
1664
864a5fa8 1665=item LINKTYPE
8e07c86e 1666
e05e23b1
PP
1667'static' or 'dynamic' (default unless usedl=undef in
1668config.sh). Should only be used to force static linking (also see
864a5fa8 1669linkext below).
8e07c86e 1670
864a5fa8 1671=item MAKEAPERL
8e07c86e 1672
864a5fa8
AD
1673Boolean which tells MakeMaker, that it should include the rules to
1674make a perl. This is handled automatically as a switch by
1675MakeMaker. The user normally does not need it.
8e07c86e 1676
479d2113
MS
1677=item MAKEFILE_OLD
1678
1679When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
1680backed up at this location.
8e07c86e 1681
479d2113 1682Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
8e07c86e 1683
864a5fa8 1684=item MAN1PODS
8e07c86e 1685
864a5fa8
AD
1686Hashref of pod-containing files. MakeMaker will default this to all
1687EXE_FILES files that include POD directives. The files listed
1688here will be converted to man pages and installed as was requested
1689at Configure time.
8e07c86e 1690
864a5fa8 1691=item MAN3PODS
8e07c86e 1692
bfa2a9ad
A
1693Hashref that assigns to *.pm and *.pod files the files into which the
1694manpages are to be written. MakeMaker parses all *.pod and *.pm files
1695for POD directives. Files that contain POD will be the default keys of
1696the MAN3PODS hashref. These will then be converted to man pages during
1697C<make> and will be installed during C<make install>.
8e07c86e 1698
864a5fa8 1699=item MAP_TARGET
8e07c86e 1700
864a5fa8
AD
1701If it is intended, that a new perl binary be produced, this variable
1702may hold a name for that binary. Defaults to perl
8e07c86e 1703
864a5fa8 1704=item MYEXTLIB
4633a7c4 1705
864a5fa8
AD
1706If the extension links to a library that it builds set this to the
1707name of the library (see SDBM_File)
4633a7c4 1708
864a5fa8 1709=item NAME
8e07c86e 1710
864a5fa8
AD
1711Perl module name for this extension (DBD::Oracle). This will default
1712to the directory name but should be explicitly defined in the
1713Makefile.PL.
8e07c86e 1714
864a5fa8 1715=item NEEDS_LINKING
8e07c86e 1716
a7665c5e 1717MakeMaker will figure out if an extension contains linkable code
864a5fa8 1718anywhere down the directory tree, and will set this variable
a7665c5e 1719accordingly, but you can speed it up a very little bit if you define
864a5fa8 1720this boolean variable yourself.
8e07c86e 1721
e05e23b1
PP
1722=item NOECHO
1723
479d2113
MS
1724Command so make does not print the literal commands its running.
1725
1726By setting it to an empty string you can generate a Makefile that
1727prints all commands. Mainly used in debugging MakeMaker itself.
1728
1729Defaults to C<@>.
e05e23b1 1730
864a5fa8 1731=item NORECURS
8e07c86e 1732
e05e23b1 1733Boolean. Attribute to inhibit descending into subdirectories.
8e07c86e 1734
1df8d179
MS
1735=item NO_META
1736
1737When true, suppresses the generation and addition to the MANIFEST of
1738the META.yml module meta-data file during 'make distdir'.
1739
1740Defaults to false.
1741
762efda7
JD
1742=item NO_VC
1743
a7665c5e 1744In general, any generated Makefile checks for the current version of
762efda7
JD
1745MakeMaker and the version the Makefile was built under. If NO_VC is
1746set, the version check is neglected. Do not write this into your
1747Makefile.PL, use it interactively instead.
1748
864a5fa8 1749=item OBJECT
8e07c86e 1750
864a5fa8
AD
1751List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1752string containing all object files, e.g. "tkpBind.o
1753tkpButton.o tkpCanvas.o"
8e07c86e 1754
e35b8f9e
JH
1755(Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1756
3b03c0f3
PP
1757=item OPTIMIZE
1758
1759Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1760passed to subdirectory makes.
1761
864a5fa8 1762=item PERL
8e07c86e 1763
864a5fa8 1764Perl binary for tasks that can be done by miniperl
8e07c86e 1765
da7f727a
JH
1766=item PERL_CORE
1767
1768Set only when MakeMaker is building the extensions of the Perl core
1769distribution.
1770
864a5fa8 1771=item PERLMAINCC
005c1a0e 1772
864a5fa8
AD
1773The call to the program that is able to compile perlmain.c. Defaults
1774to $(CC).
005c1a0e 1775
864a5fa8 1776=item PERL_ARCHLIB
005c1a0e 1777
da7f727a
JH
1778Same as for PERL_LIB, but for architecture dependent files.
1779
1780Used only when MakeMaker is building the extensions of the Perl core
1781distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
1782and adding it would get in the way of PERL5LIB).
8e07c86e 1783
864a5fa8 1784=item PERL_LIB
8e07c86e 1785
864a5fa8 1786Directory containing the Perl library to use.
8e07c86e 1787
da7f727a
JH
1788Used only when MakeMaker is building the extensions of the Perl core
1789distribution (because normally $(PERL_LIB) is automatically in @INC,
1790and adding it would get in the way of PERL5LIB).
1791
e35b8f9e
JH
1792=item PERL_MALLOC_OK
1793
1794defaults to 0. Should be set to TRUE if the extension can work with
1795the memory allocation routines substituted by the Perl malloc() subsystem.
1796This should be applicable to most extensions with exceptions of those
1797
1798=over 4
1799
1800=item *
1801
1802with bugs in memory allocations which are caught by Perl's malloc();
1803
1804=item *
1805
1806which interact with the memory allocator in other ways than via
1807malloc(), realloc(), free(), calloc(), sbrk() and brk();
1808
1809=item *
1810
1811which rely on special alignment which is not provided by Perl's malloc().
1812
1813=back
1814
1815B<NOTE.> Negligence to set this flag in I<any one> of loaded extension
1816nullifies many advantages of Perl's malloc(), such as better usage of
1817system resources, error detection, memory usage reporting, catchable failure
1818of memory allocations, etc.
1819
479d2113
MS
1820=item PERLPREFIX
1821
1822Directory under which core modules are to be installed.
1823
1824Defaults to $Config{installprefixexp} falling back to
1825$Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1826$Config{installprefixexp} not exist.
1827
1828Overridden by PREFIX.
1829
da7f727a
JH
1830=item PERLRUN
1831
75e2e551
MS
1832Use this instead of $(PERL) when you wish to run perl. It will set up
1833extra necessary flags for you.
f6d6199c 1834
ffbaec2a 1835=item PERLRUNINST
f6d6199c 1836
75e2e551
MS
1837Use this instead of $(PERL) when you wish to run perl to work with
1838modules. It will add things like -I$(INST_ARCH) and other necessary
1839flags so perl can see the modules you're about to install.
f6d6199c 1840
864a5fa8 1841=item PERL_SRC
8e07c86e 1842
864a5fa8
AD
1843Directory containing the Perl source code (use of this should be
1844avoided, it may be undefined)
8e07c86e 1845
2366100d
A
1846=item PERM_RW
1847
de592821 1848Desired permission for read/writable files. Defaults to C<644>.
2366100d
A
1849See also L<MM_Unix/perm_rw>.
1850
1851=item PERM_RWX
1852
1853Desired permission for executable files. Defaults to C<755>.
1854See also L<MM_Unix/perm_rwx>.
1855
864a5fa8 1856=item PL_FILES
8e07c86e 1857
864a5fa8
AD
1858Ref to hash of files to be processed as perl programs. MakeMaker
1859will default to any found *.PL file (except Makefile.PL) being keys
1860and the basename of the file being the value. E.g.
8e07c86e 1861
864a5fa8 1862 {'foobar.PL' => 'foobar'}
8e07c86e 1863
864a5fa8 1864The *.PL files are expected to produce output to the target files
3aa35033
GS
1865themselves. If multiple files can be generated from the same *.PL
1866file then the value in the hash can be a reference to an array of
1867target file names. E.g.
1868
1869 {'foobar.PL' => ['foobar1','foobar2']}
8e07c86e 1870
864a5fa8 1871=item PM
8e07c86e 1872
864a5fa8 1873Hashref of .pm files and *.pl files to be installed. e.g.
8e07c86e 1874
864a5fa8 1875 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
8e07c86e 1876
a3cb178b
GS
1877By default this will include *.pm and *.pl and the files found in
1878the PMLIBDIRS directories. Defining PM in the
864a5fa8 1879Makefile.PL will override PMLIBDIRS.
8e07c86e 1880
864a5fa8 1881=item PMLIBDIRS
8e07c86e 1882
864a5fa8 1883Ref to array of subdirectories containing library files. Defaults to
a3cb178b 1884[ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
864a5fa8
AD
1885they contain will be installed in the corresponding location in the
1886library. A libscan() method can be used to alter the behaviour.
1887Defining PM in the Makefile.PL will override PMLIBDIRS.
8e07c86e 1888
e35b8f9e
JH
1889(Where BASEEXT is the last component of NAME.)
1890
131aa089
RM
1891=item PM_FILTER
1892
1893A filter program, in the traditional Unix sense (input from stdin, output
1894to stdout) that is passed on each .pm file during the build (in the
1895pm_to_blib() phase). It is empty by default, meaning no filtering is done.
1896
1897Great care is necessary when defining the command if quoting needs to be
1898done. For instance, you would need to say:
1899
1900 {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
1901
1902to remove all the leading coments on the fly during the build. The
1903extra \\ are necessary, unfortunately, because this variable is interpolated
1904within the context of a Perl program built on the command line, and double
1905quotes are what is used with the -e switch to build that command line. The
1906# is escaped for the Makefile, since what is going to be generated will then
1907be:
1908
1909 PM_FILTER = grep -v \"^\#\"
1910
1911Without the \\ before the #, we'd have the start of a Makefile comment,
1912and the macro would be incorrectly defined.
1913
2aea4d40
JD
1914=item POLLUTE
1915
1916Release 5.005 grandfathered old global symbol names by providing preprocessor
a7665c5e 1917macros for extension source compatibility. As of release 5.6, these
2aea4d40
JD
1918preprocessor definitions are not available by default. The POLLUTE flag
1919specifies that the old names should still be defined:
1920
1921 perl Makefile.PL POLLUTE=1
1922
1923Please inform the module author if this is necessary to successfully install
a7665c5e 1924a module under 5.6 or later.
2aea4d40 1925
875fa795
JD
1926=item PPM_INSTALL_EXEC
1927
20e08411 1928Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
875fa795
JD
1929
1930=item PPM_INSTALL_SCRIPT
1931
1932Name of the script that gets executed by the Perl Package Manager after
1933the installation of a package.
1934
864a5fa8 1935=item PREFIX
8e07c86e 1936
f6d6199c
MS
1937This overrides all the default install locations. Man pages,
1938libraries, scripts, etc... MakeMaker will try to make an educated
1939guess about where to place things under the new PREFIX based on your
1940Config defaults. Failing that, it will fall back to a structure
1941which should be sensible for your platform.
1942
1943If you specify LIB or any INSTALL* variables they will not be effected
1944by the PREFIX.
a4260cbc 1945
b2340c53
K
1946=item PREREQ_FATAL
1947
1948Bool. If this parameter is true, failing to have the required modules
1949(or the right versions thereof) will be fatal. perl Makefile.PL will die
1950with the proper message.
1951
1952Note: see L<Test::Harness> for a shortcut for stopping tests early if
1953you are missing dependencies.
1954
1955Do I<not> use this parameter for simple requirements, which could be resolved
1956at a later time, e.g. after an unsuccessful B<make test> of your module.
1957
1958It is I<extremely> rare to have to use C<PREREQ_FATAL> at all!
1959
d5d4ec93
MS
1960=item PREREQ_PM
1961
1962Hashref: Names of modules that need to be available to run this
1963extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
1964desired version is the value. If the required version number is 0, we
1965only check if any version is installed already.
1966
88d69b28
JH
1967=item PREREQ_PRINT
1968
1969Bool. If this parameter is true, the prerequisites will be printed to
2c91f887
JH
1970stdout and MakeMaker will exit. The output format is an evalable hash
1971ref.
88d69b28
JH
1972
1973$PREREQ_PM = {
1974 'A::B' => Vers1,
1975 'C::D' => Vers2,
1976 ...
1977 };
1978
1979=item PRINT_PREREQ
1980
1981RedHatism for C<PREREQ_PRINT>. The output format is different, though:
1982
1983 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1984
5c161494
MS
1985=item SITEPREFIX
1986
479d2113
MS
1987Like PERLPREFIX, but only for the site install locations.
1988
1989Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1990an explicit siteprefix in the Config. In those cases
1991$Config{installprefix} will be used.
5c161494 1992
479d2113 1993Overridable by PREFIX
5c161494 1994
bb68fe9e
AT
1995=item SIGN
1996
1997When true, perform the generation and addition to the MANIFEST of
1998the SIGNATURE file during 'make distdir', via 'cpansign -s'.
1999
2000Note that you need to install the Module::Signature module to
2001perform this operation.
2002
2003Defaults to false.
2004
864a5fa8 2005=item SKIP
8e07c86e 2006
da7f727a 2007Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
a7665c5e
GS
2008Makefile. Caution! Do not use the SKIP attribute for the negligible
2009speedup. It may seriously damage the resulting Makefile. Only use it
f1387719 2010if you really need it.
8e07c86e 2011
864a5fa8 2012=item TYPEMAPS
8e07c86e 2013
864a5fa8
AD
2014Ref to array of typemap file names. Use this when the typemaps are
2015in some directory other than the current directory or when they are
2016not named B<typemap>. The last typemap in the list takes
2017precedence. A typemap in the current directory has highest
2018precedence, even if it isn't listed in TYPEMAPS. The default system
2019typemap has lowest precedence.
8e07c86e 2020
5c161494
MS
2021=item VENDORPREFIX
2022
479d2113
MS
2023Like PERLPREFIX, but only for the vendor install locations.
2024
2025Defaults to $Config{vendorprefixexp}.
5c161494 2026
479d2113 2027Overridable by PREFIX
5c161494 2028
45bc4d3a
JH
2029=item VERBINST
2030
2031If true, make install will be verbose
2032
864a5fa8 2033=item VERSION
8e07c86e 2034
864a5fa8
AD
2035Your version number for distributing the package. This defaults to
20360.1.
8e07c86e 2037
0d8023a2
PP
2038=item VERSION_FROM
2039
2040Instead of specifying the VERSION in the Makefile.PL you can let
2041MakeMaker parse a file to determine the version number. The parsing
2042routine requires that the file named by VERSION_FROM contains one
2043single line to compute the version number. The first line in the file
2044that contains the regular expression
2045
84902520 2046 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
0d8023a2
PP
2047
2048will be evaluated with eval() and the value of the named variable
2049B<after> the eval() will be assigned to the VERSION attribute of the
2050MakeMaker object. The following lines will be parsed o.k.:
2051
2052 $VERSION = '1.00';
84902520 2053 *VERSION = \'1.01';
30361541 2054 $VERSION = sprintf "%d.%03d", q$Revision: 1.133 $ =~ /(\d+)/g;
0d8023a2 2055 $FOO::VERSION = '1.10';
84902520 2056 *FOO::VERSION = \'1.11';
f6d6199c 2057 our $VERSION = 1.2.3; # new for perl5.6.0
0d8023a2
PP
2058
2059but these will fail:
2060
2061 my $VERSION = '1.01';
2062 local $VERSION = '1.02';
2063 local $FOO::VERSION = '1.30';
2064
e35b8f9e
JH
2065(Putting C<my> or C<local> on the preceding line will work o.k.)
2066
84902520
TB
2067The file named in VERSION_FROM is not added as a dependency to
2068Makefile. This is not really correct, but it would be a major pain
2069during development to have to rewrite the Makefile for any smallish
2070change in that file. If you want to make sure that the Makefile
2071contains the correct VERSION macro after any change of the file, you
2072would have to do something like
2073
2074 depend => { Makefile => '$(VERSION_FROM)' }
2075
2076See attribute C<depend> below.
0d8023a2 2077
479d2113
MS
2078=item VERSION_SYM
2079
2080A sanitized VERSION with . replaced by _. For places where . has
2081special meaning (some filesystems, RCS labels, etc...)
2082
864a5fa8 2083=item XS
8e07c86e 2084
864a5fa8 2085Hashref of .xs files. MakeMaker will default this. e.g.
8e07c86e 2086
864a5fa8 2087 {'name_of_file.xs' => 'name_of_file.c'}
8e07c86e 2088
864a5fa8
AD
2089The .c files will automatically be included in the list of files
2090deleted by a make clean.
4633a7c4 2091
864a5fa8 2092=item XSOPT
8e07c86e 2093
864a5fa8
AD
2094String of options to pass to xsubpp. This might include C<-C++> or
2095C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
2096that purpose.
8e07c86e 2097
864a5fa8 2098=item XSPROTOARG
4633a7c4 2099
4e68a208 2100May be set to an empty string, which is identical to C<-prototypes>, or
864a5fa8 2101C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
4e68a208
AD
2102defaults to the empty string.
2103
0d8023a2
PP
2104=item XS_VERSION
2105
2106Your version number for the .xs file of this package. This defaults
2107to the value of the VERSION attribute.
2108
8e07c86e
AD
2109=back
2110
2111=head2 Additional lowercase attributes
2112
2113can be used to pass parameters to the methods which implement that
531e2ba1
JH
2114part of the Makefile. Parameters are specified as a hash ref but are
2115passed to the method as a hash.
8e07c86e
AD
2116
2117=over 2
2118
864a5fa8 2119=item clean
8e07c86e 2120
864a5fa8
AD
2121 {FILES => "*.xyz foo"}
2122
c07a80fd
PP
2123=item depend
2124
2125 {ANY_TARGET => ANY_DEPENDECY, ...}
2126
e35b8f9e
JH
2127(ANY_TARGET must not be given a double-colon rule by MakeMaker.)
2128
864a5fa8
AD
2129=item dist
2130
5f8e730b 2131 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
3b03c0f3 2132 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
f1387719 2133 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
864a5fa8
AD
2134
2135If you specify COMPRESS, then SUFFIX should also be altered, as it is
2136needed to tell make the target file of the compression. Setting
2137DIST_CP to ln can be useful, if you need to preserve the timestamps on
2138your files. DIST_CP can take the values 'cp', which copies the file,
2139'ln', which links the file, and 'best' which copies symbolic links and
2140links the rest. Default is 'best'.
2141
2142=item dynamic_lib
2143
0d8023a2 2144 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
8e07c86e 2145
8e07c86e
AD
2146=item linkext
2147
2148 {LINKTYPE => 'static', 'dynamic' or ''}
2149
864a5fa8 2150NB: Extensions that have nothing but *.pm files had to say
8e07c86e
AD
2151
2152 {LINKTYPE => ''}
2153
864a5fa8 2154with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
a7665c5e 2155can be deleted safely. MakeMaker recognizes when there's nothing to
864a5fa8 2156be linked.
8e07c86e 2157
864a5fa8 2158=item macro
8e07c86e 2159
864a5fa8 2160 {ANY_MACRO => ANY_VALUE, ...}
8e07c86e 2161
531e2ba1
JH
2162=item postamble
2163
2164Anything put here will be passed to MY::postamble() if you have one.
2165
8e07c86e
AD
2166=item realclean
2167
2168 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
2169
f2f614a6
GS
2170=item test
2171
2172 {TESTS => 't/*.t'}
2173
8e07c86e
AD
2174=item tool_autosplit
2175
f2f614a6 2176 {MAXLEN => 8}
005c1a0e
AD
2177
2178=back
2179
2180=head2 Overriding MakeMaker Methods
2181
2182If you cannot achieve the desired Makefile behaviour by specifying
2183attributes you may define private subroutines in the Makefile.PL.
e0678a30 2184Each subroutine returns the text it wishes to have written to
005c1a0e
AD
2185the Makefile. To override a section of the Makefile you can
2186either say:
2187
f6d6199c 2188 sub MY::c_o { "new literal text" }
005c1a0e
AD
2189
2190or you can edit the default by saying something like:
2191
e0678a30
MS
2192 package MY; # so that "SUPER" works right
2193 sub c_o {
f6d6199c
MS
2194 my $inherited = shift->SUPER::c_o(@_);
2195 $inherited =~ s/old text/new text/;
2196 $inherited;
2197 }
8e07c86e 2198
bdda3fbd
PJ
2199If you are running experiments with embedding perl as a library into
2200other applications, you might find MakeMaker is not sufficient. You'd
2201better have a look at ExtUtils::Embed which is a collection of utilities
2202for embedding.
005c1a0e
AD
2203
2204If you still need a different solution, try to develop another
bdda3fbd 2205subroutine that fits your needs and submit the diffs to
e0678a30 2206F<makemaker@perl.org>
005c1a0e 2207
e0678a30
MS
2208For a complete description of all MakeMaker methods see
2209L<ExtUtils::MM_Unix>.
3b03c0f3
PP
2210
2211Here is a simple example of how to add a new target to the generated
2212Makefile:
2213
2214 sub MY::postamble {
e0678a30 2215 return <<'MAKE_FRAG';
3b03c0f3 2216 $(MYEXTLIB): sdbm/Makefile
f6d6199c 2217 cd sdbm && $(MAKE) all
e0678a30
MS
2218
2219 MAKE_FRAG
3b03c0f3
PP
2220 }
2221
a884ca7c
MS
2222=head2 The End Of Cargo Cult Programming
2223
2224WriteMakefile() now does some basic sanity checks on its parameters to
2225protect against typos and malformatted values. This means some things
2226which happened to work in the past will now throw warnings and
2227possibly produce internal errors.
2228
2229Some of the most common mistakes:
2230
2231=over 2
2232
2233=item C<<MAN3PODS => ' '>>
2234
2235This is commonly used to supress the creation of man pages. MAN3PODS
2236takes a hash ref not a string, but the above worked by accident in old
2237versions of MakeMaker.
2238
2239The correct code is C<<MAN3PODS => { }>>.
2240
2241=back
2242
3b03c0f3 2243
f1387719
PP
2244=head2 Hintsfile support
2245
2246MakeMaker.pm uses the architecture specific information from
2247Config.pm. In addition it evaluates architecture specific hints files
2248in a C<hints/> directory. The hints files are expected to be named
2249like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
2250name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
2251MakeMaker within the WriteMakefile() subroutine, and can be used to
2252execute commands as well as to include special variables. The rules
2253which hintsfile is chosen are the same as in Configure.
2254
2255The hintsfile is eval()ed immediately after the arguments given to
2256WriteMakefile are stuffed into a hash reference $self but before this
2257reference becomes blessed. So if you want to do the equivalent to
2258override or create an attribute you would say something like
2259
2260 $self->{LIBS} = ['-ldbm -lucb -lc'];
2261
005c1a0e
AD
2262=head2 Distribution Support
2263
2264For authors of extensions MakeMaker provides several Makefile
2265targets. Most of the support comes from the ExtUtils::Manifest module,
2266where additional documentation can be found.
2267
2268=over 4
2269
2270=item make distcheck
8e07c86e 2271
005c1a0e
AD
2272reports which files are below the build directory but not in the
2273MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
2274details)
2275
4633a7c4
LW
2276=item make skipcheck
2277
2278reports which files are skipped due to the entries in the
2279C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
2280details)
2281
005c1a0e 2282=item make distclean
8e07c86e 2283
005c1a0e 2284does a realclean first and then the distcheck. Note that this is not
a7665c5e 2285needed to build a new distribution as long as you are sure that the
005c1a0e
AD
2286MANIFEST file is ok.
2287
2288=item make manifest
8e07c86e 2289
005c1a0e
AD
2290rewrites the MANIFEST file, adding all remaining files found (See
2291ExtUtils::Manifest::mkmanifest() for details)
2292
2293=item make distdir
8e07c86e 2294
005c1a0e
AD
2295Copies all the files that are in the MANIFEST file to a newly created
2296directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
2297exists, it will be removed first.
2298
1df8d179
MS
2299Additionally, it will create a META.yml module meta-data file and add
2300this to your MANFIEST. You can shut this behavior off with the NO_META
2301flag.
2302
f6d6199c 2303=item make disttest
8e07c86e
AD
2304
2305Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
4633a7c4 2306a make test in that directory.
8e07c86e 2307
005c1a0e 2308=item make tardist
8e07c86e 2309
3b03c0f3 2310First does a distdir. Then a command $(PREOP) which defaults to a null
f1387719
PP
2311command, followed by $(TOUNIX), which defaults to a null command under
2312UNIX, and will convert files in distribution directory to UNIX format
2313otherwise. Next it runs C<tar> on that directory into a tarfile and
3b03c0f3
PP
2314deletes the directory. Finishes with a command $(POSTOP) which
2315defaults to a null command.
005c1a0e
AD
2316
2317=item make dist
8e07c86e 2318
005c1a0e
AD
2319Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
2320
2321=item make uutardist
8e07c86e 2322
005c1a0e
AD
2323Runs a tardist first and uuencodes the tarfile.
2324
2325=item make shdist
8e07c86e 2326
3b03c0f3
PP
2327First does a distdir. Then a command $(PREOP) which defaults to a null
2328command. Next it runs C<shar> on that directory into a sharfile and
2329deletes the intermediate directory again. Finishes with a command
2330$(POSTOP) which defaults to a null command. Note: For shdist to work
2331properly a C<shar> program that can handle directories is mandatory.
2332
2333=item make zipdist
2334
2335First does a distdir. Then a command $(PREOP) which defaults to a null
2336command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
2337zipfile. Then deletes that directory. Finishes with a command
2338$(POSTOP) which defaults to a null command.
005c1a0e
AD
2339
2340=item make ci
8e07c86e
AD
2341
2342Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2343
2344=back
005c1a0e
AD
2345
2346Customization of the dist targets can be done by specifying a hash
2347reference to the dist attribute of the WriteMakefile call. The
2348following parameters are recognized:
2349
8e07c86e 2350 CI ('ci -u')
5f8e730b 2351 COMPRESS ('gzip --best')
005c1a0e 2352 POSTOP ('@ :')
8e07c86e 2353 PREOP ('@ :')
f1387719 2354 TO_UNIX (depends on the system)
8e07c86e
AD
2355 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
2356 SHAR ('shar')
5f8e730b 2357 SUFFIX ('.gz')
8e07c86e
AD
2358 TAR ('tar')
2359 TARFLAGS ('cvf')
3b03c0f3
PP
2360 ZIP ('zip')
2361 ZIPFLAGS ('-r')
005c1a0e
AD
2362
2363An example:
2364
5f8e730b 2365 WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
005c1a0e 2366
1df8d179
MS
2367
2368=head2 Module Meta-Data
2369
2370Long plaguing users of MakeMaker based modules has been the problem of
2371getting basic information about the module out of the sources
2372I<without> running the F<Makefile.PL> and doing a bunch of messy
2373heuristics on the resulting F<Makefile>. To this end a simple module
2374meta-data file has been introduced, F<META.yml>.
2375
2376F<META.yml> is a YAML document (see http://www.yaml.org) containing
2377basic information about the module (name, version, prerequisites...)
2378in an easy to read format. The format is developed and defined by the
64964e6d
JH
2379Module::Build developers (see
2380http://module-build.sourceforge.net/META-spec.html)
1df8d179
MS
2381
2382MakeMaker will automatically generate a F<META.yml> file for you and
2383add it to your F<MANIFEST> as part of the 'distdir' target (and thus
2384the 'dist' target). This is intended to seamlessly and rapidly
2385populate CPAN with module meta-data. If you wish to shut this feature
2386off, set the C<NO_META> C<WriteMakefile()> flag to true.
2387
2388
1b171b8d
NIS
2389=head2 Disabling an extension
2390
2391If some events detected in F<Makefile.PL> imply that there is no way
2392to create the Module, but this is a normal state of things, then you
2393can create a F<Makefile> which does nothing, but succeeds on all the
2394"usual" build targets. To do so, use
2395
2396 ExtUtils::MakeMaker::WriteEmptyMakefile();
2397
2398instead of WriteMakefile().
2399
2400This may be useful if other modules expect this module to be I<built>
2401OK, as opposed to I<work> OK (say, this system-dependent module builds
2402in a subdirectory of some other distribution, or is listed as a
2403dependency in a CPAN::Bundle, but the functionality is supported by
2404different means on the current architecture).
2405
479d2113
MS
2406=head2 Other Handy Functions
2407
2408=over 4
2409
2410=item prompt
2411
2412 my $value = prompt($message);
2413 my $value = prompt($message, $default);
2414
2415The C<prompt()> function provides an easy way to request user input
2416used to write a makefile. It displays the $message as a prompt for
2417input. If a $default is provided it will be used as a default. The
2418function returns the $value selected by the user.
2419
2420If C<prompt()> detects that it is not running interactively and there
2421is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
2422is set to true, the $default will be used without prompting. This
2423prevents automated processes from blocking on user input.
2424
2425If no $default is provided an empty string will be used instead.
2426
2427=back
2428
2429
6ce21ffa
GS
2430=head1 ENVIRONMENT
2431
479d2113 2432=over 4
6ce21ffa 2433
2443aee5 2434=item PERL_MM_OPT
6ce21ffa
GS
2435
2436Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2437C<WriteMakefile()>. The string is split on whitespace, and the result
2438is processed before any actual command line arguments are processed.
2439
9d05ba64
GA
2440=item PERL_MM_USE_DEFAULT
2441
2442If set to a true value then MakeMaker's prompt function will
2443always return the default without waiting for user input.
2444
6ce21ffa
GS
2445=back
2446
f1387719
PP
2447=head1 SEE ALSO
2448
f6d6199c
MS
2449ExtUtils::MM_Unix, ExtUtils::Manifest ExtUtils::Install,
2450ExtUtils::Embed
005c1a0e 2451
e05e23b1 2452=head1 AUTHORS
fed7345c 2453
e0678a30
MS
2454Andy Dougherty <F<doughera@lafayette.edu>>, Andreas KE<ouml>nig
2455<F<andreas.koenig@mind.de>>, Tim Bunce <F<timb@cpan.org>>. VMS
de90321e
MS
2456support by Charles Bailey <F<bailey@newman.upenn.edu>>. OS/2 support
2457by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>.
2458
f6d6199c
MS
2459Currently maintained by Michael G Schwern <F<schwern@pobox.com>>
2460
2461Send patches and ideas to <F<makemaker@perl.org>>.
e8012c20 2462
e0678a30
MS
2463Send bug reports via http://rt.cpan.org/. Please send your
2464generated Makefile along with your report.
2465
2466For more up-to-date information, see http://www.makemaker.org.
fed7345c 2467
479d2113
MS
2468=head1 LICENSE
2469
2470This program is free software; you can redistribute it and/or
2471modify it under the same terms as Perl itself.
2472
2473See F<http://www.perl.com/perl/misc/Artistic.html>
2474
2475
005c1a0e 2476=cut