cpan-faq.html

[% 
  page.import({
    title   => "The CPAN Frequently Asked Questions",
    section => 'home',
    stub => '../',
  });

  PROCESS "tpl/data/cpan-stats";

%]

[% page.head = BLOCK %]
<!-- Copyright Jarkko Hietaniemi jhi@iki.fi 1998-2007,
     Ask Bjørn Hansen, Leo Lapworth 2011 All Rights Reserved
     You may distribute this document either under the Artistic License
     (comes with Perl) or the GNU Public License, whichever suits you.
     The CPAN Logo provided by J.C. Thorpe.
     You are not allowed to remove or alter these comments.
-->
[% END %]

<h1>
    CPAN Frequently Asked Questions
</h1>
<p>
    Here are some answers to the most common questions received by
    <tt>cpan@perl.org</tt>.
</p>
<p>
    For general information about Perl you should see the <a href=
    "http://www.perl.org/">Perl Home Page</a> (<tt>www.perl.org</tt>).
</p>
<p>
    See the Perl FAQ (especially for any Perl programming questions, but also
    for other resources), available at <a href=
    "http://perldoc.perl.org/index-faq.html">http://perldoc.perl.org/index-faq.html</a>.
</p>
<hr>
<h2>
    I. - General Questions.
</h2>
<ul>
    <li>
        <a href="#What_is_Perl">What is Perl?</a>
    </li>
    <li>
        <a href="#What_is_Perl6">What is Perl6?</a>
    </li>
    <li>
        <a href="#What_is_CPAN">What is the CPAN?</a>
    </li>
    <li>
        <a href="#What_is_PAUSE">What is PAUSE?</a>
    </li>
    <li>
        <a href="#How_does_the_CPAN_work">How does the CPAN work?</a>
    </li>
</ul>
<hr>
<h2>
    II. - The Quest for Perl source, modules and scripts.
</h2>
<ul>
    <li>
        <a href="#Where_Perl_source_code">Where can I find the current release
        of the Perl source code?</a>
    </li>
    <li>
        <a href="#Where_older_Perl">Where can I find older/obsolete versions of
        Perl or Perl Modules?</a>
    </li>
    <li>
        <a href="#What_versions_mean">How do I interpret the Perl version
        numbers?</a>
    </li>
    <li>
        <a href="#How_install_Perl_source">How do I install Perl from the
        source code?</a>
    </li>
    <li>
        <a href="#Where_find_Perl_modules">Where can I find Perl modules?</a>
    </li>
    <li>
        <a href="#How_install_Perl_modules">How do I install Perl modules?</a>
    </li>
    <li>
        <a href="#How_installed_modules">How do I find out what modules are
        already installed on my system?</a>
    </li>
    <li>
        <a href="#Where_recent_modules">Where can I find the most recently
        uploaded Perl modules?</a>
    </li>
    <li>
        <a href="#Where_find_modules_windows">Where can I find Perl modules for
        Windows?</a>
    </li>
    <li>
        <a href="#Where_find_binaries">Where can I find Perl binaries/packages
        or Perl module binaries?</a>
    </li>
    <li>
        <a href="#How_is_Perl_licensed">How are Perl and the CPAN modules
        licensed?</a>
    </li>
    <li>
        <a href="#What_modules_in_Perl_Dist">Does the Perl source distribution
        include any modules?</a>
    </li>
    <li>
        <a href="#Where_find_Perl_scripts">Where can I find Perl scripts?</a>
    </li>
</ul>
<hr>
<h2>
    III. - RIF [ Reading is Fun-duh-mental ]
</h2>
<ul>
    <li>
        <a href="#Where_find_Perl_FAQs">Where can I find the Perl FAQs?</a>
    </li>
    <li>
        <a href="#Where_find_Perl_documentation">Where can I find Perl
        documentation?</a>
    </li>
    <li>
        <a href="#Where_find_module_documentation">Where can I find Perl module
        documentation?</a>
    </li>
    <li>
        <a href="#Where_find_DBI_documentation">Where can I find Perl
        DBI/DBD/database documentation?</a>
    </li>
    <li>
        <a href="#Where_find_Perl_mailing_lists">Where can I find/join/create
        Perl mailing lists?</a>
    </li>
    <li>
        <a href="#Where_find_Perl_training">Where can I find Perl
        courses/training/on-line tutorials?</a>
    </li>
    <li>
        <a href="#How_join_mongers">How do I find/join/organise a Perl User
        Group?</a>
    </li>
    <li>
        <a href="#What_history_Perl">Where can I find a history of Perl
        releases or a general history of the Perl community?</a>
    </li>
