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)

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.

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