As you have implied in your first sentence, CPAN is all about distributions. There's more to a distribution than shipping code that the user can run. There's documentation, tests, examples, and control files that help you verify that your distribution is complete. A standalone script wouldn't have all, or indeed any of this provided.

The traditional way of distributing a script is as a standalone file that needs to be copied into a special place, e.g. a cgi-bin directory. There may be some manual configuring required with an editor, to set variables to contain real paths on the target machine. As a potential user, putting the script live is a great leap of faith. There's no reassurance that it will work with the configuration of the machine on which it's being installed.

A much better idea is to put all your functionality into one or more .pm files, and ship a bare bones script that calls the module(s). The reason why it's better is that you can write tests that call the module API and exercise the code completely.

The installer of your distribution gets to run tests of the module's functionality during the installation process, and is instantly made aware of any problems, before the module is installed. This becomes even more important when it comes to upgrading an existing installation.

That makes a large amount of sense to me. I've been quietly grumbling for a long time that the scripts area on CPAN is very much a second class citizen - now I understand why.

Indeed, exactly those considerations are why a next version of PMEdit will go up as a module distribution rather than to the scripts area, so I guess in a rather arse backwards fashion the objectives of CPAN are being imposed and met. ;)

Thanks for the clarification. It would be nice if something like your explanation were promanent in the scripts area of CPAN.

---

DWIM is Perl's answer to Gödel

You might do what petdance has done with ack. ack is a grep-like script. To make it findable on cpan, Andy has split out the useful functions into App::Ack.

So, you might consider App::Foo good enough for your needs.

Entirely lower-cased package names are reserved for pragmas, so you should go with the Foo::Bar format.

I'd personally opt for something along the lines like Script::Install (bear in mind, that there's Module::Install too, for modulish purposes).

So yeah, go ahead with the "dummy .pm file". As someone else pointed out already, App::Ack exists only to be able to have $App::Ack::VERSION which the CPAN shell can check so that people can easily do updates.

CPAN is about source distributions. not binary distributions. The only binaries you will find on CPAN are probably pictures (jpeg) and suchlike.

I think you are referring to C library interface modules. The bulk of the work (and code) takes place in C, either as source files in the distribution, or in third party libraries. There is some minimal Perl code inside the .pm, to "bootstrap" the shared library component.

To answer your question about pod in a binary distribution, this depends on your package manager. I have successfully used PAR in conjunction with a standalone Tk script that contains its own help text as pod (and I have a help function on the menu bar which displays the pod in its own window). I did have to jump through a few hoops, and I believe that it's easier to do in more recent versions of PAR and PAR::Packer.

I've given a talk on packaging Perl applications at two YAPC conferences, and I have submitted it to present at Houston TX in June.

--
Apprentice wetware hacker