Bug #19235 for Module-Build: --prefix not documented

This patch does several things. * It documents --prefix. The docs do not attempt to explain its behavior, they merely explain its purpose and reference MakeMaker's PREFIX. * Adds a cookbook recipe for getting Module::Build and MakeMaker to install into the same place as well as illustrate how to translate some of the most common MM flags to MB. * Removes a mention of --prefix from the recipe for installing to a non-standard location. Its complicating what should be a simple recipe. * Removes the long, technical discussion of the problems with PREFIX from the Module::Build docs. It clutters what is supposed to be simple and basic documentation with a narrow technical discussion. I've replaced it with a short discussion on prefix vs install_base in the cookbook recipe.

Sat May 13 02:36:02 PDT 2006 schwern@pobox.com * Remove long discussion about PREFIX from the basic docs Sat May 13 02:29:12 PDT 2006 schwern@pobox.com * Recepie for Installing in the same location as ExtUtils::MakeMaker Fri May 12 23:43:14 PDT 2006 schwern@pobox.com * Document --prefix Fri May 12 23:42:01 PDT 2006 schwern@pobox.com * Remove mention of --prefix from simple install docs The cookbook recepie for how to install into a non-standard location is not the place to bring up MakeMaker compatibility. It just complicates things. That should be in its own section. diff -rN -u old-Module-Build-0.28/lib/Module/Build/Cookbook.pm new-Module-Build-0.28/lib/Module/Build/Cookbook.pm --- old-Module-Build-0.28/lib/Module/Build/Cookbook.pm 2006-05-13 02:37:30.000000000 -0700 +++ new-Module-Build-0.28/lib/Module/Build/Cookbook.pm 2006-05-13 02:37:30.000000000 -0700 @@ -131,22 +131,69 @@ To install to a non-standard directory (for example, if you don't have permission to install in the system-wide directories), you can use the -C<install_base> or C<prefix> parameters: +C<install_base>: ./Build install --install_base /foo/bar - or - ./Build install --prefix /foo/bar - -Note that these have somewhat different effects - C<prefix> is an -emulation of C<ExtUtils::MakeMaker>'s old C<PREFIX> setting, and -inherits all its nasty gotchas. C<install_base> is more predictable, -and newer versions of C<ExtUtils::MakeMaker> also support it, so it's -often your best choice. See L<Module::Build/"INSTALL PATHS"> for a much more complete discussion of how installation paths are determined. +=head2 Installing in the same location as ExtUtils::MakeMaker + +With the introduction of C<--prefix> in Module::Build 0.28 and +C<INSTALL_BASE> in ExtUtils::MakeMaker 6.31 its easy to get them both +to install to the same locations. + +First, ensure you have at least version 0.28 of Module::Build +installed and 6.31 of ExtUtils::MakeMaker. Prior versions have +differing installation behaviors. + +The following installation flags are equivalent between +ExtUtils::MakeMaker and Module::Build. + + MakeMaker Module::Build + PREFIX=... --prefix ... + INSTALL_BASE=... --install_base ... + DESTDIR=... --destdir ... + LIB=... --install_path lib=... + INSTALLDIRS=... --installdirs ... + INSTALLDIRS=perl --installdirs core + UNINST=... --uninst ... + INC=... --extra_compiler_flags ... + POLLUTE=1 --extra_compiler_flags -DPERL_POLLUTE + +For example, if you are currently installing MakeMaker modules with +this command: + + perl Makefile.PL PREFIX=~ + make test + make install UNINST=1 + +You can install into the same location with Module::Build using this: + + perl Build.PL --prefix ~ + ./Build test + ./Build install --uninst 1 + +=head3 C<prefix> vs C<install_base> + +The behavior of C<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 C<prefix> will place your modules. + +In contrast, C<install_base> has predictable, easy to explain +installation locations. Now that Module::Build and MakeMaker both +have C<install_base> there is little reason to use C<prefix> other +than to preserve your existing installation locations. If you are +starting a fresh Perl installation we encourage you to use +C<install_base>. If you have an existing installation installed via +C<prefix>, consider moving it to an installation structure matching +C<install_base> and using that instead. + + =head2 Running a single test file C<Module::Build> supports running a single test, which enables you to diff -rN -u old-Module-Build-0.28/lib/Module/Build.pm new-Module-Build-0.28/lib/Module/Build.pm --- old-Module-Build-0.28/lib/Module/Build.pm 2006-05-13 02:37:30.000000000 -0700 +++ new-Module-Build-0.28/lib/Module/Build.pm 2006-05-13 02:37:30.000000000 -0700 @@ -867,113 +867,29 @@ C<File::Spec> to make the pathnames work correctly on whatever platform you're installing on. -=back - - -=head2 About PREFIX Support - -[version 0.28] - -First, it is necessary to understand the original idea behind -C<PREFIX>. If, for example, the default installation locations for -your machine are F</usr/local/lib/perl5/5.8.5> for modules, -F</usr/local/bin> for executables, F</usr/local/man/man1> and -F</usr/local/man/man3> for manual pages, etc., then they all share the -same "prefix" F</usr/local>. MakeMaker's C<PREFIX> mechanism was -intended as a way to change an existing prefix that happened to occur -in all those paths - essentially a C<< s{/usr/local}{/foo/bar} >> for -each path. - -However, the real world is more complicated than that. The C<PREFIX> -idea is fundamentally broken when your machine doesn't jibe with -C<PREFIX>'s worldview. - - -=over 4 - -=item Why PREFIX is not recommended - -=over 4 - -=item * - -Many systems have Perl configs that make little sense with PREFIX. -For example, OS X, where core modules go in -F</System/Library/Perl/...>, user-installed modules go in -F</Library/Perl/...>, and man pages go in F</usr/share/man/...>. The -PREFIX is thus set to F</>. Install L<Foo::Bar> on OS X with -C<PREFIX=/home/spurkis> and you get things like -F</home/spurkis/Library/Perl/5.8.1/Foo/Bar.pm> and -F</home/spurkis/usr/share/man/man3/Foo::Bar.3pm>. Not too pretty. - -The problem is not limited to Unix-like platforms, either - on Windows -builds (e.g. ActiveState perl 5.8.0), we have user-installed modules -going in F<C:\Perl\site\lib>, user-installed executables going in -F<C:\Perl\bin>, and PREFIX=F<C:\Perl\site>. The prefix just doesn't -apply neatly to the executables. - -=item * - -The PREFIX logic is too complicated and hard to predict for the user. -It's hard to document what exactly is going to happen. You can't give -a user simple instructions like "run perl Makefile.PL PREFIX=~ and -then set PERL5LIB=~/lib/perl5". - -=item * - -The results from PREFIX will change if your configuration of Perl -changes (for example, if you upgrade Perl). This means your modules -will end up in different places. - -=item * - -The results from PREFIX can change with different releases of -MakeMaker. The logic of PREFIX is subtle and it has been altered in -the past (mostly to limit damage in the many "edge cases" when its -behavior was undesirable). - -=item * - -PREFIX imposes decisions made by the person who configured Perl onto -the person installing a module. The person who configured Perl could -have been you or it could have been some guy at Redhat. - -=back - - -=item Alternatives to PREFIX - -Module::Build offers L</install_base> as a simple, predictable, and -user-configurable alternative to ExtUtils::MakeMaker's C<PREFIX>. -What's more, MakeMaker will soon accept C<INSTALL_BASE> -- we strongly -urge you to make the switch. - -Here's a quick comparison of the two when installing modules to your -home directory on a unix box: - -MakeMaker [*]: - - % perl Makefile.PL PREFIX=/home/spurkis - PERL5LIB=/home/spurkis/lib/perl5/5.8.5:/home/spurkis/lib/perl5/site_perl/5.8.5 - PATH=/home/spurkis/bin - MANPATH=/home/spurkis/man - -Module::Build: - - % perl Build.PL install_base=/home/spurkis - PERL5LIB=/home/spurkis/lib/perl5 - PATH=/home/spurkis/bin - MANPATH=/home/spurkis/man - -[*] Note that MakeMaker's behaviour cannot be guaranteed in even this -common scenario, and differs among different versions of MakeMaker. - -In short, using C<install_base> is similar to the following MakeMaker usage: +=item prefix - perl Makefile.PL PREFIX=/home/spurkis LIB=/home/spurkis/lib/perl5 +Provided for compatibility with ExtUtils::MakeMaker's PREFIX argument. +C<prefix> should be used when you wish Module::Build to install your +modules, documentation and scripts in the same place +ExtUtils::MakeMaker does. + +The following are equivalent. + + perl Build.PL --prefix /tmp/foo + perl Makefile.PL PREFIX=/tmp/foo + +Because of the very complex nature of the prefixification logic, the +behavior of PREFIX in MakeMaker has changed subtly over time. +Module::Build's --prefix logic is equivalent to the PREFIX logic found +in ExtUtils::MakeMaker 6.30. + +If you do not need to retain compatibility with ExtUtils::MakeMaker or +are starting a fresh Perl installation we recommand you use +C<install_base> instead (and C<INSTALL_BASE> in ExtUtils::MakeMaker). +See L<Module::Build::Cookbook/Instaling in the same location as +ExtUtils::MakeMaker> for further information. -See L</"INSTALL PATHS"> for details on other -installation options available and how to configure them. =back