=head1 NAME

Module::Install-Cookbook - A CornucopiE<aelig> of Module::Install Recipes

=head1 DESCRIPTION

It's a lot easier for most of us to cook a meal from a recipe, rather
than just throwing things into a pot until something edible forms.  So
it is with programming as well.  B<Module::Install> makes writing Perl
module installers as easy as possible.  Having a set of easy to
understand samples, makes it simpler yet.

This Cookbook is intended to be an ever-growing repository of small yet
complete coding examples; each showing how to accomplish a particular
task with B<Module::Install>.  Each example is followed by a short
discussion, explaining in detail the particular features that are being
demonstrated.

Guten Appetit!

=head1 Appetizers

=head2 Replacing C<ExtUtils::MakeMaker>

=over 4

=item Problem

As a CPAN author, you are likely to have some B<ExtUtils::MakeMaker>
based F<Makefile.PL> already.  You want to take advantage of cool
features offered by B<Module::Install> extensions, but why fix something
that's not broken?

=item Solution

The I<fix> turns out to be extremely simple.  Where you had:

    use ExtUtils::MakeMaker;
    WriteMakefile( NAME => "Foo::Bar" );

Now just write:

    use inc::Module::Install;
    WriteMakefile( NAME => "Foo::Bar" );

Presto!  Your F<Makefile.PL> is now ready to receive all sort of magic
extensions; see below for details.

=back

=over 4

=item Problem

XXX F<Build.PL>

=item Solution

=back


=head1 Fast Food

XXX: to be written

=head1 The Main Course

=item Problem

Installing XS extensions from CPAN was difficult.  Some platforms do
not come with a compiler (Win32, MacOSX...); some headers or libraries
may be missing.

=item Solution

Just use the C<par_base> and C<fetch_par> functions:

    # same old Makefile.PL, with a few changes
    use inc::Module::Install;	        # was "use ExtUtils::MakeMaker;"
    WriteMakefile( ... );		# same as the original
    check_nmake();			# make sure the user have nmake
    par_base('AUTRIJUS');		# your CPAN ID or a URL
    fetch_par() unless can_cc();	# use precompiled PAR only if necessary

Users will not notice anything, except now it works.  Of course, you
still need to type C<make par> and upload the precompiled package.

=head1 Just Desserts

XXX: to be written

=head1 Entertaining Guests

XXX: to be written

=head1 Food for Thought

XXX: to be written

=head1 SEE ALSO

For generic information, see L<Module::Install>.

=head1 AUTHOR

Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>

Structure based on L<Inline::C-Cookbook> by Brian Ingerson
E<lt>INGY@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright 2003, 2004 by Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>.

Copyright 2002 by Brian Ingerson E<lt>INGY@cpan.orgE<gt>.

This document is free documentation; you can redistribute it and/or
modify it under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
