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.org).
See the Perl FAQ (especially for any Perl programming questions, but also for other resources), available at http://perldoc.perl.org/index-faq.html.
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 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.
A good starting point for Perl information is http://www.perl.org/
Perl and Raku (formerly known as Perl 6) are two languages in the Perl family, but of different lineages. Raku is not intended primarily as a replacement for Perl, but as its own thing - and libraries exist to allow you to call Perl code from Raku programs and vice versa.
For more about Raku see http://www.raku.org/.
"We're really serious about reinventing everything that needs reinventing." --Larry Wall
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/ or any of the mirrors listed at http://www.cpan.org/SITES.html.
CPAN is also the name of a Perl module, CPAN.pm, which is used to download and install Perl software from the CPAN archive. This FAQ covers only a little about the CPAN module and you may find the documentation for it by using perldoc CPAN via the command line or on the web at https://metacpan.org/pod/CPAN.
PAUSE is the Perl Authors Upload SErver, a registry for Perl module, script and documentation authors to upload their work to the CPAN. CPAN and PAUSE are often used interchangeably but they are distinct from each other. The CPAN.pm documentation explains it rather simply;
In this discussion CPAN and PAUSE have become equal -- but they are not. PAUSE is authors/ and modules/. 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.
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.
After an author uploads their module to PAUSE, it will be mirrored to CPAN once an hour and from there, to the rest of the mirrors around the world. There are people who advise authors on their choice of name and namespace for their modules and a few others who answer questions and investigate issues sent to cpan@perl.org.
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).
Perl changed the version numbering system with v5.6.0 as was indicated in the release announcement:
Perl v5.6.0 is a major release that incorporates all maintenance and development changes since the last major release, 5.005. As you may have noticed, the version numbering has changed. Releases will henceforth be numbered as revision.version.subversion triples. Maintenance releases will have an even version component, while the version component for development releases will be odd. For example, the next maintenance update of Perl 5.6.0 will be v5.6.1, and the development series will begin life at v5.7.0.
You may also peruse the perlhist manpage for a complete list of versions and their release dates.
To build Perl you need a C compilation environment. After downloading the source code and opening it up, you should first read the INSTALL document which will detail how to build Perl on most systems. There are a number of README.[platform] for platforms where special care is needed in building Perl. As always, reading the documentation is a Good Thing[tm].
Perl can be installed using the standard source code distribution on almost all platforms Perl runs on. This includes all the UNIXes (and good lookalikes, meaning POSIX environments like OS/2, Plan 9, QNX, Amiga, MPE/iX, VMS, OS390, Stratus VOS), and Microsoft platforms. The most notable exceptions are (as of 1999-Mar-24);
For these platforms a binary release may be the easiest path.
Due to the ever increasing number of modules on CPAN, the CPAN search engine is possibly a better starting point in your quest for code, especially if you already know exactly what you are looking for.
Installing a new module can be as simple as typing perl -MCPAN -e 'install Chocolate::Belgian'. The CPAN.pm documentation has more complete instructions on how to use this convenient tool. If you are uncomfortable with having something take that much control over your software installation, or it otherwise doesn't work for you, the perlmodinstall documentation covers module installation for UNIX, Windows and Macintosh in more familiar terms.
Finally, if you're using ActivePerl on Windows, the PPM (Perl Package Manager) has much of the same functionality as CPAN.pm.
Each time a module is installed on your system, it appends information like the following to a file called perllocal.pod which can be found in /usr/local/lib/perl5/version number/architecture/ or something akin to that. The path for your specific installation is in your @INC which you can divine with perl -V.
=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.
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
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.
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.
www.activestate.com has a FAQ for their Package Manager. Also see http://strawberryperl.com/ which also enables you to build your own modules from CPAN.
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/.
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.
Yes, Perl comes with a number of useful modules and are listed in the perlmodlib pod:
The Perl FAQ is included with the Perl source code distribution.
There are quite a few mailing lists with a broad range of topics.
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/ or start a new group if one isn't near you via http://www.pm.org/start/
A history of Perl releases can be found in your Perl distribution via perldoc perlhist or via the web at http://perldoc.perl.org/perlhist.html. A more general history of the Perl community, CPAST, can be found at http://history.perl.org/.
Many CPAN filenames end in .tar.gz. Unfortunately some programs mutilate such names (e.g., rename them with _tar.tar) so that unpacking programs don't recognise them and refuse to unpack them. Try saving the file using the .tgz suffix or try changing your web client. Also, you could try a plain FTP client as almost all the CPAN sites are ftp-reachable. You can find the full list of mirrors http://www.cpan.org/SITES.html
If you use FTP remember to download in binary format, not text format.
Please read http://www.cpan.org/ENDINGS if you aren't sure what the files should be unpacked with and want to know if you are using the right program.
If you still think you have a corrupt file, try downloading the file from another site. If you still have no satisfaction, then please let us know the exact file name and URL/FTP site and path.
We at CPAN are not a helpdesk. We may point you towards a plethora of documentation to help you in your quest for knowledge but we cannot debug your code or read for you. We exist specifically to answer questions and solve problems relating directly to the functioning of the CPAN itself.
In addition to the on-line documentation you might try the newsgroup comp.lang.perl.modules for help with a particular module. Also, looking at other code using the same module might prove enlightening.
By using a CPAN search engine.
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".)
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.
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.
Scripts can be provided in any CPAN distribution, though distributions need to contain a module to be easily installable. By convention, CPAN modules meant to install scripts are usually put in the App:: namespace.
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.
Bug reports should be submitted to the GitHub issue tracker at https://github.com/Perl/perl5/issues.
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.
Type perl -v at the command line to find out.
Look at https://www.perl.org/ to find out. If you are not using the latest released version, please try to replicate your bug on the latest stable release.
Note that reports about bugs in old versions of Perl, especially those which indicate you haven't also tested the current stable release of Perl, are likely to receive less attention from the volunteers who build and maintain Perl than reports about bugs in the current release.
A significant number of the bug reports we get turn out to be documented features in Perl. Make sure the issue you've run into isn't intentional by glancing through the documentation that comes with the Perl distribution.
Given the sheer volume of Perl documentation, this isn't a trivial undertaking, but if you can point to documentation that suggests the behaviour you're seeing is wrong, your issue is likely to receive more attention. You may want to start with perldoc perltrap for pointers to common traps that new (and experienced) Perl programmers run into.
If you're unsure of the meaning of an error message you've run across, perldoc perldiag for an explanation. If the message isn't in perldiag, it probably isn't generated by Perl. You may have luck consulting your operating system documentation instead.
If you are on a non-UNIX platform perldoc perlport, as some features may be unimplemented or work differently.
You may be able to figure out what's going wrong using the Perl debugger. For information about how to use the debugger perldoc perldebug.
The easier it is to reproduce your bug, the more likely it will be fixed -- if nobody can duplicate your problem, it probably won't be addressed.
A good test case has most of these attributes: short, simple code; few dependencies on external commands, modules, or libraries; no platform-dependent code (unless it's a platform-specific bug); clear, simple documentation.
A good test case is almost always a good candidate to be included in Perl's test suite. If you have the time, consider writing your test case so that it can be easily included into the standard test suite.
Be sure to include the exact error messages, if any. "Perl gave an error" 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 crash and the stack trace.
The easier it is to understand a reproducible bug, the more likely it will be fixed. Any insight you can provide into the problem will help a great deal. In other words, try to analyze the problem (to the extent you can) and report your discoveries.
If so, that's great news; bug reports with patches are likely to
receive significantly more attention and interest than those
without patches. Please submit your patch via the GitHub Pull
Request workflow as described in perldoc perlhack. You may also send
patches to perl5-porters@perl.org. When sending a patch,
create it using git format-patch if possible, though a
unified diff created with diff -pu will do nearly as
well.
Your patch may be returned with requests for changes, or requests for more detailed explanations about your fix.
Here are a few hints for creating high-quality patches:
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 git
am or 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 is covered by Perl's test
suite).
perlbug to submit a thank-you note?
Yes, you can do this by either using the -T option, or
by invoking the program as perlthanks. Thank-you notes
are good. It makes people smile.
Please make your issue title informative. "a bug" is not informative. Neither is "perl crashes" nor is "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 possibly to get no reply at all. The volunteers who maintain Perl are busy folks, so if your problem is an obvious bug in your own code, is difficult to understand or is a duplicate of an existing report, you may not receive a personal reply.
If it is important to you that your bug be fixed, do monitor the issue tracker (you will be subscribed to notifications for issues you submit or comment on) and the commit logs to development versions of Perl, and encourage the maintainers with kind words or offers of frosty beverages. (Please do be kind to the maintainers. Harassing or flaming them is likely to have the opposite effect of the one you want.)
Feel free to update the ticket about your bug on https://github.com/Perl/perl5/issues if a new version of Perl is released and your bug is still present.
Please contact the author of the module/script, ideally by creating a ticket using the bug tracker for the module (linked as 'Bugs' from metacpan.org). The author should be automatically notified by email.
If the author doesn't respond, the documentation of the module/script might contain a contact address or you can try CPANID@perl.org where CPANID is the authors CPANID.
Most of the checklist in reporting bugs in Perl above applies for modules as well. Make your bug report as good as possible if you really want the bug fixed. If the module is included with the Perl distribution you should also follow the Perl bug reporting tips.
Sometimes a module goes unmaintained for a while due to the author pursuing other interests, being busy, etc. and another person needs changes applied to that module and may become frustrated when their bug reports and emails goes unanswered. CPAN does not mediate or dictate a policy in this situation and rely on the respective authors to work out the details. If you treat other authors as you would like to be treated in the same situation the manner in which you go about dealing with such problems should be obvious.
Simply keep in mind that you are dealing with a person who invested time and care into something. A little respect and courtesy go a long way.
The easiest way to take over a module is to have the current module maintainer either make you a co-maintainer or transfer the module to you.
If you can't reach the author for some reason (e.g. email bounces), the PAUSE admins at modules@perl.org can help. The PAUSE admins treat each case individually.
Please make sure you have tried all of the above ways of getting in contact with the author before going this way!
Yes, through the diligence of Paul Schinder and a few others, we have CPAN Testers which is a collection of test results for modules on a number of different platforms. This information is also available when viewing module information on Metacpan.
There is also http://bugs.perl.org/ where you might search for a module bug already reported to P5P.
No we don't. http://xxx.lanl.gov/help/faq/statfaq sums up our thoughts on the matter quite well.
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 cpan@perl.org.