</ul>
<hr>
<h2>
    IV. - Danger Will Robinson! Danger! Danger!
</h2>
<ul>
    <li>
        <a href="#Download_module_corrupt">I downloaded a module/script/file
        but it was corrupt, what should I do?</a>
    </li>
    <li>
        <a href="#Help_me_obi_wan">How do I use module Foo::Bar, can you help?
        (a.k.a. Are you a helpdesk?)</a>
    </li>
    <li>
        <a href="#What_search_down">I'm having trouble with search.cpan.org,
        whom do I need to contact?</a>
    </li>
</ul>
<hr>
<h2>
    V. - Searching CPAN.
</h2>
<ul>
    <li>
        <a href="#How_search_CPAN">How do I search CPAN?</a>
    </li>
    <li>
        <a href="#How_search_module_documentation">How do I search for
        module/script documentation? (a.k.a. "How do I use ..."?)</a>
    </li>
</ul>
<hr>
<h2>
    VI. - Contributing modules, patches, and bug reports.
</h2>
<ul>
    <li>
        <a href="#How_contribute_modules">How do I contribute modules to
        CPAN?</a>
    </li>
    <li>
        <a href="#Does_CPAN_allow_shareware">Does CPAN allow contributions of
        shareware or code that requests a fee of any kind?</a>
    </li>
    <li>
        <a href="#How_contribute_scripts">How do I contribute scripts to
        CPAN?</a>
    </li>
    <li>
        <a href="#How_contribute_documentation">How do I contribute
        documentation?</a>
    </li>
    <li>
        <a href="#How_report_bug_Perl">How do I report/fix a bug in Perl and/or
        its documentation?</a>
    </li>
    <li>
        <a href="#How_report_bug_module">How do I report/fix a bug in a
        module/script?</a>
    </li>
    <li>
        <a href="#How_maintain_module">How do I go about maintaining a module
        when the author is unresponsive?</a>
    </li>
    <li>
        <a href="#How_adopt_module">How do I adopt or take over a module
        already on CPAN?</a>
    </li>
    <li>
        <a href="#Where_is_testers">Is there a site for module bug
        reports/tests?</a>
    </li>
    <li>
        <a href="#Plans_for_statistics">Does CPAN provide download statistics
        for authors?</a>
    </li>
</ul>
<hr>
<h2>
    VII. - How to mirror CPAN.
</h2>
<ul>
    <li>
        <a href="how-to-mirror.html">How do I mirror CPAN?</a>
    </li>
</ul>
<hr>
<h3>
    <a name="What_is_Perl" id="What_is_Perl">What is Perl?</a>
</h3>
<p>
    From the Perl documentation:
</p>
<p>
    <cite>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.</cite>
</p>

<p>
    A good starting point for Perl information is <a href=
    "http://www.perl.org/">http://www.perl.org/</a>
</p>
<hr>
<h3>
    <a name="What_is_Perl6" id="What_is_Perl6">What is Perl6?</a>
</h3>
<p>
    Perl 5 and Perl 6 are two languages in the Perl family, but of different 
    lineages. Perl 6 is not a replacement for Perl 5, it is also not 
    currently production ready.
</p>
<p>
    You can get involved with Perl6 development at <a href=
    "http://dev.perl.org/perl6/">http://dev.perl.org/perl6</a>.
</p>
<p>
    "We're really serious about reinventing everything that needs reinventing."
    --Larry Wall
</p>
<hr>
<h3>
    <a name="What_is_CPAN" id="What_is_CPAN">What is CPAN?</a>
</h3>
<p>
    CPAN is the <b>C</b>omprehensive <b>P</b>erl <b>A</b>rchive <b>N</b>etwork,
    a large collection of Perl software and documentation. You can begin
    exploring from either <a href=
    "http://www.cpan.org/">http://www.cpan.org/</a> or any of the mirrors
    listed at <a href=
    "http://www.cpan.org/SITES.html">http://www.cpan.org/SITES.html</a>.
</p>
<p>
    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 <tt>perldoc CPAN</tt> via the command line or on the web at
    <a href=
    "http://search.cpan.org/dist/CPAN/lib/CPAN.pm">http://search.cpan.org/dist/CPAN/lib/CPAN.pm</a>.
