/ 
Beer-Admin-0.10
/ Beer::Admin

NAME

Beer::Admin - Managing Bundled External Extension Rules (BEERs)

VERSION

This document describes version 0.10 of Beer::Admin, released February 28, 2003.

SYNOPSIS

In your Makefile.PL:

use inc::Beer;
WriteMakefile();

DESCRIPTION

This module provides a drop-in replacement for ExtUtils::MakeMaker. It is designed to let module authors reduce duplicated codes in Makefile.PL (and eventually Build.PL, etc).

To start using it, just replace the use ExtUtils::MakeMaker line from Makefile.PL with use inc::Beer, then run it once:

% perl Makefile.PL
Preparing inc
Filling inc/Beer.pm
Filling inc/Beer/MakeMaker.pm
Writing Makefile for Some::Module
Updating your MANIFEST file:
Adding 'inc/Beer.pm'
Adding 'inc/Beer/MakeMaker.pm

Now your distribution will have an extra inc/ directory, with the minimal loader code inc/Beer.pm copied into it. Also, since you made use of the WriteMakefile function, the Beer::MakeMaker extension is also copied into inc/.

This way, end-users of your distribution will not need to install anything extra; all necessary libraries are bundled with it. Note that because it will not bundle POD files, unused extensions or Beer::Admin itself, the impact on distribution size is minimized.

EXTENSIONS

All extensions belong to the Beer::* namespace. The first time Makefile.PL makes use of an extention's exported function, it will be automatically copied to the inc/Beer/ directory, and becomes fixed -- i.e. even if the user installs a different version of the same extension, the bundled one will still be used.

If you wish to upgrade extensions in inc/ with installed ones, simply remove the inc/ directory and run perl Makefile.PL again. Alternatively, type make reset will also do this for you.

There are currently three extensions shipped with Beer::Admin;

Beer::MakeMaker

A wrapper to ExtUtils::MakeMaker; it adds several extra make targets, as well as being more intelligent at guessing unspecified arguments.

Beer::Manifest

Exports functions for manipulating and updating the MANIFEST file.

Beer::Win32

Functions related for installing modules on Win32, including automatically fetching and installing nmake.exe for users that needs it.

Please consult their own documentations for detailed information.

FAQ

What are the benefits of using Beer::Admin?

Please consult this module's predeccessor, CPAN::MakeMaker, for a full list of arguments for using catalyst-style distribution like this module. Here is a brief overview of the reasons:

Does everything ExtUtils::MakeMaker does.
Requires no installation for end-users.
Always up to date.
Automatically updates your MANIFEST
Distributing scripts is easy.       # needs Beer::Scripts
Support for Inline::C.              # needs Beer::Inline
Bundle prerequisite modules.        # needs Beer::Bundle
Auto-installation of prerequisites. # needs Beer::AutoInstall
Support for precompiled binaries.   # needs Beer::PAR

Besides, if you author more than one CPAN modules, chances are there are duplicated in their Makefile.PL or with some other CPAN module you copied the code from. Beer::Admin makes it really easy for you to abstract away such codes; see next question.

Can I write my own extensions?

Definitely! In fact, if you are already a CPAN author, I would suggest you to put all your Makefile.PL magics into an extension named after your lowercased CPAN ID (e.g. Beer::autrijus), which exports all utility functions used by Makefile.PL.

You do not need to release this extension to CPAN at all; simply put it in your @INC, under the Beer/ directory, and Beer::Admin will automatically bundle it with all future distributions you make, but never install them into the end-user's computer.

How is this module different from CPAN::MakeMaker?

This module is not self-modifying. Also, writing extensions for Beer::Admin is easier -- instead of tweaking your local copy of CPAN/MakeMaker.pm, simply make a new Beer::* module under the @INC.

Why is the loader named inc::Beer?

The original implementation of CPAN::MakeMaker introduces subtle problems for distributions ending with CPAN (e.g. CPAN.pm, WAIT::Format::CPAN), because its placement in ./CPAN/ duplicates the real libraries that will get installed; also, the directory name ./CPAN/ may confuse users.

On the other hand, putting bundled, for-build-time-only libraries in ./inc/ is a normal practice, and there is little chance that a CPAN distribution will be called Something::inc, so it's much safer to use.

Also, it allows for other helper modules like ExtUtils::AutoInstall to reside also in ./inc/, and to make use of them in the future.

What does Beer::Admin mean?

On February 28, 2003, the following exchange took place on MagNet #perl:

<ingy> autrijus: I might just advise that only CPAN.pm use 0.11,
       and not actually release the version for the general public
<autrijus> ugh. but i want 0.11 to play with :)
<Spoon> 0.11 of what?
<autrijus> Spoon: of a highly convoluted module that requires
           Int 17 to understand.
<Spoon> it has no name?
<autrijus> no one dare speaking of its name.
<autrijus> Spoon: but one can hint; it has the nexus of perl
           community as its first name, and the humble device that
           installs modules as its last name
<EuroXwrn> Beer::Admin
<Spoon> oh. that one.
<autrijus> EuroXwrn: that's a good one
<Spoon> ingy's module that someone called viral
<ingy> Spoon: shhhh
* autrijus decides to fork CPAN::MakeMaker into Acme::Beer::Admin
<ingy> nice

So there. It's all Schwern's fault.

SEE ALSO

Beer::MakeMaker, Beer::Manifest, Beer::Win32

CPAN::MakeMaker, CPAN::MakeMaker-Philosophy, ExtUtils::MakeMaker

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

Based on original works by Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright 2003 by Autrijus Tang <autrijus@autrijus.org>. Copyright (c) 2002. Brian Ingerson. All rights reserved.

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

See http://www.perl.com/perl/misc/Artistic.html