CPAN Frequently Asked Questions

How do I install Perl using the source code?

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

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 exception is (as of 2002-Dec-08) OS/400 ILE. (Mac OS Classic and NetWare were integrated back to the mainline in Perl 5.6.1 and Perl 5.8.0, respectively.)

The source code for OS/400 ILE has not been merged to the main Perl source code distribution. If you want to try compiling it yourself, get the sources from http://www.cpan.org/ports/as400/ and then continue at http://www.cpan.org/src/README Perl 5.8.1 is expected to support OS/400 PASE.

Where can I find Perl modules?

• http://www.cpan.org/modules/00modlist.long.html
• http://search.cpan.org/
• http://kobesearch.cpan.org/

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.

How do I install Perl modules?

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.

How do I remove installed Perl modules?

By using the ExtUtils::Installed and ExtUtils::Packlist modules that come with Perl as in the example below. There is also a more elaborate example in the ExtUtils::Packlist man page.

#!/usr/local/bin/perl -w

use ExtUtils::Packlist;
use ExtUtils::Installed;

$ARGV[0] or die "Usage: $0 Module::Name\n";

my $mod = $ARGV[0]; 

my $inst = ExtUtils::Installed->new();

    foreach my $item (sort($inst->files($mod))) {
             print "removing $item\n";
             unlink $item;
          }

     my $packfile = $inst->packlist($mod)->packlist_file();
          print "removing $packfile\n";
          unlink $packfile;
  

How do I find out what modules are already installed on my system?

• perldoc perllocal

  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.

  =head2 Wed May 12 13:42:53 1999: C<Module> L<Data::Dumper>
  
  =over 4
  
  =item *
  
  C<installed into: /usr/local/lib/perl5/5.00503>
  
  =item *
  
  C<LINKTYPE: dynamic>
  
  =item *
  
  C<VERSION: 2.101>
  
  =item *
  
  C<EXE_FILES: >
  
  =back
  

  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.

• Use the ExtUtils::Installed module

  ExtUtils::Installed provides a standard way to find out what core and module files have been installed. It uses the information stored in .packlist files created during installation to provide this information. In addition it provides facilities to classify the installed files and to extract directory information from the .packlist files.

  
  #!/usr/local/bin/perl
  
  use ExtUtils::Installed;
  my $instmod = ExtUtils::Installed->new();
  foreach my $module ($instmod->modules()) {
  my $version = $instmod->version($module) || "???";
         print "$module -- $version\n";
  }
  

  produces the following list of modules and their version

  
  Apache::DBI -- 0.87
  Apache::DBILogConfig -- 0.01
  Apache::DBILogger -- 0.93
  AppConfig -- 1.52
  Archive::Tar -- 0.22
  BerkeleyDB -- 0.06
  CGI -- 2.74
  CPAN -- 1.59
  CPAN::WAIT -- 0.27
  Catalog -- 1.00
  Compress::Zlib -- 1.11
  Config::IniFiles -- 2.14
  Convert::BER -- 1.26
  Coy -- ???
  Crypt::Rot13 -- 0.04
  Crypt::SSLeay -- 0.16
  DBI -- 1.14
  [.....]
  

• ActivePerl has the PPM utility.

  C:\>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
  

• The pmtools suite written by Tom Christiansen to help navigate and manage Perl module installations. You can obtain them at http://language.perl.com/misc/pmtools-1.00.tar.gz. From the README:

  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.
  

  • pmpath - show the module's full path
  • pmvers - get a module version number
  • pmdesc - get a module description
  • pmall - get all installed modules pmdesc descriptions
  • pmdirs - print the perl module path, newline separated
  • plxload - show what files a given program loads at compile time
  • pmload - show what files a given module loads at compile time
  • pmexp - show a module's exports
  • pminst - find what's ision numbering system wi>I have Windows 2000/NT/98/95, how can I mirror CPAN?
  • Which CPAN \Xnstalled
  • pmeth - list a class's methods, recursively
  • pmls - long list the module path
  • pmcat - cat the module source through your pager
  • pman - show the module's pod docs
  • pmfunc - show a function source code from a module
  • podgrep - grep in pods of a file
  • pfcat - show pods from perlfunc
  • podtoc - list table of contents of a podpage
  • podpath - show full path of pod file
  • pods - list all standard pods and module pods
  • sitepods - list only pods in site_perl directories
  • basepods - list only normal "man-page" style pods
  • faqpods - list only faq pods
  • modpods - all module pods, including site_perl ones
  • stdpods - list standard pods, not site_perl ones