</p>
<hr>
<h3>
    <a name="What_is_PAUSE" id="What_is_PAUSE">What is PAUSE?</a>
</h3>
<p>
    <a href="http://pause.cpan.org/">PAUSE</a> is the <b>P</b>erl
    <b>A</b>uthors <b>U</b>pload <b>SE</b>rver, 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;
</p>
<p>
    <cite>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/.</cite>
</p>
<p>
    See the question <a href="#How_contribute_modules">'How do I contribute
    modules?'</a> below if you want to become a registered PAUSE user.
</p>
<hr>

<h3>
    <a name="How_does_the_CPAN_work" id="How_does_the_CPAN_work">How does the
    CPAN work?</a>
</h3>
<p>
    CPAN works with the generosity and cooperation of thousands of developers,
    over [% cpan_stats.mirrors.count %] 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.
</p>
<p>
    After an author uploads their module to <a href=
    "http://pause.cpan.org/">PAUSE</a>, 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.
</p>

<hr>
<h3>
    <a name="Where_Perl_source_code" id="Where_Perl_source_code">Where can I
    find the current release of the Perl source code?</a>
</h3>
<ul>
    <li>
        <a href="http://www.cpan.org/src/">http://www.cpan.org/src/</a> - A
        detailed list of source code offerings.
    </li>
</ul>
<hr>
<h3>
    <a name="Where_older_Perl" id="Where_older_Perl">Where can I find
    older/obsolete versions of Perl or Perl Modules?</a>
</h3>
<p>
    Unless you have A Very Good Reason you shouldn't be installing obsolete
    versions because they might contain bugs, possibly even security bugs.
</p>
<p>
    Good Reasons may include having to support Perl 4 programs, trying to
    replicate a bug that requires an old Perl release, or pure joy of software
    archaeology. (Are you Perl 1 compliant?)
</p>
<p>
    CPAN does not carry all ancient releases and patchlevels of Perl (because
    of the bugs we mentioned above and because they would take quite a lot of
    storage space).
</p>
<ul>
    <li>
        <a href="http://backpan.perl.org/">http://backpan.perl.org/</a> - for
        old versions of modules
    </li>
</ul>
<hr>
<h3>
    <a name="What_versions_mean" id="What_versions_mean">How do I interpret the
    Perl version numbers?</a>
</h3>
<p>
    Perl changed the version numbering system with v5.6.0 as was indicated in
    the release announcement:
</p>
<p>
    <cite>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.</cite>
</p>
<p>
    You may also peruse the <tt>perlhist</tt> manpage for a complete list of
    versions and their release dates.
</p>
<hr>
<h3>
    <a name="How_install_Perl_source" id="How_install_Perl_source">How do I
    install Perl using the source code?</a>
</h3>
<p>
    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].
</p>
<p>
    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);
</p>
<ul>
    <li>MacOS (1)
    </li>
    <li>AS/400 (2)
    </li>
    <li>Novell Netware (2)
    </li>
</ul>
<p>
    For these platforms a binary release may be the easiest path.
</p>
<ol>
    <li>The source code to compile MacPerl is available at <a href=
    "http://www.cpan.org/ports/mac/">http://www.cpan.org/ports/mac/</a>.
    </li>
    <li>The source code for AS/400 and Netware Perls have not been merged to
    the main Perl source code distribution. If you want to try compiling them
    yourself, get the sources from <a href="http://www.cpan.org/ports/as400/">
        http://www.cpan.org/ports/As400/</a> or <a href=
        "http://www.cpan.org/ports/netware/">http://www.cpan.org/ports/netware/</a>
        and then continue at <a href=
        "http://www.cpan.org/src/README">http://www.cpan.org/src/README</a>
    </li>
</ol>
<hr>
<h3>
    <a name="Where_find_Perl_modules" id="Where_find_Perl_modules">Where can I
    find Perl modules?</a>
</h3>
<ul>
    <li>
        <a href=
        "http://www.cpan.org/modules/00modlist.long.html">http://www.cpan.org/modules/00modlist.long.html</a>
    </li>
    <li>
        <a href="http://www.metacpan.org/">http://www.metacpan.org/</a>
    </li>
    <li>
        <a href="http://search.cpan.org/">http://search.cpan.org/</a>
    </li>
</ul>
<p>
    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.
</p>
<hr>
<h3>
    <a name="How_install_Perl_modules" id="How_install_Perl_modules">How do I
    install Perl modules?</a>
