X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FExtUtils%2FMakeMaker%2FFAQ.pod;h=f733cb8c1a19eb760dbe4e21782f74804b09db8e;hb=277189c8ad3fc0d1dcd4c757f62b0a7bf5bacaa0;hp=ca9d53fc6137ca9169d23ffc5369e4163d6d69b1;hpb=c2990482fb4d986615c32035b6b49c5a9a91336d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/ExtUtils/MakeMaker/FAQ.pod b/lib/ExtUtils/MakeMaker/FAQ.pod index ca9d53f..f733cb8 100644 --- a/lib/ExtUtils/MakeMaker/FAQ.pod +++ b/lib/ExtUtils/MakeMaker/FAQ.pod @@ -1,6 +1,7 @@ package ExtUtils::MakeMaker::FAQ; -(our $VERSION) = sprintf "%03d", q$Revision: 1.7 $ =~ /Revision:\s+(\S+)/; +use vars qw($VERSION); +$VERSION = '1.12'; 1; __END__ @@ -13,6 +14,113 @@ ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker FAQs, tricks and tips for C. + +=head2 Module Installation + +=over 4 + +=item How do I install a module into my home directory? + +If you're not the Perl administrator you probably don't have +permission to install a module to its default location. Then you +should install it for your own use into your home directory like so: + + # Non-unix folks, replace ~ with /path/to/your/home/dir + perl Makefile.PL INSTALL_BASE=~ + +This will put modules into F<~/lib/perl5>, man pages into F<~/man> and +programs into F<~/bin>. + +To ensure your Perl programs can see these newly installed modules, +set your C environment variable to F<~/lib/perl5> or tell +each of your programs to look in that directory with the following: + + use lib "$ENV{HOME}/lib/perl5"; + +or if $ENV{HOME} isn't set and you don't want to set it for some +reason, do it the long way. + + use lib "/path/to/your/home/dir/lib/perl5"; + + +=item How do I get MakeMaker and Module::Build to install to the same place? + +Module::Build, as of 0.28, supports two ways to install to the same +location as MakeMaker. + +1) Use INSTALL_BASE / C<--install_base> + +MakeMaker (as of 6.31) and Module::Build (as of 0.28) both can install +to the same locations using the "install_base" concept. See +L for details. To get MM and MB to +install to the same location simply set INSTALL_BASE in MM and +C<--install_base> in MB to the same location. + + perl Makefile.PL INSTALL_BASE=/whatever + perl Build.PL --install_base /whatever + +2) Use PREFIX / C<--prefix> + +Module::Build 0.28 added support for C<--prefix> which works like +MakeMaker's PREFIX. + + perl Makefile.PL PREFIX=/whatever + perl Build.PL --prefix /whatever + + +=item How do I keep from installing man pages? + +Recent versions of MakeMaker will only install man pages on Unix like +operating systems. + +For an individual module: + + perl Makefile.PL INSTALLMAN1DIR=none INSTALLMAN3DIR=none + +If you want to suppress man page installation for all modules you have +to reconfigure Perl and tell it 'none' when it asks where to install +man pages. + + +=item How do I use a module without installing it? + +Two ways. One is to build the module normally... + + perl Makefile.PL + make + make test + +...and then set the PERL5LIB environment variable to point at the +blib/lib and blib/arch directories. + +The other is to install the module in a temporary location. + + perl Makefile.PL INSTALL_BASE=~/tmp + make + make test + make install + +And then set PERL5LIB to F<~/tmp/lib/perl5>. This works well when you +have multiple modules to work with. It also ensures that the module +goes through its full installation process which may modify it. + +=item PREFIX vs INSTALL_BASE from Module::Build::Cookbook + +The behavior of PREFIX is complicated and depends closely on how your +Perl is configured. The resulting installation locations will vary from +machine to machine and even different installations of Perl on the same machine. +Because of this, its difficult to document where prefix will place your modules. + +In contrast, INSTALL_BASE has predictable, easy to explain installation locations. +Now that Module::Build and MakeMaker both have INSTALL_BASE there is little reason +to use PREFIX other than to preserve your existing installation locations. If you +are starting a fresh Perl installation we encourage you to use INSTALL_BASE. If +you have an existing installation installed via PREFIX, consider moving it to an +installation structure matching INSTALL_BASE and using that instead. + +=back + + =head2 Philosophy and History =over 4 @@ -28,13 +136,13 @@ compatibility. Perl is one of the most ported pieces of software ever. It works on operating systems I've never even heard of (see perlport for details). It needs a build tool that can work on all those platforms and with -any wacky C compilers they might have. +any wacky C compilers and linkers they might have. -No such build tool existed at the time and I only know of one now -(Module::Build). +No such build tool exists. Even make itself has wildly different +dialects. So we have to build our own. -=item What's Module::Build and how does it relate to MakeMaker? +=item What is Module::Build and how does it relate to MakeMaker? Module::Build is a project by Ken Williams to supplant MakeMaker. Its primary advantages are: @@ -52,11 +160,12 @@ Its primary advantages are: =back Module::Build is the official heir apparent to MakeMaker and we -encourage people to work on M::B rather than spending time improving -MakeMaker. +encourage people to work on M::B rather than spending time adding features +to MakeMaker. =back + =head2 Module Writing =over 4 @@ -73,28 +182,36 @@ by hand is a pain and you often forget. Simplest way to do it automatically is to use your version control system's revision number (you are using version control, right?). -In CVS and RCS you use $Z<>Revision$ writing it like so: +In CVS, RCS and SVN you use $Revision$ (see the documentation of your +version control system for details). Every time the file is checked +in the $Revision$ will be updated, updating your $VERSION. - $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)/g; +SVN uses a simple integer for $Revision$ so you can adapt it for your +$VERSION like so: -On your next check in, $Z<>Revision$ will magically be expanded to contain -the current revision #. + ($VERSION) = q$Revision$ =~ /(\d+)/; - $VERSION = sprintf "%d.%03d", q$Revision: 1.7 $ =~ /(\d+)/g; +In CVS and RCS version 1.9 is followed by 1.10. Since CPAN compares +version numbers numerically we use a sprintf() to convert 1.9 to 1.009 +and 1.10 to 1.010 which compare properly. -Every time the file is checked in the $Z<>Revision$ will be updated, -updating your $VERSION. + $VERSION = sprintf "%d.%03d", q$Revision$ =~ /(\d+)\.(\d+)/g; -In CVS version 1.9 is followed by 1.10. Since CPAN compares version -numbers numerically we use a sprintf() to convert 1.9 to 1.009 and -1.10 to 1.010 which compare properly. - -If branches are involved (ie. $Z<>Revision: 1.5.3.4) its a little more +If branches are involved (ie. $Revision: 1.5.3.4$) its a little more complicated. # must be all on one line or MakeMaker will get confused. $VERSION = do { my @r = (q$Revision$ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r }; +In SVN, $Revision$ should be the same for every file in the project so +they would all have the same $VERSION. CVS and RCS have a different +$Revision$ per file so each file will have a differnt $VERSION. +Distributed version control systems, such as SVK, may have a different +$Revision$ based on who checks out the file leading to a different $VERSION +on each machine! Finally, some distributed version control systems, such +as darcs, have no concept of revision number at all. + + =item What's this F thing and how did it get in my F?! F is a module meta-data file pioneered by Module::Build and @@ -103,6 +220,54 @@ automatically generated as part of the 'distdir' target (and thus To shut off its generation, pass the C flag to C. + +=item How do I delete everything not in my F? + +Some folks are surpried that C does not delete +everything not listed in their MANIFEST (thus making a clean +distribution) but only tells them what they need to delete. This is +done because it is considered too dangerous. While developing your +module you might write a new file, not add it to the MANIFEST, then +run a C and be sad because your new work was deleted. + +If you really want to do this, you can use +C to read the MANIFEST and File::Find +to delete the files. But you have to be careful. Here's a script to +do that. Use at your own risk. Have fun blowing holes in your foot. + + #!/usr/bin/perl -w + + use strict; + + use File::Spec; + use File::Find; + use ExtUtils::Manifest qw(maniread); + + my %manifest = map {( $_ => 1 )} + grep { File::Spec->canonpath($_) } + keys %{ maniread() }; + + if( !keys %manifest ) { + print "No files found in MANIFEST. Stopping.\n"; + exit; + } + + find({ + wanted => sub { + my $path = File::Spec->canonpath($_); + + return unless -f $path; + return if exists $manifest{ $path }; + + print "unlink $path\n"; + unlink $path; + }, + no_chdir => 1 + }, + "." + ); + + =back =head2 XS @@ -113,7 +278,7 @@ To shut off its generation, pass the C flag to C. XS code is very sensitive to the module version number and will complain if the version number in your Perl module doesn't match. If -you change your module's version # without reruning Makefile.PL the old +you change your module's version # without rerunning Makefile.PL the old version number will remain in the Makefile causing the XS code to be built with the wrong number. @@ -232,7 +397,7 @@ The following four files sum up all the details discussed so far. And of course a very basic test: - test.pl: + t/cool.t: -------- use Test; BEGIN { plan tests => 1 };