What is a bundle and how do I make one for my own use or distribution on CPAN?

The 3rd edition of Programming Perl defines a bundle as "A group of related modules on CPAN" which is reasonably straightforward but it doesn't tell you what it is or how to make one yourself. A bundle can be any collection of modules, related or not. Bundles are used by CPAN.pm to install a group of modules quickly and easily.

A bundle is essentially a module in the Bundle:: namespace that has all the look and feel of a module but really isn't since it contains no code instead having a list of modules to be installed. Think of it as a list of ingredients for a CPAN.pm recipe. There are a number of existing module bundles that you can view as examples to help in building your own.

You can get a list of bundle distributions on search.cpan.org and CPAN.pm also lists all currently available bundles when you type 'b' at the prompt.

cpan> b
Bundle          Bundle::ABH     (A/AB/ABH/Bundle-ABH-1.04.tar.gz)
Bundle          Bundle::AO::Base (I/IX/IX/AO-0.32.tar.gz)
Bundle          Bundle::AO::Standard (I/IX/IX/AO-0.32.tar.gz)
Bundle          Bundle::Apache  (D/DO/DOUGM/mod_perl-1.25.tar.gz)
Bundle          Bundle::Apache::ASP (C/CH/CHAMAS/Apache-ASP-2.09.tar.gz)
Bundle          Bundle::Apache::Roaming (J/JW/JWIED/Apache-Roaming-0.1003.tar.gz)
Bundle          Bundle::BioPerl (C/CR/CRAFFI/Bundle-BioPerl-1.00.tar.gz)
Bundle          Bundle::Bonsai  (Z/ZL/ZLIPTON/Bundle-Bonsai-0.02.tar.gz)
[....]

If you give 'b' a module argument it will list extended information about the bundle.

cpan> b Bundle::DBI
Bundle id = Bundle::DBI
    CPAN_USERID  TIMB (Tim Bunce <Tim.Bunce@pobox.com>)
    CPAN_VERSION 1.03
    CPAN_FILE    T/TI/TIMB/DBI-1.15.tar.gz
    MANPAGE      Bundle::DBI - A bundle to install DBI and required modules.
    CONTAINS     Storable Net::Daemon RPC::PlServer Getopt::Long DBI
    INST_FILE    /usr/local/lib/perl5/site_perl/5.005/sun4-solaris/Bundle/DBI.pm
    INST_VERSION 1.03

There are 2 Ways to make a bundle:

1. Use the autobundle feature of CPAN.pm

   autobundle will, if no arguments are given, inventory all modules installed on the system and make a systemwide bundle. If you only want a few modules in the bundle you can simply give it a list of modules and it will do the rest.

   foo@bar /home/chaos/monkey> perl -MCPAN -eshell
   
   cpan> autobundle CGI Crypt::Rot13 Date::Christmas Date::Manip
   
   Going to read /home/chaos/monkey/.cpan/sources/authors/01mailrc.txt.gz
   CPAN: Compress::Zlib loaded ok
   Going to read /home/chaos/monkey/.cpan/sources/modules/02packages.details.txt.gz
   Going to read /home/chaos/monkey/.cpan/sources/modules/03modlist.data.gz
   
   Package namespace         installed    latest  in CPAN file
   CGI                            2.74     2.753  L/LD/LDS/CGI.pm-2.753.tar.gz
   Crypt::Rot13                   0.04      0.04  A/AY/AYRNIEU/Crypt-Rot13-0.04.tar.gz
   Date::Christmas                1.01      1.02  H/HF/HFB/Date-Christmas-1.02.tar.gz
   Date::Manip                    5.39      5.39  S/SB/SBECK/DateManip-5.39.tar.gz
   
   Wrote bundle file
       /home/chaos/monkey/.cpan/Bundle/Snapshot_2001_05_09_01.pm
   

   The "Snapshot_2001_05_09_01.pm" file may then be used with the CPAN.pm

   perl -MCPAN -e 'install Bundle::Snapshot_2001_05_09_01'

   If it has trouble finding the snapshot check your CPAN.pm configuration.

     
   cpan> o conf cpan_home
       cpan_home          /home/chaos/monkey/.cpan   
   

   This particular feature comes in very handy if you are a Systems Administrator or a user who have a number of modules you like to keep up to date on without much hassle or if you need to distribute modules to a large number of machines and want to keep it consistent. There are a lot of excellent uses for this convenient little tool.

2. Make Bundle distribution for CPAN