</h3>
<p>
    Installing a new module can be as simple as typing <tt>perl -MCPAN -e
    'install Chocolate::Belgian'</tt>. The <a href=
    "http://perldoc.perl.org/cpan.html">CPAN.pm documentation</a> 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 <a href=
    "http://perldoc.perl.org/perlmodinstall.html">perlmodinstall</a>
    documentation covers module installation for UNIX, Windows and Macintosh in
    more familiar terms.
</p>
<p>
    Finally, if you're using ActivePerl on Windows, the <a href=
    "http://www.activestate.com/activeperl/ppm-perl-modules">PPM</a> (Perl
    Package Manager) has much of the same functionality as CPAN.pm.
</p>
<hr>
<h3>
    <a name="How_installed_modules" id="How_installed_modules">How do I find
    out what modules are already installed on my system?</a>
</h3>
<ul>
    <li>
        <tt>perldoc perllocal</tt>
        <p>
            Each time a module is installed on your system, it appends
            information like the following to a file called
            <tt>perllocal.pod</tt> which can be found in
            <tt>/usr/local/lib/perl5/version number/architecture/</tt> or
            something akin to that. The path for your specific installation is
            in your @INC which you can divine with <tt>perl -V</tt>.
        </p>
        <pre>
=head2 Wed May 12 13:42:53 1999: C&lt;Module&gt; L&lt;Data::Dumper&gt;

=over 4

=item *

C&lt;installed into: /usr/local/lib/perl5/5.00503&gt;

=item *

C&lt;LINKTYPE: dynamic&gt;

=item *

C&lt;VERSION: 2.101&gt;

=item *

C&lt;EXE_FILES: &gt;

=back
</pre>
        <p>
            Each entry includes the Module name, date and time it was
            installed, where it was installed, linktype [ static or dynamic ],
            version and executables, if any, included with the module.
        </p>
    </li>
    <li>ActivePerl has the PPM utility.
        <pre>
C:\&gt;ppm query
Archive-Tar   [0.072 ] module for manipulation of tar archives.
Compress-Zlib [1.03  ] Interface to zlib compression library
DBI           [1.13  ] Database independent interface for Perl
GD            [1.25  ] Interface to Gd Graphics Library
HTML-Parser   [2.23  ] SGML parser class
MIME-Base64   [2.11  ] Encoding and decoding of base64 strings
PPM           [1.1.4 ] Perl Package Manager: locate, install, upgrade software
</pre>
    </li>
    <li>The pmtools suite written by Tom Christiansen to help navigate and
    manage Perl module installations. You can obtain them at <a href=
    "http://search.cpan.org/dist/pmtools/">http://search.cpan.org/dist/pmtools/</a>.
    From the README:
        <pre>
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.
</pre>
        <ul>
            <li>pmpath - show the module's full path
            </li>
            <li>pmvers - get a module version number
            </li>
            <li>pmdesc - get a module description
            </li>
            <li>pmall - get all installed modules pmdesc descriptions
            </li>
            <li>pmdirs - print the perl module path, newline separated
            </li>
            <li>plxload - show what files a given program loads at compile time
            </li>
            <li>pmload - show what files a given module loads at compile time
            </li>
            <li>pmexp - show a module's exports
            </li>
            <li>pminst - find what's installed
            </li>
            <li>pmeth - list a class's methods, recursively
            </li>
            <li>pmls - long list the module path
            </li>
            <li>pmcat - cat the module source through your pager
            </li>
            <li>pman - show the module's pod docs
            </li>
            <li>pmfunc - show a function source code from a module
            </li>
            <li>podgrep - grep in pods of a file
            </li>
            <li>pfcat - show pods from perlfunc
            </li>
            <li>podtoc - list table of contents of a podpage
            </li>
            <li>podpath - show full path of pod file
            </li>
            <li>pods - list all standard pods and module pods
            </li>
            <li>sitepods - list only pods in site_perl directories
            </li>
            <li>basepods - list only normal "man-page" style pods
            </li>
            <li>faqpods - list only faq pods
            </li>
            <li>modpods - all module pods, including site_perl ones
            </li>
            <li>stdpods - list standard pods, not site_perl ones
            </li>
        </ul>
    </li>
</ul>
<hr>
<h3>
    <a name="Where_recent_modules" id="Where_recent_modules">Where can I find
    the most recently uploaded Perl modules?</a>
