MakeMaker works without a flaw for me. Even on Win32.
The documentation is good enough. Only if you need very
difficult things you need to take the source code as
documentation. But if you want that, that's probably better
than writing a manual.
I didn't use Module::Build, nothing to say about that.
MakeMaker is the standard utility for generating makefiles to install Perl modules. If you plan on creating a Perl module distribution for CPAN, it's a sure thing that you're gonna have to do battle with this beast at some point.
I'll try to keep this short:
1) The documentation isn't all that great.
Notice, it doesn't even say exactly what the behavior of the default makefile will be, just that, "The generated Makefile enables the user of the extension to invoke..." Yeah, and what will that do? Will it move everything in ./lib to the Perl site/lib directory? Will it leave everything else alone? Will it try execute every *.pl script that comes with the distribution or move them to the /usr/bin directory? The docs don't say, at least not in a clear, obvious way. Instead, you have to go searching through the documentation for each and every possible option for WriteMakefile() to find out.
2) It's useless for anything else.
MakeMaker can't be used to create general-purpose makefiles for installing general-purpose Perl applications. Yes, I know what you're going to say: "MakeMaker is for installing modules, not applications!" That's true, but it could have easily been extended to do both; if we could just tell MakeMaker what to mess with and what not to mess with and where to put what it messes with it would be infinitely more useful. You can sort of do this now by creating your own MakeMaker class and overriding "make install," but thisï¿½like a makefile itselfï¿½is a royal pain in the ass.
There's certainly something to be said for doing one thing and doing it well, but notice that if h2xs did just that, then MakeMaker wouldn't be extolling its virtues.
3) It makes makefiles in the first place.
I know I'm not making any friends here, but why the heck are we even using makefiles in the first place? Especially makefiles littered with Perl one-liners and shell commands? Isn't this what *Perl* is for?
I honestly HATE makefiles. The syntax is awful, they're not portable (a makefile written for MacOS probably won't work with GNU Make on Linux, for example), whitespace matters (and yet GNU make only accepts linefeeds as line endings), and they're so damn complicated that you find yourself just hoping with all your heart that they work, because if they don't, well, you're probably screwed. I'd be willing to wager that the vast majority of makefiles are machine-generated rather than hand-edited by a thoughtful human developer either as result of or in response to their ever-increasing complexity.
All and all, this was interesting but very bad idea. It's time for MakeMaker to be retired. We now have Module::Build, a lovely pure-Perl utility for installing modules. Here's what current maintainers of MakeMaker say about Module::Build:
"Module::Build is the official heir apparent to MakeMaker and we encourage people to work on M::B rather than spending time improving MakeMaker." - ExtUtils::MakeMaker::FAQ.
Stay away from MakeMaker unless you absolutely have to use it, which, unfortunately, you probably do.