• Create framework for Bundle like so:

  foo@bar /home/chaos/monkey> h2xs -AXcfn Bundle::MyBundle
  Writing Bundle/MyBundle/MyBundle.pm
  Writing Bundle/MyBundle/Makefile.PL
  Writing Bundle/MyBundle/test.pl
  Writing Bundle/MyBundle/Changes
  Writing Bundle/MyBundle/MANIFEST
  

• Edit the MyBundle.pm
  • Remove all but the package declaration, the version and the 1; in the body of the module
  • Edit the name and add a brief ' - descriptive info' in the name
  • Add C<perl -MCPAN -e 'install Bundle::MyBundle'> to the synopsis.
  • Add a =head1 CONTENTS header and under it add modules in the bundle in the format:
    ModuleName [ optional version ] [ - comment or description ]
    The '-' in front of the comment is required.
  • Add a brief description.
  • Add author information and license.

    package Bundle::MyBundle;
    
    $VERSION = '0.01';
    
    1;
    __END__
    
    =head1 NAME
    
    Bundle::MyBundle - Bundle of my very favourite modules
    
    =head1 SYNOPSIS
    
     C<perl -MCPAN -e 'install Bundle::MyBundle'>
    
    =head1 CONTENTS
    
    CGI 2.74        - CGI is groovy baby
    Crypt::Rot13    - This would make for some interesting web pages
    Date::Christmas - defies description
    Date::Manip
    
    =head1 DESCRIPTION
    
    These modules rock, especially when installed together!
    
    =head1 AUTHOR
    
    Ima Bundle ima@bundle.com
    
    =head1 LINCENSE
    
    Steal this code!
    
    =head1 SEE ALSO
    
    perl(1).
    
    =cut
    
    

  • Remove files you don't need such as 'Changes' and 'test.pl' from the directory and add a README file with a short description of the Bundle and a list of modules it will install. Update the MANIFEST file to accurately list the contents of the Bundle directory.
  • Make the distribution by first issuing 'perl Makefile.pl' then 'make dist' which will do the following leaving you with Bundle-MyBundle-0.01.tar.gz which is ready to be uploaded to CPAN.

    foo@bar monkey/Bundle/MyBundle> perl Makefile.PL 
    
    Checking if your kit is complete...
    Looks good
    Writing Makefile for Bundle::MyBundle
    
    foo@bar monkey/Bundle/MyBundle> make dist
    rm -rf Bundle-MyBundle-0.01
    /usr/bin/perl -I/usr/local/lib/perl5/5.00503/sun4-solaris -I/usr/local/lib/perl5/5.00503 \
    -MExtUtils::Manifest=manicopy,maniread -e "manicopy(maniread(),'Bundle-MyBundle-0.01', 'best');"
    mkdir Bundle-MyBundle-0.01
    tar cvf Bundle-MyBundle-0.01.tar Bundle-MyBundle-0.01
    a Bundle-MyBundle-0.01/ 0K
    a Bundle-MyBundle-0.01/Makefile.PL 1K
    a Bundle-MyBundle-0.01/MyBundle.pm 1K
    a Bundle-MyBundle-0.01/README 1K
    a Bundle-MyBundle-0.01/MANIFEST 1K
    rm -rf Bundle-MyBundle-0.01
    gzip --best Bundle-MyBundle-0.01.tar
    

    That's all there is to it. Developers may find the bundle feature convenient if there is an optimal installation of modules that work best with their distribution.

How do I check to see if certain modules run on my operating system?

Browse through http://testers.cpan.org/ which has a listing of modules and whether or not the module succeeded or failed on a number of platforms.

How do I manually install a module in a private/non-standard directory?

You need to set PREFIX and LIB when you run the Makefile.PL. LIB is where the module files will go and PREFIX is the stub directory for everything else. For example:

  foo@barbell$ perl Makefile.PL LIB=/home/foobar/mylib PREFIX=/home/foobar/mylib

Read more about this in the ExtUtils::MakeMaker documentation.

How do I use a module installed in a private/non-standard directory?

There are several ways to use modules installed in private directories:

• foo@barbell$ setenv PERL5LIB /path/to/module sets the environment variable PERL5LIB.
• use lib qw(/path/to/module); used at the top of your script tells perl where to find your module.
• foo@barbell$ perl -I/path/to/module

All of these will append /path/to/module to @INC. You should keep in mind that having private/non-standard libraries may cause problems if you wish to have portable code.

Where can I find the most recently uploaded Perl modules?

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.