</h3>
<p>
    There are so many new and updated modules that it is hard to keep up with
    the deluge, but there are ways to stay abreast of the tide.
</p>
<ul>
    <li>
        <a href=
        "http://search.cpan.org/recent">http://search.cpan.org/recent</a>
    </li>
    <li>
        <a href=
        "http://search.cpan.org/uploads.rdf">http://search.cpan.org/uploads.rdf</a>
        - an RSS format of /recent
    </li>
</ul>
<p>
    Any of these should be good for your daily feed of new modules.
</p>
<hr>
<h3>
    <a name="Where_find_modules_windows" id="Where_find_modules_windows">Where
    can I find Perl modules for Windows?</a>
</h3>
<p>
    <a href=
    "http://www.activestate.com/activeperl/ppm-perl-modules">www.activestate.com</a>
    has a FAQ for their Package Manager. Also see <a href="http://strawberryperl.com/">http://strawberryperl.com/</a> which also
    enables you to build your own modules from CPAN.
</p>
<hr>
<h3>
    <a name="Where_find_binaries" id="Where_find_binaries">Where can I find
    Perl binaries/packages or Perl module binaries?</a>
</h3>
<p>
    <a href=
    "http://www.cpan.org/ports/index.html">http://www.cpan.org/ports/index.html</a>
    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.
</p>
<p>
    Perl module binaries for use with ActivePerl's PPM can be found at <a href=
    "http://www.activestate.com/PPMPackages/">http://www.activestate.com/PPMPackages/</a>.
</p>
<hr>
<h3>
    <a name="How_is_Perl_licensed" id="How_is_Perl_licensed">How are Perl and
    the CPAN modules licensed?</a>
</h3>
<p>
    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:
</p>
<pre>
                       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.
</pre>
<hr>
<h3>
    <a name="What_modules_in_Perl_Dist" id="What_modules_in_Perl_Dist">Does the
    Perl source include any modules?</a>
</h3>
<p>
    Yes, Perl comes with a number of useful modules and are listed in the
    perlmodlib pod:
</p>
<ul>
    <li>
        <a href=
        "http://perldoc.perl.org/perlmodlib.html">http://perldoc.perl.org/perlmodlib.html</a>
    </li>
    <li>
        <tt>perldoc perlmodlib</tt>
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_Perl_scripts" id="Where_find_Perl_scripts">Where can I
    find Perl scripts?</a>
</h3>
<ul>
    <li>
        <a href=
        "http://www.cpan.org/scripts/index.html">http://www.cpan.org/scripts/index.html</a>
    </li>
    <li>
        <a href="http://www.perlarchive.com/">http://www.perlarchive.com/</a>
    </li>
    <li>
        <a href="http://freshmeat.net">http://freshmeat.net/</a>
    </li>
    <li>and many, many other places on the net have Perl programs....
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_Perl_FAQs" id="Where_find_Perl_FAQs">Where can I find
    the Perl FAQs?</a>
</h3>
<p>
    The Perl FAQ is included with the Perl source code distribution.
</p>
<ul>
    <li>
        <tt>perldoc perlfaq</tt>
    </li>
    <li>
        <a href="http://perldoc.perl.org/index-faq.html">http://perldoc.perl.org/index-faq.html</a>
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_Perl_documentation" id=
    "Where_find_Perl_documentation">Where can I find Perl documentation?</a>
</h3>
<ul>
    <li>
        <a href="http://perldoc.cpan.org">http://perldoc.cpan.org/</a>
    </li>
    <li>
        <tt>perldoc perldoc</tt> to use the documentation included with your
        Perl distribution.
    </li>
    <li>
        <a href=
        "http://perldoc.perl.org/perlfaq2.html#Perl-Books">http://perldoc.perl.org/perlfaq2.html#Perl-Books</a>
        for those who have read all of the free documentation and want
        something they can read in the loo by candlelight.
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_module_documentation" id=
    "Where_find_module_documentation">Where can I find Perl module
    documentation?</a>
</h3>
<ul>
    <li>
        <a href="http://search.cpan.org/">http://search.cpan.org/</a>,
    </li>
    <li>
        <tt>perldoc Foo::Bar</tt> if the module is installed locally.
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_DBI_documentation" id=
    "Where_find_DBI_documentation">Where do I find Perl DBI/DBD/database
    documentation?</a>
