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