Using cpanm to install Perl modules

Question

Maybe it's a stupid question? If I install a module like File using

cpanm File

will it install everything under File, like File:Listing etc?

Answer 1

It's not a stupid question, and I can understand why you wouldn't want to just try it.

But you can go ahead and do

cpanm File

and very little will happen as there isn't a module called File.

The modules on CPAN are organized by distribution. A single distribution can contain one or more related modules, so cpanm first checks which distribution contains the module you asked for and fetches it.

That distribution is checked for dependencies, and if there are any that are out of date or not installed at all then it will fetch and install each of those in turn. Eventually either all dependencies will be resolved or there will have been a critical error that stops cpanm from proceeding.

When all dependencies are installed, the distribution that contains your module can be unpacked and installed.

All being well that is the end of things, so in brief

cpanm File

will install nothing, because there is no File module.

cpanm File:Listing

will install the distribution that contains File::Listing, which at the time of writing is GAAS/File-Listing-6.04.tar.gz

That distribution also happens to contain these modules

File::Listing::apache
File::Listing::dosftp
File::Listing::netware
File::Listing::unix
File::Listing::vms

so cpanm will first ensure that all of those modules' dependencies are fulfilled and continue recursively on the same basis.

---

Note that it may be useful to experiment with the cpan command, which has a more comprehensive set of commands. Most significantly, it will list modules, distributions, authors and bundles by name or by regular expression.

Enter cpan and get the prompt

cpan>

when you can ask for

cpan> help

and it will list a summary of the available commands. For instance I can examine the File::Listing module

cpan> m File::Listing

to see the author, distribution ("CPAN_FILE"), version etc. like this

Module id = File::Listing
    CPAN_USERID  GAAS (Gisle Aas <[email protected]>)
    CPAN_VERSION 6.04
    CPAN_FILE    G/GA/GAAS/File-Listing-6.04.tar.gz
    UPLOAD_DATE  2012-02-15
    MANPAGE      File::Listing - parse directory listing
    INST_FILE    C:\Strawberry\perl\vendor\lib\File\Listing.pm
    INST_VERSION 6.04

I can also look for distributions with a similar name, using a regex

cpan> d /File-Listing/

to see that there are two matching distributions

Distribution    GAAS/File-Listing-6.04.tar.gz
Distribution    PLICEASE/File-Listing-Ftpcopy-0.05.tar.gz
2 items found

and I can look at just Gisle Aas' File-Listing distribution with

cpan> d GAAS/File-Listing-6.04.tar.gz

and I am told about that distribution's member modules ("CONTAINSMODS") amongst other things

Distribution id = G/GA/GAAS/File-Listing-6.04.tar.gz
    CPAN_USERID  GAAS (Gisle Aas <[email protected]>)
    CPAN_VERSION 6.04
    CONTAINSMODS File::Listing File::Listing::apache File::Listing::dosftp File::Listing::netware File::Listing::unix File::Listing::vms
    UPLOAD_DATE  2012-02-15

cpanm has no such browsing facilities, so I suggest you experiment with cpan itself and use the m and perhaps the d commands for a while, with both full names and regex patterns.

Once you have understood the structure of the CPAN repository you will find cpanm much quicker and more precise for general use.

Answer 2

When you request to install a module, a CPAN client (such as cpanm) will check an index to find out which archive (i.e. probably a .tar.gz file, but perhaps .tar.bz2 or .zip) contains the latest authorized version of that module.

The client will then download that archive, and run the installation script found inside, which may indeed install not just the module you requested, but other bundled modules. (Though a large number archives on CPAN contain only a single module each.)

Along the way, the client may also detect that what you're installing has dependencies that also need installation, and automatically add them to the queue to be installed.

The names of the modules are not relevant. If you install Foo, you won't automatically get Foo::Bar just because it has a similar name. You'd only automatically get Foo::Bar if it were in the same archive file as Foo.

Answer 3

CPAN doesn't have a hierarchical organization like you're imagining — just because Foo exists and Foo::Bar exists doesn't mean that Foo::Bar is "under" Foo in a meaningful sense. It might be, but in many cases it isn't. Net::SSH::Perl isn't a part of Net::SSH; and IO::Async definitely isn't part of IO.

As tobyink and Borodin have pretty well explained, Perl modules are part of "distributions", which are the package files uploaded to CPAN. When you ask for a module to be installed, the CPAN client will install the distribution containing that module, and any distributions that that distribution depends on to build or run.