</h3>
<ul>
    <li>
        <a href="http://dbi.perl.org/">http://dbi.perl.org/</a> - The Perl DBI
        site
    </li>
    <li>
        <a href=
        "http://search.cpan.org/dist/DBI/DBI.pm">http://search.cpan.org/dist/DBI/DBI.pm</a>
        - The DBI man page
    </li>
    <li>
        <tt>perldoc DBI</tt>
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_Perl_mailing_lists" id=
    "Where_find_Perl_mailing_lists">Where can I find Perl mailing lists?</a>
</h3>
<p>
    There are quite a few mailing lists with a broad range of topics.
</p>
<ul>
    <li>
        <a href="http://lists.perl.org/">http://lists.perl.org/</a>
    </li>
    <li>
        <a href=
        "http://www.perl.org/support/mailing_lists.html">http://www.perl.org/support/mailing_lists.html</a>
    </li>
    <li>
        <a href="http://www.nntp.perl.org/">nntp.perl.org</a> - browseable web
        archives (and NNTP gateway) of many of the Perl lists.
    </li>
</ul>
<hr>
<h3>
    <a name="Where_find_Perl_training" id="Where_find_Perl_training">Where can
    I find Perl courses/training/on-line tutorials?</a>
</h3>
<h3>
    Training
</h3>
<ul>
    <li>
        <a href="http://training.perl.com/">http://training.perl.com/</a>
    </li>
    <li>
        <a href=
        "http://www.perl.org/phbs/training.html">http://www.perl.org/phbs/training.html</a>
    </li>
</ul>
<hr>
<h3>
    <a name="How_join_mongers" id="How_join_mongers">How do I
    find/join/organise a Perl User Group?</a>
</h3>
<p>
    The Perl User Groups are known as "Perl Mongers" and have active groups all
    over the world. You can find an established group at <a href=
    "http://www.pm.org/groups.shtml">http://www.pm.org/groups.shtml</a> or
    start a new group if one isn't near you via <a href=
    "http://www.pm.org/start.shtml">http://www.pm.org/start.shtml</a>
</p>
<hr>
<h3>
    <a name="What_history_Perl" id="What_history_Perl">Where can I find a
    history of Perl releases or a general history of the Perl community?</a>
</h3>
<p>
    A history of Perl releases can be found in your Perl distribution via
    <tt>perldoc perlhist</tt> or via the web at <a href=
    "http://perldoc.perl.org/perlhist.html">http://perldoc.perl.org/perlhist.html</a>.
    A more general history of the Perl community, CPAST, can be found at
    <a href="http://history.perl.org/">http://history.perl.org/</a>.
</p>
<hr>
<h3>
    <a name="Download_module_corrupt" id="Download_module_corrupt">I downloaded
    a module/script/file but it was corrupt, what should I do?</a>
</h3>
<p>
    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 <a href=
    "http://www.cpan.org/SITES.html">http://www.cpan.org/SITES.html</a>
</p>
<p>
    If you use FTP remember to download in binary format, not text format.
</p>
<p>
    Please read <a href=
    "http://www.cpan.org/ENDINGS">http://www.cpan.org/ENDINGS</a> if you aren't
    sure what the files should be unpacked with and want to know if you are
    using the right program.
</p>
<p>
    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.
</p>
<hr>
<h3>
    <a name="Help_me_obi_wan" id="Help_me_obi_wan">How do I use module
    Foo::Bar, can you help? (a.k.a. Are you a helpdesk?)</a>
</h3>
<p>
    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.
</p>
<p>
    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.
</p>
<hr>
<h3>
    <a name="What_search_down" id="What_search_down">I'm having trouble with
    search.cpan.org, whom do I need to contact?</a>
</h3>
<p>
    If you are experiencing difficulty using search.cpan.org due to network or
    server errors, you need to contact <a href=
    "mailto:webmaster@search.cpan.org">webmaster@search.cpan.org</a>.
</p>
<hr>
<h3>
    <a name="How_search_CPAN" id="How_search_CPAN">How do I search for anything
    in CPAN?</a>
</h3>
<p>
    By using a CPAN search engine.<br>
</p>
<ul>
    <li>
        <a href="http://www.metacpan.org/">http://www.metacpan.org/</a> -
        A front-end for api.metacpan.org, which was created so that CPAN
        metadata can be searched and accessed without necessarily having to use
        any specific interface.
    </li>
    <li>
        <a href="http://search.cpan.org/">http://search.cpan.org/</a> - Graham
        Barr's search engine which can search for modules, distributions or
        authors in all of CPAN.
    </li>
    <li>
        <a href="http://perldoc.perl.org">http://perldoc.perl.org/</a> - also
        useful for core perl documentation.
    </li>
