BackPAN::Index::Create - generate an index file for a BackPAN mirror


 use BackPAN::Index::Create qw/ create_backpan_index /;

      basedir       => '/path/to/backpan'
      releases_only => 0 | 1,
      output        => 'backpan-index.txt',
      order         => 'dist' # or 'author' or 'age'


BackPAN::Index::Create provides a function create_backpan_index() that will create a text index file for a BackPAN CPAN mirror. A BackPAN CPAN mirror is like a regular CPAN mirror, but it has everything that has ever been released to CPAN. The canonical BackPAN mirror is

By default the generated index will look like this:

 authors/id/B/BA/BARBIE/Acme-CPANAuthors-British-1.01.meta.txt 1395991503 1832
 authors/id/B/BA/BARBIE/Acme-CPANAuthors-British-1.01.readme.txt 1395991503 1912
 authors/id/B/BA/BARBIE/Acme-CPANAuthors-British-1.01.tar.gz 1395991561 11231

The first line is a comment that identifies the revision number of the index format. For each file in the BackPAN mirror the index will then contain one line. Each line contains three items:

  • path

  • timestamp

  • size (in bytes)

You can see indexes created using this module on the CPAN Testers BackPAN, the home page of which also has more information about BackPAN mirrors.


The supported arguments are all shown in the SYNOPSIS.


The path to the top of your BackPAN repository, without a trailing slash.


If the releases_only option is true, then the index will only contain release tarballs, and the paths won't include the leading authors/id/:

 B/BA/BARBIE/Acme-CPANAuthors-British-1.01.tar.gz 1395991561 11231


The path to the file where the index should be generated. If the file already exists, it will be over-written.


Specifies what order the entries should be written to the index in. Currently supported values are:

  • 'dist'

    Entries are sorted first by dist name (as determined by CPAN::DistnameInfo, and then by age. This means that when processing the file, you'll see entries dist by dist, and within each dist you'll see them in order they were released.

  • 'author'

    Entries are sorted first by author, and then by filename. This will cluster files from the same release.

  • 'age'

    Entries are sorted first by age, and then by filename. Given that filenames are unique on CPAN, this should give a deterministic result for a specific BackPAN.

The supported sort orders are defined by plugins in the BackPAN::Index::Create::OrderBy namespace.,, and are included in the base distribution. If you have installed additional plugins, they'll be automatically available.

Note: CPAN::DistnameInfo doesn't handle paths for files other than tarballs, so if you generate a full index, you may not get the results you expect.

Note for Windows users

On Windows the generated index will use '/' as the directory separator, as I think that's the right thing to do. Please let me know if you think I'm wrong.


create-backpan-index - a script that provides a command-line interface to this module, included in the same distribution.

BackPAN::Index - an interface to an alternate BackPAN index.

CPAN Testers BackPAN - one of the BackPAN mirrors. It provides four different indexes that are generated using this module. The script used to generate these can be found in the examples directory of this distribution.



Neil Bowers <>


This software is copyright (c) 2014 by Neil Bowers <>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.