CPAN::FindDependencies(3)

NAME
CPAN::FindDependencies - find dependencies for modules on the CPAN

SYNOPSIS
    use CPAN::FindDependencies;
    my @dependencies = CPAN::FindDependencies::finddeps("CPAN");
    foreach my $dep (@dependencies) {
        print ' ' x $dep->depth();
        print $dep->name().' ('.$dep->distribution().")\n";
    }

INCOMPATIBLE CHANGES
Up to version 2.49 you used the "02packages" argument to specify where a cached "02packages.details.txt.gz" could be found. That argument no longer exists as of version 3.00, use the "mirror" argument instead.

Up to version 2.49, "maxdepth => 0" would incorrectly return the whole tree. From version 3.00 it cuts the tree off at its root so will only return the module that you asked about. Not very useful, but correct.

In version 2.49 you used the "configreqs" argument to specify that you were interested in configure-time requirements as well as build- and run-time requirements. That option no longer exists as of version 3.00, it will always report on configure, build, test, and run-time requirements.

HOW IT WORKS
The module uses the CPAN packages index to map modules to distributions and vice versa, and then fetches distributions' metadata or Makefile.PL files from a CPAN mirror to determine pre-requisites. This means that a working interwebnet connection is required.

FUNCTIONS
There is just one function, which is not exported by default although you can make that happen in the usual fashion.

  finddeps
Takes a single compulsory parameter, the name of a module (ie Some::Module); and the following optional named parameters:

nowarnings
    Warnings about modules where we can't find their META.yml or Makefile.PL, and so can't divine their pre-requisites, will be suppressed. Other warnings may still be emitted though, such as those telling you about modules which have dodgy (but still understandable) metadata;

fatalerrors
    Failure to get a module's dependencies will be a fatal error instead of merely emitting a warning;

perl
    Use this version of perl to figure out what's in core. If not specified, it defaults to 5.005. Three part version numbers (eg 5.8.8) are supported but discouraged.

cachedir
    A directory to use for caching. It defaults to no caching. Even if caching is turned on, this is only for META.yml or Makefile.PL files.

    The cache is never automatically cleared out. It is your responsibility to clear out old data.

maxdepth
    Cuts off the dependency tree at the specified depth. Your specified module is at depth 0, your dependencies at depth 1, their dependencies at depth 2, and so on.

    If you don't specify any maxdepth at all it will grovel over the entire tree.

mirror
    This can be provided more than once, if for example you want to use a private Pinto repository for your own code while using a public CPAN mirror for open source dependencies. The argument comes in two parts separated by a comma - the base URL from which to fetch files, and optionally the URL or a file from which to fetch the index "02packages.details.txt.gz" file to use with that mirror.

      mirror https://cpan.mydomain.net,file:///home/me/mycache/02packages.txt.gz

    If you want to use the default CPAN mirror (https://cpan.metacpan.org/) but also specify an index location you can use "DEFAULT" for the mirror URL.

    So for example, to use your own special private mirror, including fetching 02packages from it, but also use the default mirror with a cached local copy of its 02packages, specify two mirrors thus:

      mirror => 'https://cpan.mydomain.net',
      mirror => 'DEFAULT,file:///home/me/mycache/02packages.txt.gz'

    The index is cached for three minutes or until your process finishes, whichever is soonest. This is because it is HUMUNGOUS and parsing it takes ages even when it's loaded from a local disk, and I don't want the tests to take forever.

usemakefilepl
    If set to true, then for any module that doesn't have a META.yml, try to use its Makefile.PL as well. Note that this involves downloading code from the Internet and running it. This obviously opens you up to all kinds of bad juju, hence why it is disabled by default. NB that this fetches Makefile.PL from <https://fastapi.metacpan.org> only so will not work for private mirrors. This is a deliberate choice, your own private code ought to be packaged properly with a META file, you should only care about divining dependencies from Makefile.PL if you rely on really old stuff on public CPAN mirrors.

recommended
    Adds recommended modules to the list of dependencies, if set to a true value.

suggested
    Adds suggested modules to the list of dependencies, if set to a true value.

Order of arguments is not important.

It returns a list of CPAN::FindDependencies::Dependency objects, whose useful methods are:

name
    The module's name;

distribution
    The distribution containing this module;

version
    The minimum required version of his module (if specified in the requirer's pre-requisites list);

depth
    How deep in the dependency tree this module is;

warning
    If any warning was generated (even if suppressed) for the module, it will be recorded here.

Any modules listed as dependencies but which are in the perl core distribution for the version of perl you specified are suppressed.

These objects are returned in a semi-defined order. You can be sure that a module will be immediately followed by one of its dependencies, then that dependency's dependencies, and so on, followed by the 'root' module's next dependency, and so on. You can reconstruct the tree by paying attention to the depth of each object.

The ordering of any particular module's immediate 'children' can be assumed to be random - it's actually hash key order.

TREE PRUNING
The dependency tree is pruned to remove duplicates. This means that even though "Test::More", for example, is a dependency of almost everything on the CPAN, it will only be listed once.

SECURITY
If you set "usemakefilepl" to a true value, this module may download code from the internet and execute it. You should think carefully before enabling that feature.

BUGS/WARNINGS/LIMITATIONS
You must have web access to <http://metacpan.org/> and (unless you tell it where else to look for the index) <http://www.cpan.org/>, or have all the data cached locally.. If any metadata or Makefile.PL files are missing, the distribution's dependencies will not be found and a warning will be spat out.

Startup can be slow, especially if it needs to fetch the index from the interweb.

Dynamic dependencies - for example, dependencies that only apply on some platforms - can't be reliably resolved. They *may* be resolved if you use the unsafe Makefile.PL, but even that can't be relied on.

FEEDBACK
I welcome feedback about my code, including constructive criticism and bug reports. The best bug reports include files that I can add to the test suite, which fail with the current code in my git repo and will pass once I've fixed the bug

Feature requests are far more likely to get implemented if you submit a patch yourself.

SOURCE CODE REPOSITORY
<git://github.com/DrHyde/perl-modules-CPAN-FindDependencies.git>

SEE ALSO
CPAN

<http://deps.cpantesters.org/>

<http://metacpan.org>

AUTHOR, LICENCE and COPYRIGHT
Copyright 2007 - 2019 David Cantrell <david@cantrell.org.uk>

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

THANKS TO
Stephan Loyd (for fixing problems with some META.yml files)

Alexandr Ciornii (for a patch to stop it segfaulting on Windows)

Brian Phillips (for the code to report on required versions of modules)

Ian Tegebo (for the code to extract deps from Makefile.PL)

Georg Oechsler (for the code to also list 'recommended' modules)

Jonathan Stowe (for making it work through HTTP proxies)

Kenneth Olwing (for support for 'configure_requires')

CONSPIRACY
This module is also free-as-in-mason software.