Following on from my previous post on CPAN terminology, this one focusses on the model and terminology related to dependencies: the modules that your dist uses, and the other CPAN distributions that use yours.
This post might seem a bit rough around the edges, because I've been writing it to clarify my understanding, and filling in gaps as I go. Let me know if I've got anything wrong or unclear, or missed anything you think fits here.
This might seem obvious, but those are modules.
You don't install modules though, you install the latest release of the distribution that contains the module. So when you type
# cpan Web::Query
you end up installing the Web-Query distribution. At the time I'm writing this, you'd install the 0.32 release of Web-Query, which is the tarball Web-Query-0.32.tar.gz
We started off talking about three modules, but now we're dealing with the distributions, all of which contain other modules:
Here the three modules we're talking about happen to be the main modules of their respective distributions. But this isn't always the case: if List::MoreUtils used Exporter::Shiny instead of Exporter::Tiny, then obviously that wouldn't be true (see, for example, Term::Vspark).
Most of the time when people are talking about CPAN dependencies, they're talking about distribution dependencies. If we consider the three distributions above in the context of the river model, then here's roughly where they fit:
Exporter-Tiny and List-MoreUtils are both a long way up the river — they're used by a lot of other CPAN distributions. The usage count includes indirect usage: Web-Query uses Exporter-Tiny indirectly.
From the perspective of List-MoreUtils, Exporter-Tiny is upstream, and Web-Query is downstream. So for your distribution, upstream dependencies are the distributions that you use, and downstream dependencies are the ones using your dist.
So far we've been talking about runtime dependencies:
every time your code uses
List::MoreUtils, it uses
This is called the runtime phase, and there are other phases that can
have dependencies associated with them.
List-MoreUtils has a
Makefile.PL, so if you were installing
it manually, you'd run:
perl Makefile.PL make make test make install
With that in mind, these are the other phases:
Makefile.PLthat uses ExtUtils::MakeMaker, so ExtUtils::MakeMaker is a configure dependency.
Build, if your distribution has a
Build.PL). This phase is blank for most distributions on CPAN, but if your distribution used the Template-Toolkit to build your
.pmfrom templates, then you'd have Template listed as a build prereq.
Build test. This will often be Test::More and any other
Test::modules that your testsuite uses.
In addition to phase, dependencies also have a relationship type, which in most cases specifies how hard the dependency is:
So now we can look at a more complete view of the upstream dependencies for List-MoreUtils, considering the modules used:
The official spec for dependency definitions is CPAN::Meta::Spec.
One fuzzy area when specifying dependencies is core modules.
The main reason for specifying your dependencies is so that when a CPAN client is installing your distribution, it can check whether the dependencies are already installed, and if not, install them first.
But by definition, core modules will already have been installed.
Personally I think you should list all prereqs: