VII. - How to mirror CPAN.

Perl is a high-level programming language with an eclectic heritage
written by Larry Wall and a cast of thousands. It derives from the
ubiquitous C programming language and to a lesser extent from sed, awk, the
Unix shell, and at least a dozen other tools and languages. Perl's process,
file, and text manipulation facilities make it particularly well-suited for
tasks involving quick prototyping, system utilities, software tools, system
management tasks, database access, graphical programming, networking, and
web programming. These strengths make it especially popular with
system administrators and web developers, but mathematicians,
geneticists, journalists, and even managers also use Perl. Maybe you
should, too.

Perl 5 and Perl 6 are two languages in the Perl family, but of different
lineages. Perl 6 is not intended primarily as a replacement for Perl 5,
but as its own thing - and libraries exist to allow you to call Perl 5 code
from Perl 6 programs and vice versa.

CPAN is also the name of a Perl module, CPAN.pm, which is used to
download and install Perl software from the CPAN archive. This FAQ covers
only a little about the CPAN module and you may find the documentation for
it by using perldoc CPAN via the command line or on the web at
https://metacpan.org/pod/CPAN.

PAUSE is the Perl
Authors Upload SErver, a registry for Perl module,
script and documentation authors to upload their work to the CPAN. CPAN and
PAUSE are often used interchangeably but they are distinct from each other.
The CPAN.pm documentation explains it rather simply;

In this discussion CPAN and PAUSE have become equal -- but they are
not. PAUSE is authors/, modules/ and scripts/. CPAN is PAUSE plus the
clpa/, doc/, misc/, ports/ and src/.

CPAN works with the generosity and cooperation of thousands of developers,
over 257 participating mirrors, many companies,
institutions and individuals donating the network bandwidth, storage space
and computing power, volunteers who help keep everything together and users
whose interest in Perl keep the archive alive and growing.

After an author uploads their module to PAUSE, it will be mirrored to CPAN once an
hour and from there, to the rest of the mirrors around the world. There are
people who advise authors on their choice of name and namespace for their
modules and a few others who answer questions and investigate issues sent
to cpan@perl.org.

Perl changed the version numbering system with v5.6.0 as was indicated in
the release announcement:

Perl v5.6.0 is a major release that incorporates all maintenance and
development changes since the last major release, 5.005. As you may have
noticed, the version numbering has changed. Releases will henceforth be
numbered as revision.version.subversion triples. Maintenance releases will
have an even version component, while the version component for development
releases will be odd. For example, the next maintenance update of Perl
5.6.0 will be v5.6.1, and the development series will begin life at
v5.7.0.

You may also peruse the perlhist manpage for a complete list of
versions and their release dates.

To build Perl you need a C compilation environment. After downloading the
source code and opening it up, you should first read the INSTALL document
which will detail how to build Perl on most systems. There are a number of
README.[platform] for platforms where special care is needed in building
Perl. As always, reading the documentation is a Good Thing[tm].

Perl can be installed using the standard source code distribution on almost
all platforms Perl runs on. This includes all the UNIXes (and good
lookalikes, meaning POSIX environments like OS/2, Plan 9, QNX, Amiga,
MPE/iX, VMS, OS390, Stratus VOS), and Microsoft platforms. The most notable
exceptions are (as of 1999-Mar-24);

Due to the ever increasing number of modules on CPAN, the CPAN search
engine is possibly a better starting point in your quest for code,
especially if you already know exactly what you are looking for.

Installing a new module can be as simple as typing perl -MCPAN -e
'install Chocolate::Belgian'. The CPAN.pm documentation has more
complete instructions on how to use this convenient tool. If you are
uncomfortable with having something take that much control over your
software installation, or it otherwise doesn't work for you, the perlmodinstall
documentation covers module installation for UNIX, Windows and Macintosh in
more familiar terms.

Finally, if you're using ActivePerl on Windows, the PPM (Perl
Package Manager) has much of the same functionality as CPAN.pm.

Each time a module is installed on your system, it appends
information like the following to a file called
perllocal.pod which can be found in
/usr/local/lib/perl5/version number/architecture/ or
something akin to that. The path for your specific installation is
in your @INC which you can divine with perl -V.

This is pmtools -- a suite of small programs to help manage modules.
The names are totally preliminary, and in fact, so is the code. We follow
the "keep it small" notion of many tiny tools each doing one thing well,
eschewing giant megatools with millions of options.

http://www.cpan.org/ports/index.html
is a current list of Perl binaries that we are aware of at this time. If
you have a package for a platform, send us a URL. We do not endorse nor
guarantee these packages nor do we store them locally on CPAN due to the
potential size of the archive if we did.

Most, though not all, modules on CPAN are licensed under the GNU Public
License (GPL) or the Artistic license and should be stated in the
documentation that accompanies the module itself. If the license is not
specifically stated in the module, you can always write the author to
clarify the issue for you. Also, the text of the Artistic license and the
GNU Public License are included in the root directory of the source
distribution. From the 'README' file that comes with Perl:

Perl Kit, Version 5.0
Copyright 1989-1999, Larry Wall
All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of either:
a) the GNU General Public License as published by the Free
Software Foundation; either version 1, or (at your option) any
later version, or
b) the "Artistic License" which comes with this Kit.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
the GNU General Public License or the Artistic License for more details.
You should have received a copy of the Artistic License with this
Kit, in the file named "Artistic". If not, I'll be glad to provide one.
You should also have received a copy of the GNU General Public License
along with this program in the file named "Copying". If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307, USA or visit their web page on the internet at
http://www.gnu.org/copyleft/gpl.html.
For those of you that choose to use the GNU General Public License,
my interpretation of the GNU General Public License is that no Perl
script falls under the terms of the GPL unless you explicitly put
said script under the terms of the GPL yourself. Furthermore, any
object code linked with perl does not automatically fall under the
terms of the GPL, provided such object code only adds definitions
of subroutines and variables, and does not otherwise impair the
resulting interpreter from executing any standard Perl script. I
consider linking in C subroutines in this manner to be the moral
equivalent of defining subroutines in the Perl language itself. You
may sell such an object file as proprietary provided that you provide
or offer to provide the Perl source, as specified by the GNU General
Public License. (This is merely an alternate way of specifying input
to the program.) You may also sell a binary produced by the dumping of
a running Perl script that belongs to you, provided that you provide or
offer to provide the Perl source as specified by the GPL. (The
fact that a Perl interpreter and your code are in the same binary file
is, in this case, a form of mere aggregation.) This is my interpretation
of the GPL. If you still have concerns or difficulties understanding
my intent, feel free to contact me. Of course, the Artistic License
spells all this out for your protection, so you may prefer to use that.

Many CPAN filenames end in .tar.gz. Unfortunately some programs mutilate
such names (e.g., rename them with _tar.tar) so that unpacking programs
don't recognise them and refuse to unpack them. Try saving the file using
the .tgz suffix or try changing your web client. Also, you could try a
plain FTP client as almost all the CPAN sites are ftp-reachable. You can
find the full list of mirrors http://www.cpan.org/SITES.html

If you use FTP remember to download in binary format, not text format.

Please read http://www.cpan.org/ENDINGS if you aren't
sure what the files should be unpacked with and want to know if you are
using the right program.

If you still think you have a corrupt file, try downloading the file from
another site. If you still have no satisfaction, then please let us know
the exact file name and URL/FTP site and path.

We at CPAN are not a helpdesk. We may point you towards a plethora of
documentation to help you in your quest for knowledge but we cannot debug
your code or read for you. We exist specifically to answer questions and
solve problems relating directly to the functioning of the CPAN itself.

In addition to the on-line documentation you might try the newsgroup
comp.lang.perl.modules for help with a particular module. Also, looking at
other code using the same module might prove enlightening.

In general modules and scripts come with their own documentation which
should have been installed along with your module/script. (Thanks to Perl's
pod-style documentation, "it is very hard to misplace your
documentation".)

No. Everything on CPAN is free of charge. The reason for this is that CPAN
is the product of hundreds of people donating their time and resources for
the common good of the Perl community. There are places on the net where
one can offer shareware without treading on the generosity of others and
this is not that place.

If the documentation is for a particular module that isn't a core
distribution module, then please send it to the module author. If the
module is a core module the most appropriate place to send doc patches and
enhancements is the Perl5Porters mailing list.

Always remember to make your bug reports as detailed as possible. "Perl
doesn't work." is not a bug report.
Please note that problems concerning modules that are installed separately
from the Perl distribution (such as Tk) are reported differently.

Here is a checklist from perlbug, a bug reporting tool
included in your Perl distribution. It is a bit on the long side, but
please read it carefully as the better your bug report is, the more likely
the issue will be addressed.

What version of Perl you are running?

Try perl -v at the command line to find out.

Are you running the latest released version of perl?

Look at http://www.perl.com/
to find out. If it is not the latest released version, get that one
and see whether your bug has been fixed. Note that bug reports
about old versions of Perl, especially those prior to the 5.0
release, are less likely to be incorporated into the source as
Perl1 through Perl4 are largely unmaintained.

Are you sure what you have is a bug?

A significant number of the bug reports we get turn out to be
documented features in Perl. Make sure the behavior you are
witnessing doesn't fall under that category, by glancing through
the documentation that comes
with Perl (we'll admit this is no small task, given the sheer
volume of it all, but at least have a look at the sections that
seem relevant).

Be aware of the familiar traps that perl programmers of various
hues fall into. See the perltrap documentation.

Check in perldiag to see what
any Perl error message(s) mean. If message isn't in perldiag, it
probably isn't generated by Perl. Consult your operating system
documentation instead.

If you are on a non-UNIX platform check also perlport documentation,
some features may not be implemented or work differently.

Try to study the problem under the Perl debugger,if necessary. See
the perldebug
documentation.

Do you have a proper test case?

The easier it is to reproduce your bug, the more likely it will be
fixed, because if no one can duplicate the problem, no one can fix
it. A good test case has most of these attributes: fewest possible
number of lines; few dependencies on external commands, modules, or
libraries; runs on most platforms unimpeded; and is
self-documenting.

A good test case is almost always a good candidate to be on the
perl test suite. If you have the time, consider making your test
case so that it will readily fit into the standard test suite.

Remember also to include all the exact error messages, if any.
"Perl complained something" is not an exact error message.

If you get a core dump (or equivalent), you may use a debugger
(dbx, gdb, etc) to produce a stack trace to include in the bug
report. NOTE: unless your Perl has been compiled with debug info
(often -g), the stack trace is likely to be somewhat hard to use
because it will most probably contain only the function names and
not their arguments. If possible, recompile your Perl with debug
info and reproduce the dump and the stack trace.

Can you describe the bug in plain English?

The easier it is to understand a reproducible bug, the more likely
it will be fixed. Anything you can provide by way of insight into
the problem helps a great deal. In other words, try to analyze the
problem (to the extent you can) and report your discoveries.

Can you fix the bug yourself?

A bug report which includes a patch to fix it will almost
definitely be fixed. Use the diff program to generate your patches
(diff is being maintained by the GNU folks as part of the diffutils
package, so you should be able to get it from any of the GNU
software repositories). If you do submit a patch, the cool-dude
counter at perlbug@perl.com will register you as a savior of the
world. Your patch may be returned with requests for changes, or
requests for more detailed explanations about your fix.

Here are some clues for creating quality patches:
Use the -c or -u switches to the diff program (to create a
so-called context or unified diff). Make sure the patch is not
reversed (the first argument to diff is typically the original
file, the second argument your changed file). Make sure you test
your patch by applying it with the patch program before you send it
on its way. Try to follow the same style as the code you are trying
to patch. Make sure your patch really does work (make test, if the
thing you're patching supports it).

Can you use perlbug to submit the report?

perlbug will, amongst other things, ensure your report includes
crucial information about your version of perl. If perlbug is
unable to mail your report after you have typed it in, you may have
to compose the message yourself, add the output produced by perlbug
-d and email it to perlbug@perl.com. If, for some reason, you
cannot run perlbug at all on your system, be sure to include the
entire output produced by running perl -V (note the uppercase V).

Whether you use perlbug or send the email manually, please make
your Subject line informative. "a bug" is not informative. Neither
is "perl crashes" nor "HELP!!!" These don't help. A compact
description of what's wrong is fine.

Having done your bit, please be prepared to wait, to be told the
bug is in your code, or even to get no reply at all. The Perl
maintainers are busy folks, so if your problem is a small one or if
it is difficult to understand or already known, they may not
respond with a personal reply. If it is important to you that your
bug be fixed, do monitor the Changes file in any development
releases since the time you submitted the bug, and encourage the
maintainers with kind words (but never any flames!). Feel free to
resend your bug report if the next released version of perl comes
out and your bug is still present.

Please contact the author of the module/script, ideally by
creating a ticket using the bug tracker for the module (linked as 'Bugs' from
metacpan.org).
The author should be automatically notified by email.

If the author doesn't respond, the documentation of the module/script might
contain a contact address or you can try CPANID@perl.org where
CPANID is the authors CPANID.

Most of the checklist in reporting bugs in
Perl above applies for modules as well. Make your bug report as good as
possible if you really want the bug fixed. If the module is included with
the Perl distribution you should also follow the Perl bug reporting tips.

Sometimes a module goes unmaintained for a while due to the author pursuing
other interests, being busy, etc. and another person needs changes applied
to that module and may become frustrated when their bug reports and emails
goes unanswered.
CPAN does not mediate or dictate a policy in this situation and rely on the
respective authors to work out the details. If you treat other authors as
you would like to be treated in the same situation the manner in which you
go about dealing with such problems should be obvious.

Give it time. If you need changes made immediately, consider applying
your patches to the current module, changing the version and requiring that
version for your application. Eventually the author will turn up and apply
your patches, offer you maintenance of the module or, if the author doesn't
respond in a year, you may get maintenance by having interest.

If you need changes in order for another module or application to work,
consider making the needed changes and bundling the new version with your
own distribution and noting the change well in the documentation. Do not
upload the new version under the same namespace to CPAN until the matter
has been resolved with the author or CPAN.

Simply keep in mind that you are dealing with a person who invested time
and care into something. A little respect and courtesy go a long way.

The easiest way to take over a module is to have the current module
maintainer either make you a co-maintainer or transfer the module to you.

If you can't reach the author for some reason (e.g. email bounces), the
PAUSE admins at modules@perl.org can help. The PAUSE admins treat each case
individually.

Please make sure you have tried all of the above ways of getting in contact
with the author before going this way!

Get a login for the Perl Authors Upload Server (PAUSE) if you don't
already have one: http://pause.perl.org

Write to modules@perl.org explaining what you did to contact the
current maintainer including all email addresses of the author in cc
and links to the tickets you have opened.
The PAUSE admins will also try to reach the maintainer.

Post a public message in a heavily trafficked site announcing your
intention to take over the module. Potential places are
http://blogs.perl.org/, http://www.perlmonks.org/, and any appropriate
mailing lists or web forums.

Wait a bit. The PAUSE admins don't want to act too quickly in case the
current maintainer is on holiday. If there's no response to private
communication or the public post, a PAUSE admin can transfer it to you.

Yes, through the diligence of Paul Schinder and a few others, we have
CPAN Testers which is a collection
of test results for modules on a number of different platforms. This
information is also available when viewing module information on
Metacpan.