#!/usr/bin/perl
use strict;
use warnings;

use Log::Report       'cpan-site', syntax => 'SHORT';
use File::Basename    qw/basename/;
use Getopt::Long      qw/GetOptions :config gnu_getopt/;
use CPAN::Site::Index qw/cpan_index cpan_mirror/;

# the server will redirect you to a mirror
use constant CPAN_CORE => 'ftp://ftp.cpan.org/pub/CPAN';

#
# Collect options
#

my $lazy;
my $mode        = 0;
my $global_cpan = $ENV{CPANSITE_GLOBAL} || CPAN_CORE;
my $mycpan      = $ENV{CPANSITE_LOCAL}  || $ENV{CPANSITE};
my $stand_alone = 0;
my $undefs      = 1;

GetOptions
    'cpan|c=s'   => \$global_cpan
  , 'lazy|l!'    => \$lazy
  , 'verbose|v+' => \$mode
  , 'mode|m=s'   => \$mode
  , 'site|s=s'   => \$mycpan
  , 'stand-alone|a!' => \$stand_alone
  , 'undefs|u!'  => \$undefs
    or exit 1;

defined $lazy or $lazy = 1;

dispatcher mode => $mode, 'ALL'
    if $mode;

my $action = shift;
defined $action
    or error __x"Missing action. Usage {program} [OPTIONS] ACTION"
         , program => $0;

if($action eq 'version')
{   print "$CPAN::Site::Index::VERSION\n";
    exit 0;
}

