CPAN

CPAN Frequently Asked Questions

Here are some answers to the most common questions received by cpan@perl.org.

For general information about Perl you should see the Perl Home Page (www.perl.com).

See the Perl FAQ (especially for any Perl programming questions, but also for other resources), available at http://perlfaq.cpan.org/.

Copyright Elaine Ashton <hfb@chaos.wustl.edu> and Jarkko Hietaniemi <jhi@iki.fi> 1998-2007 All Rights Reserved.


I. - General Questions.


II. - The Quest for Perl source, modules and scripts.


III. - RIF [ Reading is Fun-duh-mental ]


IV. - Danger Will Robinson! Danger! Danger!


V. - Searching CPAN, CSPAN and the rest of the known universe.


VI. - Contributing modules, patches, and bug reports.


VII. - How to mirror CPAN.


What is Perl?

From the Perl documentation:

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 world wide web programming. These strengths make it especially popular with system administrators and CGI script authors, but mathematicians, geneticists, journalists, and even managers also use Perl. Maybe you should, too.

See also http://www.tpj.com/whatisperl.html

Two good starting points for Perl information are http://www.perl.com/ and http://www.perl.org/


What is Perl6?

At The Second O'Reilly Open Source Software Convention, Larry Wall announced Perl6 development would begin in earnest. Perl6 was an oft used term for Chip Salzenberg's project to rewrite Perl in C++ named Topaz. However, Topaz should not be confused with the nisus to rewrite Perl while keeping the lessons learned from other software, as well as Perl5, in mind.

If you have a desire to help in the crusade to make Perl a better place then peruse the Perl6 developers page at http://www.perl.org/perl6 and get involved.

"We're really serious about reinventing everything that needs reinventing." --Larry Wall


What is CPAN?

CPAN is the Comprehensive Perl Archive Network, a large collection of Perl software and documentation. You can begin exploring from either http://www.cpan.org/, http://www.perl.com/CPAN/ or any of the mirrors listed at http://www.cpan.org/SITES.html.

Note that 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 http://search.cpan.org/dist/CPAN/lib/CPAN.pm.


What is PAUSE?

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

See the question 'How do I contribute modules?' below if you want to become a registered PAUSE user.


How does the CPAN work?

With dark magic, evil-looking sacrificial knives and scantily clad virgins under pale moonlight.

It actually works with the generosity and cooperation of hundreds of developers, over 100 participating mirrors, funet.fi 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. Various scripts run on CPAN daily to make sure that mirrors are up and running and that the mirror to PAUSE is functional, etc. 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.


How does the CPAN multiplexer work?

Not nearly as much dark magic and certainly no virgins, scantily clad or not...er...I mean...

The CPAN Multiplexer is the creation of Tom Christiansen and it lives at http://www.perl.com/CPAN which will present you with a menu of available mirrors and links to the source code if you wish to see how it really works. You may use a trailing slash on the above URL to have it try and direct you to the nearest mirror. The multiplexer attempts to map the tail part of the resolved DNS name of the client to the closest possible CPAN site, e.g. An *.ac.uk address will be directed to a mirror in the .uk domain, but an unresolvable numeric address or a *.com will be directed to the perl.com mirror.


Where can I find the current release of the Perl source code?

The Perl Mongers have a "Download Perl" button for websites and if you are interested you can find it on their site at http://www.pm.org/web_site_frosting.shtml.


Where can I find older/obsolete versions of Perl or Perl Modules?

Unless you have A Very Good Reason you shouldn't be installing obsolete versions because they might contain bugs, possibly even security bugs.

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

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


How do I interpret the Perl version numbers?

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.


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[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);

For these platforms a binary release may be the easiest path.

  1. The source code to compile MacPerl is available at http://www.cpan.org/ports/mac/.
  2. 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 http://www.cpan.org/ports/As400/ or http://www.cpan.org/ports/netware/ and then continue at http://www.cpan.org/src/README

Where can I find Perl modules?

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 find out what modules are already installed on my system?


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.

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.netaxs.com/~joc/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. 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.

Does the Perl source include any modules?

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


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 DLLs with REXX calling convention and REXX runtime.
OS2::ExtAttr
Access to extended attributes.
OS2::PrfDB
Access to the OS/2 setting database.
OS2::Process
Constants for \tool{system}(2) call on OS/2.
OS2::REXX
Access to DLLs with REXX calling convention and REXX runtime.

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?


Where can I find the Perl FAQs?

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


Where can I find Perl documentation?


Where can I find Perl module documentation?


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


Where can I find Perl mailing lists?

There are quite a few mailing lists with a broad range of topics.

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?


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

Training


Where can I find CPAN on a CD-ROM?

CPAN (cpan.org) does not produce CD-ROMs, sorry. Besides, these days one would need a DVD.


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.shtml or start a new group if one isn't near you via http://www.pm.org/start.shtml


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://theoryx5.uwinnipeg.ca/CPAN/perl/pod/perlhist.html.

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.


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

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.


When downloading a module a strange VRML viewer started up and I got an error, what should I do?

You saw an error window "VRML Console" saying "Compilation error: Unrecognized header string". The reason the VRML viewer starts is that there is a type of compressed VRML file with a .gz extension, using (theoretically) the standard gzip compression. The VRML folk used .gz as a means of cutting down the download time on the old wrl files. Most VRML browsers come with a mini gunzip program. See also the VRML FAQ which also covers this problem.

