1package ExtUtils::MakeMaker::FAQ; 2 3our $VERSION = '7.34'; 4$VERSION = eval $VERSION; 5 61; 7__END__ 8 9=head1 NAME 10 11ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker 12 13=head1 DESCRIPTION 14 15FAQs, tricks and tips for C<ExtUtils::MakeMaker>. 16 17 18=head2 Module Installation 19 20=over 4 21 22=item How do I install a module into my home directory? 23 24If you're not the Perl administrator you probably don't have 25permission to install a module to its default location. Ways of handling 26this with a B<lot> less manual effort on your part are L<perlbrew> 27and L<local::lib>. 28 29Otherwise, you can install it for your own use into your home directory 30like so: 31 32 # Non-unix folks, replace ~ with /path/to/your/home/dir 33 perl Makefile.PL INSTALL_BASE=~ 34 35This will put modules into F<~/lib/perl5>, man pages into F<~/man> and 36programs into F<~/bin>. 37 38To ensure your Perl programs can see these newly installed modules, 39set your C<PERL5LIB> environment variable to F<~/lib/perl5> or tell 40each of your programs to look in that directory with the following: 41 42 use lib "$ENV{HOME}/lib/perl5"; 43 44or if $ENV{HOME} isn't set and you don't want to set it for some 45reason, do it the long way. 46 47 use lib "/path/to/your/home/dir/lib/perl5"; 48 49=item How do I get MakeMaker and Module::Build to install to the same place? 50 51Module::Build, as of 0.28, supports two ways to install to the same 52location as MakeMaker. 53 54We highly recommend the install_base method, its the simplest and most 55closely approximates the expected behavior of an installation prefix. 56 571) Use INSTALL_BASE / C<--install_base> 58 59MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install 60to the same locations using the "install_base" concept. See 61L<ExtUtils::MakeMaker/INSTALL_BASE> for details. To get MM and MB to 62install to the same location simply set INSTALL_BASE in MM and 63C<--install_base> in MB to the same location. 64 65 perl Makefile.PL INSTALL_BASE=/whatever 66 perl Build.PL --install_base /whatever 67 68This works most like other language's behavior when you specify a 69prefix. We recommend this method. 70 712) Use PREFIX / C<--prefix> 72 73Module::Build 0.28 added support for C<--prefix> which works like 74MakeMaker's PREFIX. 75 76 perl Makefile.PL PREFIX=/whatever 77 perl Build.PL --prefix /whatever 78 79We highly discourage this method. It should only be used if you know 80what you're doing and specifically need the PREFIX behavior. The 81PREFIX algorithm is complicated and focused on matching the system 82installation. 83 84=item How do I keep from installing man pages? 85 86Recent versions of MakeMaker will only install man pages on Unix-like 87operating systems. 88 89For an individual module: 90 91 perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none 92 93If you want to suppress man page installation for all modules you have 94to reconfigure Perl and tell it 'none' when it asks where to install 95man pages. 96 97 98=item How do I use a module without installing it? 99 100Two ways. One is to build the module normally... 101 102 perl Makefile.PL 103 make 104 make test 105 106...and then use L<blib> to point Perl at the built but uninstalled module: 107 108 perl -Mblib script.pl 109 perl -Mblib -e '...' 110 111The other is to install the module in a temporary location. 112 113 perl Makefile.PL INSTALL_BASE=~/tmp 114 make 115 make test 116 make install 117 118And then set PERL5LIB to F<~/tmp/lib/perl5>. This works well when you 119have multiple modules to work with. It also ensures that the module 120goes through its full installation process which may modify it. 121Again, L<local::lib> may assist you here. 122 123=item How can I organize tests into subdirectories and have them run? 124 125Let's take the following test directory structure: 126 127 t/foo/sometest.t 128 t/bar/othertest.t 129 t/bar/baz/anothertest.t 130 131Now, inside of the C<WriteMakeFile()> function in your F<Makefile.PL>, specify 132where your tests are located with the C<test> directive: 133 134 test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'} 135 136The first entry in the string will run all tests in the top-level F<t/> 137directory. The second will run all test files located in any subdirectory under 138F<t/>. The third, runs all test files within any subdirectory within any other 139subdirectory located under F<t/>. 140 141Note that you do not have to use wildcards. You can specify explicitly which 142subdirectories to run tests in: 143 144 test => {TESTS => 't/*.t t/foo/*.t t/bar/baz/*.t'} 145 146=item PREFIX vs INSTALL_BASE from Module::Build::Cookbook 147 148The behavior of PREFIX is complicated and depends closely on how your 149Perl is configured. The resulting installation locations will vary 150from machine to machine and even different installations of Perl on the 151same machine. Because of this, its difficult to document where prefix 152will place your modules. 153 154In contrast, INSTALL_BASE has predictable, easy to explain installation 155locations. Now that Module::Build and MakeMaker both have INSTALL_BASE 156there is little reason to use PREFIX other than to preserve your existing 157installation locations. If you are starting a fresh Perl installation we 158encourage you to use INSTALL_BASE. If you have an existing installation 159installed via PREFIX, consider moving it to an installation structure 160matching INSTALL_BASE and using that instead. 161 162=item Generating *.pm files with substitutions eg of $VERSION 163 164If you want to configure your module files for local conditions, or to 165automatically insert a version number, you can use EUMM's C<PL_FILES> 166capability, where it will automatically run each F<*.PL> it finds to 167generate its basename. For instance: 168 169 # Makefile.PL: 170 require 'common.pl'; 171 my $version = get_version(); 172 my @pms = qw(Foo.pm); 173 WriteMakefile( 174 NAME => 'Foo', 175 VERSION => $version, 176 PM => { map { ($_ => "\$(INST_LIB)/$_") } @pms }, 177 clean => { FILES => join ' ', @pms }, 178 ); 179 180 # common.pl: 181 sub get_version { '0.04' } 182 sub process { my $v = get_version(); s/__VERSION__/$v/g; } 183 1; 184 185 # Foo.pm.PL: 186 require 'common.pl'; 187 $_ = join '', <DATA>; 188 process(); 189 my $file = shift; 190 open my $fh, '>', $file or die "$file: $!"; 191 print $fh $_; 192 __DATA__ 193 package Foo; 194 our $VERSION = '__VERSION__'; 195 1; 196 197You may notice that C<PL_FILES> is not specified above, since the default 198of mapping each .PL file to its basename works well. 199 200If the generated module were architecture-specific, you could replace 201C<$(INST_LIB)> above with C<$(INST_ARCHLIB)>, although if you locate 202modules under F<lib>, that would involve ensuring any C<lib/> in front 203of the module location were removed. 204 205=back 206 207=head2 Common errors and problems 208 209=over 4 210 211=item "No rule to make target `/usr/lib/perl5/CORE/config.h', needed by `Makefile'" 212 213Just what it says, you're missing that file. MakeMaker uses it to 214determine if perl has been rebuilt since the Makefile was made. It's 215a bit of a bug that it halts installation. 216 217Some operating systems don't ship the CORE directory with their base 218perl install. To solve the problem, you likely need to install a perl 219development package such as perl-devel (CentOS, Fedora and other 220Redhat systems) or perl (Ubuntu and other Debian systems). 221 222=back 223 224=head2 Philosophy and History 225 226=over 4 227 228=item Why not just use <insert other build config tool here>? 229 230Why did MakeMaker reinvent the build configuration wheel? Why not 231just use autoconf or automake or ppm or Ant or ... 232 233There are many reasons, but the major one is cross-platform 234compatibility. 235 236Perl is one of the most ported pieces of software ever. It works on 237operating systems I've never even heard of (see perlport for details). 238It needs a build tool that can work on all those platforms and with 239any wacky C compilers and linkers they might have. 240 241No such build tool exists. Even make itself has wildly different 242dialects. So we have to build our own. 243 244 245=item What is Module::Build and how does it relate to MakeMaker? 246 247Module::Build is a project by Ken Williams to supplant MakeMaker. 248Its primary advantages are: 249 250=over 8 251 252=item * pure perl. no make, no shell commands 253 254=item * easier to customize 255 256=item * cleaner internals 257 258=item * less cruft 259 260=back 261 262Module::Build was long the official heir apparent to MakeMaker. The 263rate of both its development and adoption has slowed in recent years, 264though, and it is unclear what the future holds for it. That said, 265Module::Build set the stage for I<something> to become the heir to 266MakeMaker. MakeMaker's maintainers have long said that it is a dead 267end and should be kept functioning, while being cautious about extending 268with new features. 269 270=back 271 272=head2 Module Writing 273 274=over 4 275 276=item How do I keep my $VERSION up to date without resetting it manually? 277 278Often you want to manually set the $VERSION in the main module 279distribution because this is the version that everybody sees on CPAN 280and maybe you want to customize it a bit. But for all the other 281modules in your dist, $VERSION is really just bookkeeping and all that's 282important is it goes up every time the module is changed. Doing this 283by hand is a pain and you often forget. 284 285Probably the easiest way to do this is using F<perl-reversion> in 286L<Perl::Version>: 287 288 perl-reversion -bump 289 290If your version control system supports revision numbers (git doesn't 291easily), the simplest way to do it automatically is to use its revision 292number (you are using version control, right?). 293 294In CVS, RCS and SVN you use $Revision$ (see the documentation of your 295version control system for details). Every time the file is checked 296in the $Revision$ will be updated, updating your $VERSION. 297 298SVN uses a simple integer for $Revision$ so you can adapt it for your 299$VERSION like so: 300 301 ($VERSION) = q$Revision$ =~ /(\d+)/; 302 303In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares 304version numbers numerically we use a sprintf() to convert 1.9 to 1.009 305and 1.10 to 1.010 which compare properly. 306 307 $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g; 308 309If branches are involved (ie. $Revision: 1.5.3.4$) it's a little more 310complicated. 311 312 # must be all on one line or MakeMaker will get confused. 313 $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r }; 314 315In SVN, $Revision$ should be the same for every file in the project so 316they would all have the same $VERSION. CVS and RCS have a different 317$Revision$ per file so each file will have a different $VERSION. 318Distributed version control systems, such as SVK, may have a different 319$Revision$ based on who checks out the file, leading to a different $VERSION 320on each machine! Finally, some distributed version control systems, such 321as darcs, have no concept of revision number at all. 322 323 324=item What's this F<META.yml> thing and how did it get in my F<MANIFEST>?! 325 326F<META.yml> is a module meta-data file pioneered by Module::Build and 327automatically generated as part of the 'distdir' target (and thus 328'dist'). See L<ExtUtils::MakeMaker/"Module Meta-Data">. 329 330To shut off its generation, pass the C<NO_META> flag to C<WriteMakefile()>. 331 332 333=item How do I delete everything not in my F<MANIFEST>? 334 335Some folks are surprised that C<make distclean> does not delete 336everything not listed in their MANIFEST (thus making a clean 337distribution) but only tells them what they need to delete. This is 338done because it is considered too dangerous. While developing your 339module you might write a new file, not add it to the MANIFEST, then 340run a C<distclean> and be sad because your new work was deleted. 341 342If you really want to do this, you can use 343C<ExtUtils::Manifest::manifind()> to read the MANIFEST and File::Find 344to delete the files. But you have to be careful. Here's a script to 345do that. Use at your own risk. Have fun blowing holes in your foot. 346 347 #!/usr/bin/perl -w 348 349 use strict; 350 351 use File::Spec; 352 use File::Find; 353 use ExtUtils::Manifest qw(maniread); 354 355 my %manifest = map {( $_ => 1 )} 356 grep { File::Spec->canonpath($_) } 357 keys %{ maniread() }; 358 359 if( !keys %manifest ) { 360 print "No files found in MANIFEST. Stopping.\n"; 361 exit; 362 } 363 364 find({ 365 wanted => sub { 366 my $path = File::Spec->canonpath($_); 367 368 return unless -f $path; 369 return if exists $manifest{ $path }; 370 371 print "unlink $path\n"; 372 unlink $path; 373 }, 374 no_chdir => 1 375 }, 376 "." 377 ); 378 379 380=item Which tar should I use on Windows? 381 382We recommend ptar from Archive::Tar not older than 1.66 with '-C' option. 383 384=item Which zip should I use on Windows for '[ndg]make zipdist'? 385 386We recommend InfoZIP: L<http://www.info-zip.org/Zip.html> 387 388 389=back 390 391=head2 XS 392 393=over 4 394 395=item How do I prevent "object version X.XX does not match bootstrap parameter Y.YY" errors? 396 397XS code is very sensitive to the module version number and will 398complain if the version number in your Perl module doesn't match. If 399you change your module's version # without rerunning Makefile.PL the old 400version number will remain in the Makefile, causing the XS code to be built 401with the wrong number. 402 403To avoid this, you can force the Makefile to be rebuilt whenever you 404change the module containing the version number by adding this to your 405WriteMakefile() arguments. 406 407 depend => { '$(FIRST_MAKEFILE)' => '$(VERSION_FROM)' } 408 409 410=item How do I make two or more XS files coexist in the same directory? 411 412Sometimes you need to have two and more XS files in the same package. 413There are three ways: C<XSMULTI>, separate directories, and bootstrapping 414one XS from another. 415 416=over 8 417 418=item XSMULTI 419 420Structure your modules so they are all located under F<lib>, such that 421C<Foo::Bar> is in F<lib/Foo/Bar.pm> and F<lib/Foo/Bar.xs>, etc. Have your 422top-level C<WriteMakefile> set the variable C<XSMULTI> to a true value. 423 424Er, that's it. 425 426=item Separate directories 427 428Put each XS files into separate directories, each with their own 429F<Makefile.PL>. Make sure each of those F<Makefile.PL>s has the correct 430C<CFLAGS>, C<INC>, C<LIBS> etc. You will need to make sure the top-level 431F<Makefile.PL> refers to each of these using C<DIR>. 432 433=item Bootstrapping 434 435Let's assume that we have a package C<Cool::Foo>, which includes 436C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS 437file. First we use the following I<Makefile.PL>: 438 439 use ExtUtils::MakeMaker; 440 441 WriteMakefile( 442 NAME => 'Cool::Foo', 443 VERSION_FROM => 'Foo.pm', 444 OBJECT => q/$(O_FILES)/, 445 # ... other attrs ... 446 ); 447 448Notice the C<OBJECT> attribute. MakeMaker generates the following 449variables in I<Makefile>: 450 451 # Handy lists of source code files: 452 XS_FILES= Bar.xs \ 453 Foo.xs 454 C_FILES = Bar.c \ 455 Foo.c 456 O_FILES = Bar.o \ 457 Foo.o 458 459Therefore we can use the C<O_FILES> variable to tell MakeMaker to use 460these objects into the shared library. 461 462That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm> 463and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and 464I<Bar.pm> simply loading I<Foo.pm>. 465 466The only issue left is to how to bootstrap I<Bar.xs>. This is done 467from I<Foo.xs>: 468 469 MODULE = Cool::Foo PACKAGE = Cool::Foo 470 471 BOOT: 472 # boot the second XS file 473 boot_Cool__Bar(aTHX_ cv); 474 475If you have more than two files, this is the place where you should 476boot extra XS files from. 477 478The following four files sum up all the details discussed so far. 479 480 Foo.pm: 481 ------- 482 package Cool::Foo; 483 484 require DynaLoader; 485 486 our @ISA = qw(DynaLoader); 487 our $VERSION = '0.01'; 488 bootstrap Cool::Foo $VERSION; 489 490 1; 491 492 Bar.pm: 493 ------- 494 package Cool::Bar; 495 496 use Cool::Foo; # bootstraps Bar.xs 497 498 1; 499 500 Foo.xs: 501 ------- 502 #include "EXTERN.h" 503 #include "perl.h" 504 #include "XSUB.h" 505 506 MODULE = Cool::Foo PACKAGE = Cool::Foo 507 508 BOOT: 509 # boot the second XS file 510 boot_Cool__Bar(aTHX_ cv); 511 512 MODULE = Cool::Foo PACKAGE = Cool::Foo PREFIX = cool_foo_ 513 514 void 515 cool_foo_perl_rules() 516 517 CODE: 518 fprintf(stderr, "Cool::Foo says: Perl Rules\n"); 519 520 Bar.xs: 521 ------- 522 #include "EXTERN.h" 523 #include "perl.h" 524 #include "XSUB.h" 525 526 MODULE = Cool::Bar PACKAGE = Cool::Bar PREFIX = cool_bar_ 527 528 void 529 cool_bar_perl_rules() 530 531 CODE: 532 fprintf(stderr, "Cool::Bar says: Perl Rules\n"); 533 534And of course a very basic test: 535 536 t/cool.t: 537 -------- 538 use Test; 539 BEGIN { plan tests => 1 }; 540 use Cool::Foo; 541 use Cool::Bar; 542 Cool::Foo::perl_rules(); 543 Cool::Bar::perl_rules(); 544 ok 1; 545 546This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. 547 548An alternative way to achieve this can be seen in L<Gtk2::CodeGen> 549and L<Glib::CodeGen>. 550 551=back 552 553=back 554 555=head1 DESIGN 556 557=head2 MakeMaker object hierarchy (simplified) 558 559What most people need to know (superclasses on top.) 560 561 ExtUtils::MM_Any 562 | 563 ExtUtils::MM_Unix 564 | 565 ExtUtils::MM_{Current OS} 566 | 567 ExtUtils::MakeMaker 568 | 569 MY 570 571The object actually used is of the class MY which allows you to 572override bits of MakeMaker inside your Makefile.PL by declaring 573MY::foo() methods. 574 575=head2 MakeMaker object hierarchy (real) 576 577Here's how it really works: 578 579 ExtUtils::MM_Any 580 | 581 ExtUtils::MM_Unix 582 | 583 ExtUtils::Liblist::Kid ExtUtils::MM_{Current OS} (if necessary) 584 | | 585 ExtUtils::Liblist ExtUtils::MakeMaker | 586 | | | 587 | | |----------------------- 588 ExtUtils::MM 589 | | 590 ExtUtils::MY MM (created by ExtUtils::MM) 591 | | 592 MY (created by ExtUtils::MY) | 593 . | 594 (mixin) | 595 . | 596 PACK### (created each call to ExtUtils::MakeMaker->new) 597 598NOTE: Yes, this is a mess. See 599L<http://archive.develooper.com/makemaker@perl.org/msg00134.html> 600for some history. 601 602NOTE: When ExtUtils::MM is loaded it chooses a superclass for MM from 603amongst the ExtUtils::MM_* modules based on the current operating 604system. 605 606NOTE: ExtUtils::MM_{Current OS} represents one of the ExtUtils::MM_* 607modules except ExtUtils::MM_Any chosen based on your operating system. 608 609NOTE: The main object used by MakeMaker is a PACK### object, *not* 610ExtUtils::MakeMaker. It is, effectively, a subclass of MY, 611ExtUtils::Makemaker, ExtUtils::Liblist and ExtUtils::MM_{Current OS} 612 613NOTE: The methods in MY are simply copied into PACK### rather than 614MY being a superclass of PACK###. I don't remember the rationale. 615 616NOTE: ExtUtils::Liblist should be removed from the inheritance hiearchy 617and simply be called as functions. 618 619NOTE: Modules like File::Spec and Exporter have been omitted for clarity. 620 621 622=head2 The MM_* hierarchy 623 624 MM_Win95 MM_NW5 625 \ / 626 MM_BeOS MM_Cygwin MM_OS2 MM_VMS MM_Win32 MM_DOS MM_UWIN 627 \ | | | / / / 628 ------------------------------------------------ 629 | | 630 MM_Unix | 631 | | 632 MM_Any 633 634NOTE: Each direct MM_Unix subclass is also an MM_Any subclass. This 635is a temporary hack because MM_Unix overrides some MM_Any methods with 636Unix specific code. It allows the non-Unix modules to see the 637original MM_Any implementations. 638 639NOTE: Modules like File::Spec and Exporter have been omitted for clarity. 640 641=head1 PATCHING 642 643If you have a question you'd like to see added to the FAQ (whether or 644not you have the answer) please either: 645 646=over 2 647 648=item * make a pull request on the MakeMaker github repository 649 650=item * raise a issue on the MakeMaker github repository 651 652=item * file an RT ticket 653 654=item * email makemaker@perl.org 655 656=back 657 658=head1 AUTHOR 659 660The denizens of makemaker@perl.org. 661 662=head1 SEE ALSO 663 664L<ExtUtils::MakeMaker> 665 666=cut 667