You want the documents for ExtUtils::MakeMaker - specifically this bit.

actually, this documentation has never helped me. i just didn't get the difference of the two parameters.

a couple of years ago, when I had the problem to install an application onto the customers machine and the dependant modules (packaged with the application) into a certain directory nobody in c.l.p.m could really help me, and the MakeMaker docs didn't either. I only used the PREFIX parameter and was wondering how to predict in which directories the modules would end up (as this changed also between perl versions).

I happened to stumble over a website where Makefile.PL was called additionally with the LIB parameter (I don't remember where I found this). I tried it, and it just worked. Foo::Bar ended up reliably in prefix/Foo/Bar.pm, so that I knew that I could just say use lib qw(prefix);

But why?

So I think the docs are not really easy to understand. It says for PREFIX=~:
This will install all files in the module under your home directory, with man pages and libraries going into an appropriate place (usually ~/man and ~/lib).

and for LIB=~/lib:
This will install the module's architecture-independent files into ~/lib, the architecture-dependent files into ~/lib/$archname.

What exactly is the difference between "all files in the module" and "the module's architecture-independent files"? (Note that also using PREFIX will use a different directory for architecture dependant files.) If you read the documentation for LIB, you don't know why you still have to use PREFIX.

I think a part of the confusion is caused by the fact that both parameters can contradict each other (saying PREFIX=/foo/bar LIB=/foo/baz)

LIB is the directory that the system should install the modules to... PREFIX is um ... special.

Basically, to summarize the slides -- PREFIX is used to affect LIB, PATH, and MANPATH ... but because some vendors have adjusted how those values are derived from PREFIX, you can end up with files where you didn't expect them

(oh ... and Module::Build now supports PREFIX, but I'm not sure that's a good thing)

I understand vaguely supporting PREFIX has become hairy. What I don't understand is, what are the best practices to deal with the situation.

Is tinita's suggestion of using LIB and PREFIX together a best practice for installing modules locally?

Will this ever fail?

If yes, when will if fail?

If no (ie, it shouldn't ever fail), shouldn't the documentation for installing perl modules locally be patched to mention this?

More concretely: if there's a scenario like the one you mentioned, where LIB is calculated from PREFIX, but the PREFIX value was also specified to Makefile.PL, which value will ultimately wind up being used?

If you pass both, PREFIX will be used to generate PATH and MANPATH, while the LIB you passed in will be used as is.

And I'm relucant to say 'best practice', as what's best in each situation varies greatly. Specifying both should get the .pm files installed to the correct place, but I can't be sure that your man pages or executables will be.

And to respond to your other question --

'vendor' == Vendors of operating systems that supply already compiled versions of perl.

As for examples, the link I gave (which was labeled 'special', and could have been labeled better), is a talk by Michael Schwern titled 'Why PREFIX Will Never Work'. Slide 8 talks about Apple's values in MacOSX, and slide 9 talks about the values in Debian.

"...because some vendors have adjusted how those values are derived from PREFIX..."

I'm confused.

Some vendors of what? Perl? Perl modules? Operating systems?

Do you know of any specific examples of this?

Take this example, Module::Starter comes with a command-line utility called module-starter. Setting the PREFIX variable would install the command-line utility there but Module/Starter.pm would get installed in the normal lib directory.

At least that is the way I understand it. Please feel free to correct me if I am wrong.

At least that is the way I understand it. Please feel free to correct me if I am wrong.

You're wrong ;-)

Setting PREFIX would install both the module and the command line utility under PREFIX.