You can fix this with the following steps;

  1. Open "My Computer" or Windows NT Explorer.
  2. Select the "View" menu.
  3. Select "Options".
  4. Click the "File Types" tab.
  5. Scroll through the "Registered file types" until you reach "WorldView VRMLViewer Object" and select it.
  6. Click "Remove".
  7. Answer "Yes". (I've never seen these VRML files WorldView claims to be caring about: if you have and you do care, please tell me how to make WorldView stop caring about the .gz and application/x-gzip)
  8. Quit and restart your browser for the change to take effect.
  9. The next time you try open a file ending in .gz Windows will ask you which application to use to open that file. Scroll down to WinZiP (winzip32), and remember to check the box asking whether to always use this application to open this type of file unless, of course, you plan on regularly using the VRML viewer.

Where can I find the GDBM_File/DB_File module?

The GDBM_File module comes standard with Perl 5.

The problem you are most likely to be having is that your system (or the system your binary distribution was built on in the case you are not using the source code distribution but instead relying on a prebuilt binary installation kit) does not have the external library called libgdbm, or GNU DBM. The GDBM_File module needs that to be built, installed, and used. The library has nothing to do with Perl as such. You can try hunting for it using the standard software repositories for your platform or http://www.gnu.org/

If you are looking for DB_File, every time it says GDBM think of DB, GDBM_File needs an external library called libdb, or Berkeley DB. You might try http://www.sleepycat.com who distributes the Berkeley DB source code.


I'm having trouble with search.cpan.org, whom do I need to contact?

If you are experiencing difficulty using search.cpan.org due to network or server errors, you need to contact webmaster@search.cpan.org.


How do I search for anything on CPAN?

By using a CPAN search engine.


How do I search for module/script documentation? (also known as "How do I use ..."?)

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


How do I search for ANYTHING, really?


How do I find Ralph Nader? (a.k.a. We're C-P-A-N not C-S-P-A-N!)

You dialed the wrong number. The place you are looking for is http://www.cspan.org/.


How do I contribute modules to CPAN?

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 http://www.cpan.org/modules/04pause.html which will tell you how to go about getting a PAUSE ID and the steps needed to upload your code. Also, perldoc perlmodlib and perldoc perlmod are a good introduction to Perl modules.


Does CPAN allow contributions of shareware or code that requests a fee of any kind?

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.


How do I contribute scripts to CPAN?

CPAN has a scripts repository at http://www.cpan.org/scripts/ and http://www.cpan.org/scripts/submitting.html will instruct you on how to go about contributing your scripts.


How do I contribute documentation to CPAN?

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.


How do I report/fix a bug in Perl and/or its documentation?

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.


How do I report/fix a bug in a module/script?

Please contact the author of the module/script. The documentation of the module/script should 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.


How do I go about maintaining a module when the author is unresponsive?

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

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.


How do I adopt or take over a module already on CPAN?

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.

Is there a site for module bug reports/tests?

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

There is also http://bugs.perl.org/ where you might search for a module bug already reported to P5P.


Does CPAN provide download statistics for authors?

No we don't. http://xxx.lanl.gov/help/faq/statfaq sums up our thoughts on the matter quite well.


How do I mirror CPAN?

Either an FTP or rsync client will do. Scantily clad virgins and pale moonlight are optional and are not included in the sales price.


What do I need to mirror CPAN?


I have Windows Vista/XP/2000/NT/98/95, how can I mirror CPAN?

By using rsync for NT.


Which CPAN site should I mirror?

The one that gives the best bandwidth (where your mirror finishes quickest) and which is most up-to-date. Most up-to-date is, by definition, the CPAN master site ftp.funet.fi. Note that it lives in the GMT+2 timezone so please try not to mirror during working hours: 0600 to 1400 GMT/UTC. If you want to mirror from somewhere else, check the list at http://www.cpan.org/SITES.html

Please organize the mirroring with the corresponding FTP maintainer (their email addresses from the file http://www.cpan.org/MIRRORED.BY) so that you will not overload their site and that your mirror starts just after theirs has finished.

A few tips to keep in mind:


How do I register my mirror to make it a public resource?

If you want to publicize your CPAN mirror (meaning that your mirror is publicly available), please fill in the following template which can be found from the top of the file http://www.cpan.org/MIRRORED.BY:

hostname.of.the.CPAN.mirroring.site:
  frequency        = "daily/bidaily/.../weekly"
  dst_directory    = "the.same.host.name:/CPAN/mirror/directory/"
  dst_location     = "city, (area?, )country, continent (lon lat)"
  dst_organisation = "full organisation name"
  dst_timezone     = "GMT[+-]n"
  dst_contact      = "email.address.to.contact@for.this.mirror"
  dst_src          = "from.which.host:/is/this/site/mirroring/from/"
  dst_notes        = "(optional field) access restrictions, for example?"

There are plenty of examples of how to fill in the template file. When your template is ready, please send it to cpan@perl.org and you will be registered.>


Copyright Jarkko Hietaniemi <jhi@iki.fi> and Elaine Ashton <hfb@chaos.wustl.edu> 1998-2007 All Rights Reserved.