pericmd 006: Naming of App module and distribution

Let’s get on a different topic first for a change. How should one name a (CLI) application module and distribution for CPAN? Here are my thoughts on the matter:

As we know, CPAN can (and does) contain applications in addition to modules. And a single CPAN distribution can contain both modules and applications, among other things. The overwhelming convention for a CPAN distribution that mainly contains application(s) is to name them App-subpackage. I release lots of those distributions, BTW.

There is usually the App::subpackage as the main module in the distribution. And of course the application itself which is put under script/scriptname or bin/scriptname subdirectory.

Now the problem is what you should use for subpackage and scriptname. Should they be the same name? What about capitalization? Also remember that scriptname can contain dashes or other characters that are problematic in a module/package name.

When an application is being used, users deal mostly with scriptname. They only remember the scriptname and oftentimes do not even know or remember what the name of the module/distribution is. One example of this is: cpanm (contained in App-cpanminus distribution and installed via something like “cpan App::cpanminus”). Or for more difference: cpan-outdated (contained in App-cpanoutdated), or ack (contained in App::Ack).

Module installers, since they often operate using only data provided by a regular CPAN mirror, expect a module name. This is because PAUSE does not index script names, only package names (in this file: 02packages.details.txt.gz). Hence, at least once, most users must find out the name of the module name for an application she has in mind. If she does not know or remember it, she will need to resort to searching the name using Google or MetaCPAN. Perhaps installers can be smarter and more helpful in the future by grok-ing script names too, but anyways.

Now, to ease user’s pain, I tend to give subpackage and scriptname with the same name, down to the capitalization. Examples: App-dux, App-fatten, App-nauniq, App-norepeat, and so on. So for example if I want to install say norepeat (which since I often use it almost daily, will remember the name of), I’ll just type: cpanm -n App::norepeat.

But some of my applications are named with multiple words, separated by dash (why use dash? Because I hate having to press Shift on my keyboard should I use underscore). For these, I switch subpackage to use camel case. Thus, I have these distributions: App-ListDebianReleases, App-CreateSelfSignedSSLCert, or App-CreateSparseFile. They contain, respectively, these CLI apps: list-debian-releases, create-self-signed-ssl-cert, and create-sparse-file. So, if I happen to need say create-self-signed-ssl-cert script, I know that I have to type: “cpanm -n App::CreateSelfSignedSSLCert” without looking it up, provided I remember the script’s name (and I usually do).

Then there are also CPAN distributions that contain a collection of scripts, instead of a single one. Examples for this include: App-DistUtils, App-PMUtils, App-OrgUtils. They too use camel casing and follow some extra convention, like the Utils suffix.

How do you name your application module/distribution?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s