• http://search.cpan.org/recent
• http://theoryx5.uwinnipeg.ca/mod_perl/cpan-search?request=recent
• http://use.perl.org/
• http://search.cpan.org/recent.rdf - an RSS format of /recent

Any of these should be good for your daily feed of new modules.

Where can I find Perl modules for Windows?

www.activestate.com has a FAQ for their Package Manager or http://www.northbound-train.com/perlwin32.html which has a nice listing of Win32 resources including modules.

Where can I find Perl binaries/packages or Perl module binaries?

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.

Perl module binaries for use with ActivePerl's PPM can be found at http://www.activestate.com/PPMPackages/.

How are Perl and the CPAN modules licensed?

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.

The Open Source Initiative has a nice page of 'approved' licenses and license mailing list information at http://www.opensource.org/licenses/index.html.

CPAN and PAUSE are not responsible for any licenses or lack thereof contained in the contents of the archive. We do recommend that authors license their modules to avoid legal ambiguity and so that people may use the code in good conscience. If you require help with a license, we urge you to consult legal counsel who can give you sound advice.

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.

Does the Perl source include any modules?

Yes, Perl comes with a number of useful modules and are listed in the perlmodlib pod:

• http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmodlib.pod
• perldoc perlmodlib

What modules are platform dependent?

Several implementations of Perl on specific platforms come bundled with a collection of platform specific modules.

Additional information is available for:

IBM OS/2

The following modules come with standard Perl.

OS2::DLL

Access to DLLmbering system wi>I have Windows 2000/NT/98/95, how can I mirror CPAN?

DEC (Open)VMS

The following modules come with standard Perl.

VMS::DCLsym

Perl extension to manipulate DCL symbols.

VMS::Filespec

Converts between VMS and Unix file specification syntax.

VMS::Stdio

Standard I/O functions via VMS extensions.

VMS::XSSymSet

Keeps sets of symbol names palatable to the VMS linker.

Microsoft Windows (32 bit)

The following modules come with ActiveState Perl.

Win32::ChangeNotify

Monitors events related to files and directories.

Win32::Console

Uses Win32 Console and Character Mode Functions.

Win32::Event

Uses Win32 event objects.

Win32::EventLog

Processes Win32 Event Logs.

Win32::File

Manages file attributes.

Win32::FileSecurity

Manages FileSecurity Discretionary Access Control Lists.

Win32::IPC

Loads base class for Win32 synchronization objects.

Win32::Internet

Accesses WININET.DLL functions.

Win32::Mutex

Uses Win32 mutex objects.

Win32::NetAdmin

Manages network groups and users.

Win32::NetResource

Manages network resources.

Win32::ODBC

Uses ODBC Extension for Win32.

Win32::OLE

Uses OLE Automation extensions.

Win32::OLE::Const

Extracts constant definitions from TypeLib.

Win32::OLE::Enum

Uses OLE Automation Collection Objects.

Win32::OLE::NLS

Uses OLE National Language Support.

Win32::OLE::Variant

Creates and modifies OLE VARIANT variables.

Win32::PerfLib

Accesses the Windows NT Performance Counter.

Win32::Process

Creates and manipulates processes.

Win32::Semaphore

Uses Win32 semaphore objects.

Win32::Service

Manages system services.

Win32::Sound

Plays with Windows sounds.

Win32::TieRegistry

Mungs the registry.

Win32API::File

Accesses low-level Win32 system API calls for files and directories.

Win32API::Net

Manages Windows NT LanManager accounts.

Win32API::Registry

Accesses low-level Win32 system API calls from WINREG.H.

Where can I find Perl scripts?

• http://www.cpan.org/scripts/index.html
• http://www.perlarchive.com/
• http://freshmeat.net/
• and many, many other places on the net have Perl programs....

Where can I find the Perl FAQs?

The Perl FAQ is included with the Perl source code distribution.

• perldoc perlfaq
• http://perlfaq.cpan.org/

Where can I find Perl documentation?

• http://www.cpan.org/doc/index.html
• http://perldoc.cpan.org/
• perldoc perldoc to use the documentation included with your Perl distribution.
• http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlfaq2.pod#Perl_Books for those who have read all of the free documentation and want something they can read in the loo by candlelight.

Where can I find Perl module documentation?

• http://search.cpan.org/,
• http://wait.cpan.org/
• perldoc Foo::Bar if the module is installed locally.

Where do I find Perl DBI/DBD/database documentation?

