[Module-build-checkins] [svn:Module-Build] r6314 - in Module-Build/trunk: . lib/Module lib/Module/Build

[<kwi...@cv...>]

Author: kwilliams
Date: Thu May 18 19:06:04 2006
New Revision: 6314

Modified:
   Module-Build/trunk/   (props changed)
   Module-Build/trunk/lib/Module/Build.pm
   Module-Build/trunk/lib/Module/Build/Cookbook.pm

Log:
 r1907@Scotchie:  ken | 2006-05-18 20:58:46 -0500
 Apply a patch from Schwern that looks like it improves the
 documentation and cookbook for --prefix.


Modified: Module-Build/trunk/lib/Module/Build.pm
==============================================================================
--- Module-Build/trunk/lib/Module/Build.pm	(original)
+++ Module-Build/trunk/lib/Module/Build.pm	Thu May 18 19:06:04 2006
@@ -851,113 +851,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
 

Modified: Module-Build/trunk/lib/Module/Build/Cookbook.pm
==============================================================================
--- Module-Build/trunk/lib/Module/Build/Cookbook.pm	(original)
+++ Module-Build/trunk/lib/Module/Build/Cookbook.pm	Thu May 18 19:06:04 2006
@@ -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