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" head1, 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'
Not all versions of CPAN.pm work correctly; you may need to upgrade that first.
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" head1 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
Alex Efros contributed a shorter description of how to get things to work. You can find this in the CPAN::Site manual page.
Configuration
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:
MYCPAN=/location/of/my/data/on/disk
cpansite -vl index $MYCPAN
The script traverses $MYCPAN/authors/id and merges this with the $MYCPAN/modules/02packages.details.txt.gz data, a copy from the original CPAN. It creates a CHECKSUMS
file, and README files from each tar-ball. The result is a $MYCPAN/site/02packages.details.txt.gz file.
The files $MYCPAN/authors/01mailrc.txt.gz and $MYCPAN/modules/03modlist.data.gz are downloaded from CPAN. This will reduce the number of failing retreivals when you start installing software.
Adding your own modules to the local archive
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)
AUTHORS
Mark Overmeer <perl@overmeer.net>. Original implementation by Ulrich Pfeifer <pfeifer@wait.de>.