Finding Stuff on the CPAN

Identifying the Problem you’re trying to solve

This is a general fact about the nature of problem solving: You can only solve a problem if you know what it is. And in my opinion, it is our job as developers to be able to do that. To identify problems in their context and find and evaluate applicable solutions. I’ll give you an example. Let’s say you want to “access the database.” This is nothing for which you’ll find a simple problem/solution pair. If you do, I’d assume it is an indication of a lack of flexibility of your tools. Some questions that might arise:

• What database? Are you concerned with a single one or do you ever expect that you might want to switch, or allow your application to connect to databases of different vendors? Maybe even at the same time?

• What are your technical constraints? Do you need to focus on speed, memory or maintainability?

• Is your DB simple or complex?

• Is your database even relational?

Personally, I’m a DBIx::Class fan. But not everybody is. Some like Rose, some like Kioku. All these different solutions appeal to different people in different situations. You could start, for example, by making a list of things that would make you not use a module. I don’t mean a “wishlist” on which you write things you find desirable, but rather a list of things you need to solve your problem. Once you know all the modules that are suitable for your task, you can still look at what else they would bring you, and decide upon that.

Searching the Comprehensive Perl Archive Network

It all starts of course with the CPAN search interface.

There are currently applications being in development (CPANHQ being an exciting example) that will make locating and finding information about modules easier. For now, if you search CPAN for something like “DB” or “XML,” you’ll get tons of results. You might have to narrow it down a bit, which is why it is so important to know what you’re trying to solve.

Simply trying to use Google often turns out fatal. But I found if you restrict your search and add

site:search.cpan.org/dist/

or alternatively (or additionally) search the KobeSearch CPAN Browser via

site:cpan.uwinnipeg.ca/dist/

you get a much better overview. I usually have keyword shortcuts defined for Firefox so I don’t have to remember them. The simplest way to define the ones for use with Google is to search for something with the parameters you want, and then replace the querystring with %s. My goopan shortcut points here. This means I can search the distributions on CPAN by entering

goopan web framework

into my address bar. Two others I found useful:

• cp, to directly search for distributions on KobeSearch
• dist, to look up a distribution of which I know the name already

I’ll skip the one’s for Wikipedia, other Google ones and so on, since they aren’t really relevant here, and it’s rather easy to shortcut your own queries.

Finding possible Solutions in the Community

Do you already use a framework that has its own community including mailing lists and extensions on CPAN? If yes, you might want to search in combination with this if the problem you are trying to solve is in context of that framework. Doing REST for example might be very different depending on which web framework you already have. If you can’t find any obvious solutions, another source of information might be IRC. The MagNET on irc.perl.org has lots of channels and people who will gladly help if you’re lost (Just don’t expect general Perl 5 help from #perl, there are beginner channels, language specific channels like #perlde or #perlfr, and project specific channels like #catalyst, #moose and #dbix-class that are much better suited).

There is also lots of information on the Perl 5 Wiki, including a list of recommended modules ordered by categories. This is a very good starting point if you have no frame of reference (like a surrounding web framework).

Still unsure? You can always search (Search first. Always. It’s just polite) or ask on PerlMonks, which has a bit of a rusty old interface, but has an enourmous amount of information, and a rich community behind it.

Utilising available Information about Modules

So, let’s assume you have compiled your list of candidates. You found a bunch of modules that could all do what you need to do, so which one to use? They all might have a different feature set that helps you decide what brings in more, but features aren’t everything, right? So, how do we judge a new found module and what information is available to us to do so? Quite some.

If you take a look at Moose’s distribution overview, you can see a block of information on the top, above the links to the documentation. So, let’s take a look at what’s there.

The “Other Releases” dropdown can give you a good indication on how often to expect updates and bugfixes from the module, if there tend to be release candidates, and so on.

A link called “View/Report Bugs ($n)” will point us towards an overview of the bugs/wishlist items for the distribution on RT. You should always check the documentation though. Some projects (especially the larger ones) have their own bugtracking systems.

You can use the “Dependencies” link to see a tree of other modules that are required to install, including the probabilities that they will pass their tests. Of course these numbers are statistics and not really applicable all the time. But the decision not to use something with 50% of the dependencies always failing is not a hard one.

The “Rating” section is a very wonderful one, since it gives you reallife wetware opinions. Sometimes the comments contain sarcasm, so if you’re not sure (as a fellow non-native english speaker I find this quite understandable) always take a look at the 1-5 star rating. Above every review you can see if other people felt this review was justified or unhelpful. This is all in general a rather good indicator.

Most CPAN distributions have a Changes file that I often consult. It gives a nice overview of what is happening to the module itself while it is being developed. You can also see how often bigger/smaller changes take place. Some even mention when the documentation was updated.

After the Fact: Finding Help

Now you’ve chosen your module, but you’re stuck. That one function doesn’t seem to be doing what the documentation made you expect. What to do now? A first thing I often do with modules and projects I’m not involved with, is to check the RT (or project specific tracker, like mentioned above) if this issue is already known. If CPAN holds a newer version of the module, you might want to try if the issue already got fixed.

If not, you should try to get in contact with the maintainers or community surrounding the module or project. Now, don’t just email the poor developer that uploaded the module. Some projects involve more than one (and some even many, just take a look at the list of Moose contributors). There’s no guarantee the uploader is someone who can give you a specific answer. When there’s a special place to ask for help, it is usually noted in the module documentation. Moose is a good example here too, since it delivers with a section on getting help.

Typical places to find assistance would be IRC, mailing lists or you can try to ask on PerlMonks. Chances are someone there is already using the module, contributing it, or at least able to understand the source code and find the root of the problem.

While we’re at source codes. Of course you can use the “Source” link provided for the modules on CPAN, but the features you find might be undocumented (and unsupported), and it just isn’t something for everybody.

If you solved your issue, that’s great! This would be the time to provide the developers with a documentation patch so future readers don’t have to go the same route to find an answer. This is how documentation gets better. The best documentation hints come from people who don’t know the module at hand, since they are the only one’s who know how the documentation could help them. It doesn’t have to be much, most of the time it’s just about a sentence or a paragraph in the right place.

If you couldn’t solve your problem, you can file a ticket on the module’s RT page (again, make sure to check the documentation if the module or project doesn’t have its own tracker, otherwise your ticket might be overlooked).

How about You?

This has been a very opinionated write-up. It is completely based on how I came to wrap my mind around the Perl 5 ecosystem and where I arrived after running against some walls.

If you know of other ways to find solutions on CPAN or to evaluate a module, please tell us about it. If you have a Perl blog to post it on, that would be even better, since it has the potential to reach more people.