</ul>
<hr>
<h3>
    <a name="How_search_module_documentation" id=
    "How_search_module_documentation">How do I search for module/script
    documentation? (also known as "How do I use ..."?)</a>
</h3>
<p>
    In general modules and scripts come with their own documentation which
    should have been installed along with your module/script. (Thanks to Perl's
    <tt>pod</tt>-style documentation, "it is very hard to misplace your
    documentation".)
</p>
<ul>
    <li>
        <tt>perldoc Module::Name</tt>
    </li>
    <li>
        <tt>perldoc scriptname</tt>
    </li>
    <li>
        <a href="http://www.metacpan.org/">http://www.metacpan.org/</a>
    </li>
    <li>
        <a href="http://search.cpan.org">http://search.cpan.org/</a>
    </li>
</ul>
<hr>
<h3>
    <a name="How_contribute_modules" id="How_contribute_modules">How do I
    contribute modules to CPAN?</a>
</h3>
<p>
    If you would like to learn more about PAUSE and how to go about
    contributing your module to CPAN please read the PAUSE FAQ at <a href=
    "http://www.cpan.org/modules/04pause.html">http://www.cpan.org/modules/04pause.html</a>
    which will tell you how to go about getting a PAUSE ID and the steps needed
    to upload your code. Also,<a href=
    "http://perldoc.perl.org/perlmodlib.html"><tt>perldoc perlmodlib</tt></a>
    and <a href="http://perldoc.perl.org/perlmod.html"><tt>perldoc
    perlmod</tt></a> are a good introduction to Perl modules.
</p>
<hr>
<h3>
    <a name="Does_CPAN_allow_shareware" id="Does_CPAN_allow_shareware">Does
    CPAN allow contributions of shareware or code that requests a fee of any
    kind?</a>
</h3>
<p>
    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.
</p>
<hr>
<h3>
    <a name="How_contribute_scripts" id="How_contribute_scripts">How do I
    contribute scripts to CPAN?</a>
</h3>
<p>
    CPAN has a scripts repository at <a href=
    "http://www.cpan.org/scripts/">http://www.cpan.org/scripts/</a> and
    <a href="http://www.cpan.org/scripts/submitting.html">http://www.cpan.org/scripts/submitting.html</a>
    will instruct you on how to go about contributing your scripts.
</p>
<hr>
<h3>
    <a name="How_contribute_documentation" id=
    "How_contribute_documentation">How do I contribute documentation to
    CPAN?</a>
</h3>
<p>
    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.
</p>
<hr>
<h3>
    <a name="How_report_bug_Perl" id="How_report_bug_Perl">How do I report/fix
    a bug in Perl and/or its documentation?</a>
</h3>
<p>
    Always remember to make your bug reports as detailed as possible. "Perl
    doesn't work." is not a bug report.<br>
    Please note that problems concerning modules that are installed separately
    from the Perl distribution (such as Tk) are reported differently.
</p>
<p>
    Here is a checklist from <a href=
    "http://perldoc.perl.org/perlbug.html">perlbug</a>, 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.
</p>
<ul>
    <li>
        <b>What version of Perl you are running?</b>
        <p>
            Try <tt>perl -v</tt> at the command line to find out.
        </p>
    </li>
    <li>
        <b>Are you running the latest released version of perl?</b>
        <p>
            Look at <a href="http://www.perl.com/pub">http://www.perl.com/</a>
            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.
        </p>
    </li>
    <li>
        <b>Are you sure what you have is a bug?</b>
        <p>
            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 <a href="http://perldoc.cpan.org">documentation</a> 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).
        </p>
        <p>
            Be aware of the familiar traps that perl programmers of various
            hues fall into. See the <a href=
            "http://perldoc.perl.org/perltrap.html">perltrap</a> documentation.
        </p>
        <p>
            Check in <a href=
            "http://perldoc.perl.org/perldiag.html">perldiag</a> 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.
        </p>
        <p>
            If you are on a non-UNIX platform check also <a href=
            "http://perldoc.perl.org/perlport.html">perlport</a> documentation,
            some features may not be implemented or work differently.
        </p>
        <p>
            Try to study the problem under the Perl debugger,if necessary. See
            the <a href="http://perldoc.perl.org/perldebug.html">perldebug</a>
            documentation.
        </p>
    </li>
    <li>
        <b>Do you have a proper test case?</b>
        <p>
            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.
        </p>
        <p>
            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.
        </p>
        <p>
            Remember also to include all the exact error messages, if any.
            "Perl complained something" is not an exact error message.
        </p>
        <p>
            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.
        </p>
    </li>
    <li>
        <b>Can you describe the bug in plain English?</b>
        <p>
            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.
        </p>
    </li>
    <li>
        <b>Can you fix the bug yourself?</b>
        <p>
            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.
        </p>
        <p>
            Here are some clues for creating quality patches:<br>
            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).
        </p>
    </li>
    <li>
        <b>Can you use perlbug to submit the report?</b>
        <p>
            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).
        </p>
        <p>
            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.
        </p>
        <p>
            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.
        </p>
    </li>