if($action eq 'index')
{   $mycpan = shift @ARGV if @ARGV;
    $mycpan
        or error __x"specify top-directory of your archive as argument";

    $mycpan    =~ s!^file:(?://)?!!;
    -d $mycpan
        or fault __x"archive directory '{dir}'", dir => $mycpan;

    cpan_index $mycpan, $global_cpan
      , lazy     => $lazy
      , fallback => !$stand_alone
      , undefs   => $undefs;
    exit 0;
}

if($action eq 'mirror')
{   $mycpan
        or error __x"set CPANSITE_LOCAL in environment or use --site option";

    @ARGV
        or error __x"list of module names expected";

    cpan_mirror $mycpan, $global_cpan, \@ARGV;
    exit 0;
}

error __x"action '{name}' does not exist (anymore)", name => $action;

__END__

=head1 NAME

cpansite -- extend CPAN with private packages

=head1 SYNOPSIS

 cpansite version
 cpansite [OPTIONS] index
 cpansite [OPTIONS] mirror PACKAGE

  OPTIONS:                                  via %ENV:
    --verbose  -v -vv -vvv --mode=DEBUG
    --no-lazy       redo everything
    --cpan <url>    some CPAN mirror        CPANSITE_GLOBAL
    --site <dir>    local archive directory CPANSITE_LOCAL
    --stand-alone   no fallback to global CPAN
    --no-undefs     do not include "undef" versions in index

=head1 DESCRIPTION

B<WARNING: A lot has changed with the 1.01 release.  Please read more
about these changes in the file "explain_101.txt" included in the
distribution.>

The C<cpansite> script is used to create your own CPAN server. The
logic is implemented in L<CPAN::Site::Index> which you may use directly.
You only need to install this module on one server in your network.

There are two kinds of local CPANs which can be constructed with this
software:

=over 4

=item 1. local CPAN with fallback to the global CPAN

When you generate a new index for your local set-up, the default
behavior is to merge that knowledge with the global CPAN. When you
install a module on a client, it will first attempt to fetch it from
your own set-up. If not found, it will automatically continue to
look at the global CPAN.

=item 2. pure local CPAN, without fallback

When you choose to generate the index without fallback, the installation
of a module will fail when you do not have a local copy of the module
in your set-up. You can use the C<mirror> action to collect the latest
version of a module into your own structure.

=back

=head2 Indexing options

The following options are available with all actions:

=over 4

=item --verbose -v -vv -vvv --mode=DEBUG

Produce verbose output via L<Log::Report>.

=item --site <dir>  or  -s <dir>  or   $CPANSITE_LOCAL

The location of your local CPAN archive set-up.

Example:
  export CPANSITE_LOCAL="/www/websites/cpan.example.com"
  cpansite index

  cpansite --site $CPANSITE_LOCAL index  # alternative

=item --cpan <url>  or  -c <url>  or   $CPANSITE_GLOBAL

Update the list of "real" CPAN modules regularly (daily or more) from
this url. By default, C<ftp:///ftp.cpan.org> is addressed which
redirects to a server close to you.

=item --stand-alone or  -a

The "real" CPAN list is not included.  For instance, if you have
downloaded all the releases from CPAN that you need, and you do not want
unexpected extra downloads.  The downloaded versions will prevail over
newer releases on CPAN, but you may download modules from the core CPAN
that you do not expect.

=item --no-lazy     or --lazy  or   -l

Try to avoid redo-ing everything.  By default, the indexer is
lazy: it will process only new distributions.  When not lazy, all
distributions on the local disk are processed and a new table is
created.  The default of this option was reversed with release 1.00
of C<CPAN::Site>.

=item --no-undefs   or --undefs or -u

Whether to include package names with "undef" version in the packages
list. Those packages cannot be used for dependencies, so are hardly
useful.

=back

=head1 DETAILS

=head2 Configuring the Clients

To get in touch with your own cpan archive, you have to explicitly provide
an url to it.  Add this to your C<CPAN.pm> configuration file (usually
F<~/.cpan/CPAN/MyConfig.pm>) option C<urllist>.  B<There is no need to
install the CPAN::Site software on your clients since release 1.01>.

You probably also want to set the variable C<index_expire> to very short:
the clients need to reload your local index as soon as possible, and not
wait a day; just after your new local release is put in your local index,
it must get visible to your client.

You may also consider to have the CPAN install cache to be cleaned
by the system.  Certainly when you set the cache size larger (required
for more complex recursive installations) it is nice to have it removed
after a (short) while.  Set C<keep_source_where> to a temporary
directory.

Example for  F<~/.cpan/CPAN/MyConfig.pm>

 $CPAN::Config =
  { ...
  , index_expire      => 1/600     # 5 minutes
  , urllist => [ $MYCPAN_URL, $BIGCPAN_MIRROR ]
  , keep_source_where => '/tmp/cpan-cache'
  , build_cache       => 100       # MegaByte cache
  , ...
  };

To avoid manually editing the CPAN config file one can also set the
MYCPAN_URL from the shell:

  cpan> o conf urllist unshift $MYCPAN_URL
  cpan> o conf index_expire 0.001  # 86 seconds
  cpan> o conf commit

=head2 Configuring the Server

=head3 Starting your own CPAN

You have to have a ftp or http server running. Create a directory
where you will distribute the data from, here named C<$MYCPAN>.
With a web-server, it is adviced to create a virtual host like
C<cpan.example.com> which has C<$MYCPAN> as DocumentRoot.

Define a fake pause-id (here the demo is MYID), because if you use
an existing pause-id you clients will start producing warnings about
missing checksums on files retreived for the public archive.

  MYMODS=$MYCPAN/authors/id/M/MY/MYID
  mkdir -p $MYMODS

Although CPAN.pm claims to support a directory format of
C<$MYCPAN/authors/id/MYID>, experience shows that this does not
work correctly with some recursively dependencies.

=head3 Adding your own modules to the local archive

Put your own modules in C<$MYMODS> and then rerun the indexer.

  mv MyDist-1.00-tar.gz $MYMODS   # local
  scp MyDist-1.00-tar.gz cpan.example.com:$MYMODS

=head3 Generating an index with fallback

Your own software probably depends on a lot of modules which are
found on the global CPAN.  And those modules require even more
modules from CPAN.  By default, your local CPAN index will know
about all modules which you have yourself plus all module on
the global CPAN.

The index only contains the last (highest) version of each file
(which means that each file must contain a version number otherwise the
text C<undef> is used for version)  In any case, the local packages get
preference over the global CPAN packages, even when they have a lower
version number.

With fallback:

 cpansite --site $MYCPAN index
 cpansite index    # when   CPANSITE_LOCAL=$MYCPAN

The script traverses I<$MYCPAN>F</authors/id> and merges this with the
I<$MYCPAN>F</global/02packages.details.txt.gz> data, a copy from the
original CPAN.  It creates a C<CHECKSUMS> file.  The result is a private
I<$MYCPAN>F</modules/02packages.details.txt.gz> file.

The files F<$MYCPAN/authors/01mailrc.txt.gz> and
F<$MYCPAN/modules/03modlist.data.gz> are downloaded from CPAN.  This
will reduce the number of failing retreivals when you start installing
software.

=head3 Generating an index without fallback

When you wish for a controled environment, where all your systems
run the same versions of the modules, you should disable the fallback
to the global CPAN.

Without fallback:

 cpansite --site $MYCPAN --stand-alone index
 cpansite --stand-alone index    # when   CPANSITE_LOCAL=$MYCPAN

The index is now very small.  But when you start installing your software
on systems, it will start complaining that the module cannot be found on
CPAN.  Now, add specific distribution versions from the global CPAN to
your own archive.  See next section.

=head3 Adding distributions from global CPAN to your own

When you want a fixed distribution version to be used on your systems,
you can manually download them and insert them in the C<$MYCPAN> tree.

However, there is also a simple way to retrieve the most recent version.
The next example shows how to insert the latest versions of the
distributions which include the packages Mail::Box and Test::More into
your local CPAN archive.

 cpansite --site $MYCPAN --cpan $GLOBAL mirror Mail::Box Test::More

 # when CPANSITE_LOCAL=$MYCPAN and CPANSITE_GLOBAL=$GLOBAL
 cpansite mirror Mail::Box Test::More

=head1 AUTHORS

Mark Overmeer E<lt>perl@overmeer.netE<gt>.

=cut