NAME

cpansite -- extend CPAN with private packages

SYNOPSIS

 cpansite [OPTIONS] index [MYCPAN]
 cpansite [OPTIONS] install PACKAGE
 cpansite [OPTIONS] [shell]

  General options:
    --verbose  -v     be verbose
               -vv    debug output

  Indexing options:
    --lazy     -l     try to avoid redo-ing everything
    --cpan <url>      some CPAN mirror

DESCRIPTION

The cpansite script (old name mkpackages) can be used (on the server) to create the required extended CPAN index, and (on the clients) to install those modules. Before it can be used, you need some minor configuring, explained in the "DETAILS" chapter, below in this manual page.

Without any arguments, a CPAN install shell is started. Besides, an abbreviation for install is available. Other uses for the CPAN.pm module are only supported in the traditional way:

  perl -MCPAN::Site 'something'

General options

The following options are available in all modes:

--verbose or -v

Produce verbose output, just enough to follow what is happening globally. There will not be a flood of distribution names or packages, only processing steps.

-vv

Produce a detailed trace, including decissions why some packages are picked or not, and where distributions are considered to be new or not.

$CPANSITE

The CPANSITE environment variable contains a list of white-space seperated urls which will be added before the list of url in the personal CPAN.pm configuration file .cpan/CPAN/MyConfig.pm

Example:

  export CPANSITE="http://mycpan.example.com/local"
  perl -MCPAN::Site -e shell
  cpansite shell              # alternative

Indexing options (mode index)

In "index mode", this script generates the required index for your own local CPAN additions. See the "DETAILS" chapter below. You can either specify a directory which contains your cpan tree, or an environment variable named CPANSITE.

Additional options for "index" mode:

--lazy or -l

Try to avoid redo-ing everything: without this flag, all distributions on the local disk are processed and a new table is created. With this flag, the process tries to handle only new distributions.

--cpan <url>

Update the list of "real" CPAN modules regularly (daily) from this url. By default, the slow but most up-to-date CPAN source at ftp.cpan.org is used.

When this flag is explicitly empty cpansite --cpan '' index

then 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.

DETAILS

Configuring the clients

To get in touch with your own cpan archive, you have to provide an url to it. Either add this to your CPAN.pm configuration file (usually .cpan/CPAN/MyConfig.pm) option urllist or set the environment variable CPANSITE.

You probably also want to set the variable 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 keep_source_where to a temporary directory.

Example for .cpan/CPAN/MyConfig.pm

 $CPAN::Config =
  { ...
  , index_expire => 1/600    # 5 minutes
  , urllist => [ MYCPAN_URL, 'ftp://ftp.cpan.org/pub/CPAN' ]
  , 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 commit

Generating an index

Where the local index is the sole search list used at the client site, it will contain both your own packages and all of the other packages listed on CPAN. You will need to rerun the indexing on regular basis (for instance one a day) to keep in sync with CPAN, for instance with cron.

The output will only contain the last (highest) version of each file (which means that each file must contain a version number otherwise the text 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.

Example:

 cpansite -vl index $MYCPAN

The script traverses $CPANSITE/authors/id and generates the $CPANSITE/modules/02packages.details.txt.gz and CHECKSUMS files. It also will extract README files from the tar-balls in the /authors/id directories.

Created is the long index file MYCPAN/site/02packages.details.txt.gz. An empty MYCPAN/site/01mailrc.txt.gz and MYCPAN/site/03modlist.data.gz are generated as well: most people do not use those (anymore) so why bother?

MYCPAN/authors/id/**/CHECKSUMS fiels are generated in all directories below MYCPAN/autors/id/.

In MYCPAN/modules/**, files from the "real" CPAN are cached.

Adding your own modules to the local archive

Not all versions of CPAN.pm work correctly; you may need to upgrade that first.

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.

  mkdir -p MYCPAN/authors/id/M/MY/MYID
  mv MyDist-1.00-tar.gz MYCPAN/authors/id/M/MY/MYID
  cpansite -v -l index MYCPAN

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

SEE ALSO

CPAN::Site(3pm), CPAN::Site::Index(3pm)

AUTHORS

Mark Overmeer <perl@overmeer.net>. Original implementation by Ulrich Pfeifer <pfeifer@wait.de>.

cpanm CPAN::Site

perl -MCPAN -e shell
install CPAN::Site