• http://dbi.perl.org/ - Alligator Descartes Definitive DBI page.
• http://www.savebaseball.com/mysql/DBD_3.21.X.php3 - A mySQL Perl DBI/DBD Manual.
• http://search.cpan.org/search?module=DBI - The DBI man page.
• perldoc DBI

Where can I find Perl mailing lists?

There are quite a few ec\OÃH[06/Sep/2008:23:49:48 -0400]mailing lists with a broad range of topics.

• http://lists.perl.org/
• http://www.perl.com/pub/language/info/mailing-lists.html,
• http://www.perl.org/support/mailing_lists.html
• http://www.mail-archive.com/ - browseable web archives of many of the Perl lists.

Many of the lists are open for general subscription. If you don't see a list that interests you and would like to start your own you may ask lists@perl.org to set one up for you if you cannot host it yourself.

Where can I find Perl journals/magazines?

• http://www.tpj.com/ - The journal in print for Perl.
• http://www.perlmonth.com/ - a terrific on-line only journal.
• http://www.unixreview.com/
• http://www.stonehenge.com/merlyn/WebTechniques/ - Randal Schwartz' Web Techniques Columns.
• http://www.usenix.org/publications/login/login.html - ;login, the publication of USENIX.
• http://www.samag.com/ - System Admin Magazine has occasional Perl articles.

Where can I find Perl courses/training/on-line tutorials?

Training

• http://www.perltraining.org/
• http://www.perl.org/phbs/training.html

On-line Tutorials

• http://www.ebb.org/PickingUpPerl/
• http://www.speech.cs.cmu.edu/~sburke/pub/perl.html
• http://www.comp.leeds.ac.uk/Perl/start.html
• http://www.cpan.org/doc/FMTEYEWTK/index.html
• http://www.cclabs.missouri.edu/things/instruction/perl/perlcourse.html

Where can I find CPAN on a CD-ROM?

CPAN (cpan.org) does not produce CD-ROMs so we cannot guarantee the freshness or quality of CD-ROMs produced by others or contained in the products below.

Red Hat offers a CPAN CD-ROM in its Deluxe Edition of Red Hat Linux. See http://www.redhat.com/products/ for more details.

O'Reilly and Associates produce The Perl Resource Kit, the UNIX and Win32 Editions. The UNIX version is from November 1997 and no longer in print. The Win32 version is from August 1998. See http://www.oreilly.com/catalog/ for more information and possible updates to the PRK.

Last but not least, the above list is certainly not comprehensive nor is it to be considered as an endorsement. If you know of other CPAN-on-a-CD products, please let us know and we will include them here.

How do I find/join/organise a Perl User Group?

The Perl User Groups are known as "Perl Mongers" and have active groups all over the world. You can find an established group at http://www.pm.org/groups/index.html or start a new group if one isn't near you via http://www.pm.org/start/index.html

Where can I find a history of Perl releases or a general history of the Perl community?

A history of Perl releases can be found in your Perl distribution via perldoc perlhist or via the web at http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlhist.pod.

A more general history of the Perl community, CPAST, can be found at http://history.perl.org/.

I got an error downloading a module, what should I do?

If you feel that you have experienced unreasonable difficulty reaching a particular mirror and wish to inform us of this, please check the points below before contacting us. We do poll mirrors daily to be sure they are on-line and available, but there are times when servers or their networks go down for brief periods of time that we don't always see and have no control over.

• What program were you using to download? A Web browser? An FTP client?
• Which server were you using?

  Note that many Perl software servers redirect your WWW requests to a site (hopefully) nearer to you. For example, the perl.com multiplexer does that so you often aren't downloading from perl.com itself. If you are using a web browser, take a close look at the URL/Location. Also note that we cannot debug your network connectivity and if you have problems connecting to anywhere other than the CPAN master site, ftp.funet.fi, we probably cannot be of service.

  You can try changing the server to http://www.perl.com/CPAN, (note: NO final slash) and pick a new server. Note that the selection is `sticky' and your browser will use that server from then on. Using http://www.perl.com/CPAN/ (note the final slash) will use the multiplexer to pick a new mirror for you.

• What was the exact error message?

  We are not clairvoyant so please include the exact error message, cut and paste if you must.

• Did you retry later?

  The server might be temporarily busy or be offline and refuse connections for a while. Retry later or try another server.

I downloaded a module/script/file but it was corrupt, what should I do?

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 or at http://mirror.cpan.org/.

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.

How do I use module Foo::Bar, can you help? (a.k.a. Are you a helpdesk?)

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.

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.

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.

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.

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

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.