X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/d10894c88dd9594f894165e862889054b81758bd..b7da5e65d666d7b7c1eace2dff55ff1d323fa0da:/cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker/FAQ.pod?ds=sidebyside diff --git a/cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker/FAQ.pod b/cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker/FAQ.pod index 1b863cc..a82c53b 100644 --- a/cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker/FAQ.pod +++ b/cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker/FAQ.pod @@ -1,6 +1,7 @@ package ExtUtils::MakeMaker::FAQ; -our $VERSION = '6.72'; +our $VERSION = '7.44'; +$VERSION =~ tr/_//d; 1; __END__ @@ -11,7 +12,7 @@ ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker =head1 DESCRIPTION -FAQs, tricks and tips for C. +FAQs, tricks and tips for L. =head2 Module Installation @@ -21,8 +22,12 @@ FAQs, tricks and tips for C. =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: +permission to install a module to its default location. Ways of handling +this with a B less manual effort on your part are L +and L. + +Otherwise, you can 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=~ @@ -41,7 +46,6 @@ 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 @@ -80,7 +84,8 @@ installation. =item How do I keep from installing man pages? Recent versions of MakeMaker will only install man pages on Unix-like -operating systems. +operating systems by default. To generate manpages on non-Unix operating +systems, make the "manifypods" target. For an individual module: @@ -99,8 +104,10 @@ Two ways. One is to build the module normally... make make test -...and then set the PERL5LIB environment variable to point at the -blib/lib and blib/arch directories. +...and then use L to point Perl at the built but uninstalled module: + + perl -Mblib script.pl + perl -Mblib -e '...' The other is to install the module in a temporary location. @@ -112,20 +119,89 @@ The other is to install the module in a temporary location. 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. +Again, L may assist you here. + +=item How can I organize tests into subdirectories and have them run? + +Let's take the following test directory structure: + + t/foo/sometest.t + t/bar/othertest.t + t/bar/baz/anothertest.t + +Now, inside of the C function in your F, specify +where your tests are located with the C directive: + + test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'} + +The first entry in the string will run all tests in the top-level F +directory. The second will run all test files located in any subdirectory under +F. The third, runs all test files within any subdirectory within any other +subdirectory located under F. + +Note that you do not have to use wildcards. You can specify explicitly which +subdirectories to run tests in: + + test => {TESTS => 't/*.t t/foo/*.t t/bar/baz/*.t'} =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. +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. + +=item Generating *.pm files with substitutions eg of $VERSION + +If you want to configure your module files for local conditions, or to +automatically insert a version number, you can use EUMM's C +capability, where it will automatically run each F<*.PL> it finds to +generate its basename. For instance: + + # Makefile.PL: + require 'common.pl'; + my $version = get_version(); + my @pms = qw(Foo.pm); + WriteMakefile( + NAME => 'Foo', + VERSION => $version, + PM => { map { ($_ => "\$(INST_LIB)/$_") } @pms }, + clean => { FILES => join ' ', @pms }, + ); -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. + # common.pl: + sub get_version { '0.04' } + sub process { my $v = get_version(); s/__VERSION__/$v/g; } + 1; + + # Foo.pm.PL: + require 'common.pl'; + $_ = join '', ; + process(); + my $file = shift; + open my $fh, '>', $file or die "$file: $!"; + print $fh $_; + __DATA__ + package Foo; + our $VERSION = '__VERSION__'; + 1; + +You may notice that C is not specified above, since the default +of mapping each .PL file to its basename works well. + +If the generated module were architecture-specific, you could replace +C<$(INST_LIB)> above with C<$(INST_ARCHLIB)>, although if you locate +modules under F, that would involve ensuring any C in front +of the module location were removed. =back @@ -184,13 +260,16 @@ 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 adding features -to MakeMaker. +Module::Build was long the official heir apparent to MakeMaker. The +rate of both its development and adoption has slowed in recent years, +though, and it is unclear what the future holds for it. That said, +Module::Build set the stage for I to become the heir to +MakeMaker. MakeMaker's maintainers have long said that it is a dead +end and should be kept functioning, while being cautious about extending +with new features. =back - =head2 Module Writing =over 4 @@ -204,8 +283,14 @@ modules in your dist, $VERSION is really just bookkeeping and all that's important is it goes up every time the module is changed. Doing this 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?). +Probably the easiest way to do this is using F in +L: + + perl-reversion -bump + +If your version control system supports revision numbers (git doesn't +easily), the simplest way to do it automatically is to use its revision +number (you are using version control, right?). In CVS, RCS and SVN you use $Revision$ (see the documentation of your version control system for details). Every time the file is checked @@ -297,7 +382,7 @@ do that. Use at your own risk. Have fun blowing holes in your foot. We recommend ptar from Archive::Tar not older than 1.66 with '-C' option. -=item Which zip should I use on Windows for '[nd]make zipdist'? +=item Which zip should I use on Windows for '[ndg]make zipdist'? We recommend InfoZIP: L @@ -326,9 +411,27 @@ WriteMakefile() arguments. =item How do I make two or more XS files coexist in the same directory? Sometimes you need to have two and more XS files in the same package. -One way to go is to put them into separate directories, but sometimes -this is not the most suitable solution. The following technique allows -you to put two (and more) XS files in the same directory. +There are three ways: C, separate directories, and bootstrapping +one XS from another. + +=over 8 + +=item XSMULTI + +Structure your modules so they are all located under F, such that +C is in F and F, etc. Have your +top-level C set the variable C to a true value. + +Er, that's it. + +=item Separate directories + +Put each XS files into separate directories, each with their own +F. Make sure each of those Fs has the correct +C, C, C etc. You will need to make sure the top-level +F refers to each of these using C. + +=item Bootstrapping Let's assume that we have a package C, which includes C and C modules each having a separate XS @@ -443,12 +546,116 @@ And of course a very basic test: This tip has been brought to you by Nick Ing-Simmons and Stas Bekman. +An alternative way to achieve this can be seen in L +and L. + +=back + =back +=head1 DESIGN + +=head2 MakeMaker object hierarchy (simplified) + +What most people need to know (superclasses on top.) + + ExtUtils::MM_Any + | + ExtUtils::MM_Unix + | + ExtUtils::MM_{Current OS} + | + ExtUtils::MakeMaker + | + MY + +The object actually used is of the class L which allows you to +override bits of MakeMaker inside your Makefile.PL by declaring +MY::foo() methods. + +=head2 MakeMaker object hierarchy (real) + +Here's how it really works: + + ExtUtils::MM_Any + | + ExtUtils::MM_Unix + | + ExtUtils::Liblist::Kid ExtUtils::MM_{Current OS} (if necessary) + | | + ExtUtils::Liblist ExtUtils::MakeMaker | + | | | + | | |----------------------- + ExtUtils::MM + | | + ExtUtils::MY MM (created by ExtUtils::MM) + | | + MY (created by ExtUtils::MY) | + . | + (mixin) | + . | + PACK### (created each call to ExtUtils::MakeMaker->new) + +NOTE: Yes, this is a mess. See +L +for some history. + +NOTE: When L is loaded it chooses a superclass for MM from +amongst the ExtUtils::MM_* modules based on the current operating +system. + +NOTE: ExtUtils::MM_{Current OS} represents one of the ExtUtils::MM_* +modules except L chosen based on your operating system. + +NOTE: The main object used by MakeMaker is a PACK### object, *not* +L. It is, effectively, a subclass of L, +L, L and ExtUtils::MM_{Current OS} + +NOTE: The methods in L are simply copied into PACK### rather +than MY being a superclass of PACK###. I don't remember the rationale. + +NOTE: L should be removed from the inheritance hiearchy +and simply be called as functions. + +NOTE: Modules like L and L have been omitted for clarity. + + +=head2 The MM_* hierarchy + + MM_Win95 MM_NW5 + \ / + MM_BeOS MM_Cygwin MM_OS2 MM_VMS MM_Win32 MM_DOS MM_UWIN + \ | | | / / / + ------------------------------------------------ + | | + MM_Unix | + | | + MM_Any + +NOTE: Each direct L subclass is also an +L subclass. This +is a temporary hack because MM_Unix overrides some MM_Any methods with +Unix specific code. It allows the non-Unix modules to see the +original MM_Any implementations. + +NOTE: Modules like L and L have been omitted for clarity. + =head1 PATCHING If you have a question you'd like to see added to the FAQ (whether or -not you have the answer) please send it to makemaker@perl.org. +not you have the answer) please either: + +=over 2 + +=item * make a pull request on the MakeMaker github repository + +=item * raise a issue on the MakeMaker github repository + +=item * file an RT ticket + +=item * email makemaker@perl.org + +=back =head1 AUTHOR