Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CPANSITE(1)	      User Contributed Perl Documentation	   CPANSITE(1)

       cpansite	-- extend CPAN with private packages

	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
	   --env-proxy	   read	additional proxy settings
	   --site <dir>	   local archive directory     CPANSITE_LOCAL
	   --stand-alone   no fallback to global CPAN
	   --no-undefs	   do not include "undef" versions in index

       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

       The "cpansite" script is	used to	create your own	CPAN server. The logic
       is implemented in 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

       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.

       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 "mirror" action
	   to collect the latest version of a module into your own structure.

   Indexing options
       The following options are available with	all actions:

       --verbose -v -vv	-vvv --mode=DEBUG
	   Produce verbose output via Log::Report.

       --site <dir>  or	 -s <dir>  or	$CPANSITE_LOCAL
	   The location	of your	local CPAN archive set-up.

	     export CPANSITE_LOCAL="/www/websites/"
	     cpansite index

	     cpansite --site $CPANSITE_LOCAL index  # alternative

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

	   Let LWP::UserAgent read the proxy settings from environment
	   variables.  See the according method	in that	manual page.

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

       --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 "CPAN::Site".

       --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 but included by default.

   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 "" configuration file
       (usually	~/.cpan/CPAN/ option "urllist".  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 "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

       Example for  ~/.cpan/CPAN/

	$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

   Configuring the Server
       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 $MYCPAN.  With a web-
       server, it is adviced to	create a virtual host like ""
       which has $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.

	 mkdir -p $MYMODS

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

       Adding your own modules to the local archive

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

	 mv MyDist-1.00-tar.gz $MYMODS	 # local
	 scp MyDist-1.00-tar.gz$MYMODS

       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
       "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 $MYCPAN/authors/id and merges this with the
       $MYCPAN/global/02packages.details.txt.gz	data, a	copy from the original
       CPAN.  It creates a "CHECKSUMS" file.  The result is a private
       $MYCPAN/modules/02packages.details.txt.gz file.

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

       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.

       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 $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

	cpansite mirror	Mail::Box Test::More

       Mark Overmeer <>.

perl v5.24.1			  2012-11-15			   CPANSITE(1)


Want to link to this manual page? Use this URL:

home | help