Perl/CPAN how to distribute script rather than module

Question

I just published my first perl program, unifdef+ (code::unifdefplus, v0.5.3), but I'm not sure if I've done it properly. The program is broken into two parts -- a script (script/unifdef+.pl), and a module (lib/unifdefplus.pm). The script is basically a wrapper for the module. This is supposed to act as a command line utility (which is in reality what I wanted to publish).

The README file I included documents the script, not the module. CPAN seems to be taking the version from the module rather than the script as well (which is undefined at the moment).

So, my questions is: if I want this to be indexed as a script rather than a module, do I need to do anything differently? Also, I'm taking it I should write some documentation for the module as well -- in which case I'm assuming it should be a README file in the lib directory?

Again, I apologize, but this is the first time I've done this, and I want to make sure I've done it right.

Answer 1

Right off the bat, please read On the naming of modules from the PAUSE admins. If you still have questions, or you're still unsure, reach out to modules <at> perl.org.

The simplest way is to use a name in the App:: namespace, such as App::MyMod.

Typically, I'd keep the script and module documentation within their separate files, but near the top of the module documentation, clearly link to the script's documentation, and state that most users will want to read that for normal use.

To build the README from the script documentation:

pod2readme bin/my_script

Likewise, if you change your mind and want README to reference the module instead:

pod2readme lib/App/MyMod.pm

Assuming you're using ExtUtils::MakeMaker for your builds, you can ensure that the script is installed by adding a directive:

EXE_FILES => [
    'bin/my_script'
],

With of course your script in the top-level bin directory of your distribution. Other build systems have similar directives.