view release on metacpan or  search on metacpan

lib/CPAN/Mirror/Tiny.pm  view on Meta::CPAN

=head1 SYNOPSIS

  use CPAN::Mirror::Tiny;

  my $cpan = CPAN::Mirror::Tiny->new(base => "./darkpan");

  $cpan->inject("https://cpan.metacpan.org/authors/id/S/SK/SKAJI/App-cpm-0.112.tar.gz");
  $cpan->inject("https://github.com/skaji/Carl.git");
  $cpan->write_index(compress => 1);

  # $ find darkpan -type f
  # darkpan/authors/id/S/SK/SKAJI/App-cpm-0.112.tar.gz
  # darkpan/authors/id/V/VE/VENDOR/Carl-0.01-ff194fe.tar.gz
  # darkpan/modules/02packages.details.txt.gz

=head1 DESCRIPTION

CPAN::Mirror::Tiny helps you create partial CPAN mirror (also known as DarkPAN).

There is also a command line interface L<cpan-mirror-tiny> for CPAN::Mirror::Tiny.

=head1 WHY NEW?

Yes, we already have great CPAN modules which create CPAN mirror.

L<CPAN::Mini>, L<OrePAN2>, L<WorePAN> ...

I want to use such modules in CPAN clients.
Actually I used OrePAN2 in L<Carl|https://github.com/skaji/Carl>,
which can install modules in github.com or any servers.

Then minimal dependency and no dependency on XS modules is critical.
Unfortunately existing CPAN mirror modules depend on XS modules.

This is why I made CPAN::Mirror::Tiny.

=head1 METHODS

=head2 new

  my $cpan = CPAN::Mirror::Tiny->new(%option)

Constructor. C< %option > may be:

=over 4

=item * base

Base directory for cpan mirror. If C<$ENV{PERL_CPAN_MIRROR_TINY_BASE}> is set, it will be used.
This is required.

=item * tempdir

Temp directory. Default C<< File::Temp::tempdir(CLEANUP => 1) >>.

=back

=head2 inject

  # automatically guess $source
  $cpan->inject($source, \%option)

  # or explicitly call inject_* method
  $cpan->inject_local('/path/to//Your-Module-0.01.tar.gz'', {author => 'YOU'});
  $cpan->inject_local_file('/path/to//Your-Module-0.01.tar.gz'', {author => 'YOU'});
  $cpan->inject_local_directory('/path/to/cpan/dir', {author => 'YOU'});

  $cpan->inject_http('http://example.com/Hoge-0.01.tar.gz', {author => 'YOU'});

  $cpan->inject_git('git://github.com/skaji/Carl.git', {author => 'SKAJI'});

  $cpan->inject_cpan('Plack', {version => '1.0039'});

Inject C< $source > to our cpan mirror directory. C< $source > is one of

=over 4

=item * local tar.gz path / directory

  $cpan->inject('/path/to/Module.tar.gz', { author => "SKAJI" });
  $cpan->inject('/path/to/dir',           { author => "SKAJI" });

=item * http url of tar.gz

  $cpan->inject('http://example.com/Module.tar.gz', { author => "DUMMY" });

=item * git url (with optional ref)

  $cpan->inject('git://github.com/skaji/Carl.git', { author => "SKAJI", ref => '0.114' });

=item * cpan module

  $cpan->inject('cpan:Plack', {version => '1.0039'});

=back

As seeing from the above examples, you can specify C<author> in C<\%option>.
If you omit C<author>, default C<VENDOR> is used.

B<CAUTION>: Currently, the distribution name for git repository is something like
C<S/SK/SKAJI/Carl-0.01-9188c0e.tar.gz>,
where C<0.01> is the version and C<9188c0e> is C<git rev-parse --short HEAD>.

=head2 index

  my $index_string = $cpan->index

Get the index (a.k.a. 02packages.details.txt) of our cpan mirror.

=head2 write_index

  $cpan->write_index( compress => bool )

Write the index to C< $base/modules/02packages.details.txt >
or C< base/modules/02packages.details.txt.gz >.

=head1 TIPS

=head2 How can I install modules in my DarkPAN with cpanm / cpm?