NAME

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

SYNOPSIS

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

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

DESCRIPTION

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 backpan.perl.org.

By default the generated index will look like this:

 #FORMAT 1
 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.

ARGUMENTS

The supported arguments are all shown in the SYNOPSIS.

basedir

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

releases_only

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/:

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

output

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

order

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. Dist.pm, Author.pm, and Age.pm 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.

SEE ALSO

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.

REPOSITORY

https://github.com/neilbowers/BackPAN-Index-Create

AUTHOR

Neil Bowers <neilb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Neil Bowers <neilb@cpan.org>.

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

cpanm BackPAN::Index::Create

perl -MCPAN -e shell
install BackPAN::Index::Create