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=6d17ff5d670001d8f3f2324083707a9cd3968fbf;hpb=2977d345acaba2d25f549b813e6f840a0d225b16;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/ExtUtils/MakeMaker/FAQ.pod b/lib/ExtUtils/MakeMaker/FAQ.pod index 6d17ff5..f733cb8 100644 --- a/lib/ExtUtils/MakeMaker/FAQ.pod +++ b/lib/ExtUtils/MakeMaker/FAQ.pod @@ -1,7 +1,7 @@ package ExtUtils::MakeMaker::FAQ; use vars qw($VERSION); -$VERSION = '1.11_01'; +$VERSION = '1.12'; 1; __END__ @@ -19,6 +19,55 @@ FAQs, tricks and tips for C. =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 @@ -39,17 +88,35 @@ 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 PREFIX=~/tmp LIB=~/tmp/lib/perl + 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. -And then set PERL5LIB to F<~/tmp/lib/perl>. 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. +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 @@ -122,7 +189,7 @@ in the $Revision$ will be updated, updating your $VERSION. SVN uses a simple integer for $Revision$ so you can adapt it for your $VERSION like so: - $VERSION = (q$Revision$) =~ /(\d+)/g; + ($VERSION) = q$Revision$ =~ /(\d+)/; 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 @@ -153,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 @@ -282,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 };