</ul>
<hr>
<h3>
    <a name="How_report_bug_module" id="How_report_bug_module">How do I
    report/fix a bug in a module/script?</a>
</h3>
<p>
    Please contact the author of the module/script, ideally by
    creating a ticket using the bug tracker for the module (linked as 'Bugs' from
    <a href="http://www.metacpan.org">www.metacpan.org</a> or 'View/Report Bugs'
    from <a href="http://search.cpan.org">search.cpan.org</a>).
    The author should be automatically notified by email.
</p>
<p>
    If the author doesn't respond, the documentation of the module/script might
    contain a contact address or you can try <tt>CPANID@perl.org</tt> where
    CPANID is the authors CPANID.
</p>
<p>
    Most of the checklist in <a href="#How_report_bug_Perl">reporting bugs in
    Perl</a> 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.
</p>
<hr>
<h3>
    <a name="How_maintain_module" id="How_maintain_module">How do I go about
    maintaining a module when the author is unresponsive?</a>
</h3>
<p>
    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.
</p>
<ul>
    <li>Be courteous.
    </li>
    <li>Be considerate.
    </li>
    <li>Make an earnest attempt to contact the author as explained in
    <a href="#How_report_bug_module">How do I report/fix a bug in a
    module/script?</a>.
    </li>
    <li>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.
    </li>
    <li>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.
    </li>
</ul>
<p>
    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.
</p>
<hr>
<h3>
    <a name="How_adopt_module" id="How_adopt_module">How do I adopt or take
    over a module already on CPAN?</a>
</h3>
<p>
    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.
</p>
<p>
    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.
</p>
<p>
    Please make sure you have tried all of the above ways of getting in contact
    with the author before going this way!
</p>
<ul>
    <li>Get a login for the Perl Authors Upload Server (PAUSE) if you don't
    already have one: http://pause.perl.org
    </li>
    <li>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.
    </li>
    <li>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.
    </li>
    <li>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.
    </li>
</ul>
<hr>
<h3>
    <a name="Where_is_testers" id="Where_is_testers">Is there a site for module
    bug reports/tests?</a>
</h3>
<p>
    Yes, through the diligence of Paul Schinder and a few others, we have
    <a href="http://www.cpantesters.org/">CPAN Testers</a> 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 
    <a href="http://www.metacpan.org/">Metacpan</a> or
    <a href="http://search.cpan.org/">search.cpan.org</a>.
</p>
<p>
    There is also <a href="http://bugs.perl.org/">http://bugs.perl.org/</a>
    where you might search for a module bug already reported to P5P.
</p>
<hr>
<h3>
    <a name="Plans_for_statistics" id="Plans_for_statistics">Does CPAN provide
    download statistics for authors?</a>
</h3>
<p>
    No we don't. <a href=
    "http://xxx.lanl.gov/help/faq/statfaq">http://xxx.lanl.gov/help/faq/statfaq</a>
    sums up our thoughts on the matter quite well.
</p>

<hr>
<span id="How_mirror_CPAN"></span>
<span id="What_do_I_need"></span>
<span id="Which_site_mirror"></span>
<span id="How_register_mirror"></span>

<h2>Questions about mirroring CPAN</h2>
See <a href="how-to-mirror.html">How to mirror CPAN</a>.
<hr>

<p>
    <small>The CPAN FAQ is copyright Jarkko Hietaniemi and Elaine
    Ashton 1998-2007 and Ask Bjørn Hansen, Leo Lapworth 2011 All
    Rights Reserved. Send questions and comments
    to <a href="mailto:cpan@perl.org">cpan@perl.org</a>.
    </small>
</p>