I have prepared some answers to the most common questions asked from cpan@perl.org -- sort of CPAN Frequently Asked Questions list.
In general, you should look for information about Perl from 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://language.perl.com/faq/index.htmland in searchable form at
http://theory.uwinnipeg.ca/CPAN/perl/perlfaq.htmlBest regards,
-- cpan@perl.org
In this FAQ you will find answers to the following questions: 0. What is ...? 0.1. ... Perl? 0.2. ... CPAN? 0.2.1. ... How does CPAN work? 0.2.2. ... How does the CPAN multiplexor work? 0.3. ... PAUSE? 1. Is Perl Y2K-compliant? 2. I got an error downloading ...? 3. I downloaded ... but it was corrupt. 3.1. ... How do I unpack ...? 4. Where do I find ...? 4.1. ... Perl source code 4.1.1. ... How do I install Perl from the source code? 4.1.2. ... How do find Perl? 4.2. ... Perl binaries/executables or Perl module binaries 4.3. ... documentation 4.4. ... scripts 4.5. ... modules 4.5.1. ... GDBM_File 4.5.1. ... DB_File 4.6. ... module documentation 4.6.1. ... DBI/DBD/database access documentation 4.7. ... Perl FAQs 4.8. ... Perl mailing lists 4.9. ... Perl journals/magazines 4.9. ... Perl courses/training 5. How do I search for ...? 5.1. ... anything? 5.1.1. ... really ANYTHING? 5.2. ... module/script documentation? (also known as "How do I use ..."?) 6. How do I contribute ...? 6.1. ... modules 6.2. ... scripts 6.3. ... documentation 6.4. ... fixes 7. How do I report/fix a bug in ...? 7.1. ... Perl and/or its documentation 7.2. ... a module/script? 8. How do I join/found ...? 8.1. ... a Perl user group 8.2. ... a Perl mailing list 9. How do I mirror CPAN? 9.1. ... What do I need? 9.2. ... Which site should I mirror? 9.3. ... How do I register? --------------------------------------------------------------------------- 0. What is ...? 0.1. ... Perl? From the Perl documentation: Perl is an interpreted language optimized for scanning arbitrary text files, extracting information from those text files, and printing reports based on that information. It's also a good language for many system management tasks. The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, elegant, minimal). See also http://www.tpj.com/whatisperl.html In general good starting points for Perl information are http://www.perl.com/ and http://www.perl.org/ 0.2. ... CPAN? CPAN is the Comprehensive Perl Archive Network, a large collection of Perl software and documentation. You can start off from any of these: http://www.perl.com/CPAN/ http://www.perl.org/CPAN/ http://www.cpan.org/ Note that CPAN is also the name of a Perl module used to download and install Perl software from the CPAN archive. This FAQ says only a little about the CPAN module. 0.2.1. ... How does CPAN work? With dark magic, evil-looking sacrificial knives and scantily clad virgins under pale moonlight. 0.2.2. ... How does the CPAN multiplexer work? By mapping the tail part of the DNS name of the client as closely as possible to the CPAN sites. 0.3. ... PAUSE? PAUSE is the Perl Authors Upload SErver, a registry for Perl authors (software writers) to upload their work to the CPAN. See 6.1. and 6.2. below if you want to become a registered PAUSE author. 1. Is Perl Y2K compliant? Yes. See http://language.perl.com/news/y2k.html Because Perl is a general-purpose programming language, the real question is: are your programmers Y2K compliant? 2. I got an error downloading ...? 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, perl.com does that: you often aren't downloading from perl.com itself. If you are using a web browser, take a close look at the URL/Location: what does it say? Also note that I cannot debug your network connectivity: if you have problems connecting to anywhere else than the CPAN master site, ftp.funet.fi, I cannot help. You can try changing the server: open up http://www.perl.com/CPAN (note: NO final slash) and pick a new server. Note that the selection is `sticky': from then on your browser will remember it and any connections going through http://www.perl.com/CPAN/ (note the final slash) will use the selected server. What was the exact error message? I am no psychic. Please say what the exact error message was. Did you retry later? Many servers might be temporarily busy and refuse connections for a while. Retrying later might help. The best guess is to try outside the business hours of the server. 3. I downloaded ... but it was corrupt. Many CPAN filenames end in .tar.gz. Unfortunately many silly download programs mutilate such names (so that they end with _tar.tar, for example) and therefore many silly unpacking programs refuse to unpack them. Try saving that using the .tgz suffix or try changing your download program, by using a different web browser. Also, you could try a pure FTP client; all the CPAN sites are ftp-reachable. You can find the full list in the file http://www.perl.com/CPAN/MIRRORED.BY If you use FTP, remember to download in binary format, not text format. 3.1. ... How do I unpack ...? See first the main entry #3, especially if your file ends in _tar.tar. If that doesn't help, please read http://www.perl.com/CPAN/ENDINGS 4. Where do I find ...? cpan@perl.org is not a helpdesk for locating miscellaneous software. Locating software from the Internet for some specific purpose would be a full-time job and a highly paid one at that. Writing software to match your needs would be even more expensive. CPAN is maintained by a handful of volunteers in their spare time. However, we can give you some general pointers. Read on. 4.1. ... Perl source code http://www.perl.com/CPAN/src/latest.tar.gz (UNIX-style tar.gz) or http://www.perl.com/CPAN/src/latest.zip (PC-style ZIP, with CR LF line endings) 4.1.1. ... How do I install Perl using the source code? To build Perl you need a C compilation environment. 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) - MacOS 1) - AS/400 2) - Novell Netware 2) For these platforms a binary release (see 4.2. below) may be the easiest path. 1) The source code to compile MacPerl is available, check out the Mac section of 4.2. below. 2) The source codes 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.perl.com/CPAN/ports/as400/ http://www.perl.com/CPAN/ports/netware/ Now continue at http://www.perl.com/CPAN/src/README 4.1.2. ... Where do I find Perl <some ancient version>? Unless you have A Very Good Reason you shouldn't be installing obsolete versions because they might contain bugs. Including 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). You may, however, try whether the dusty Perl release you are after can be found at the Oasis: http://www.oasis.leo.org/perl/ 4.2. ... Perl binaries/executables or Perl module binaries http://www.perl.com/CPAN/ports/index.html 4.3. ... documentation http://www.perl.com/CPAN/doc/index.html http://theory.uwinnipeg.ca/CPAN/perl/pod/index.html 4.4. ... scripts http://www.perl.com/CPAN/scripts/index.html 4.5. ... modules http://www.perl.com/CPAN/modules/index.html or ask at the USENET newsgroup comp.lang.perl.modules. Please be specific in your query: "I WANT PERL PROGRAM FOR WEB" is not likely to elicit helpful responses. 4.5.1. ... GDBM_File 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 in, in 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.T 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. 4.5.2. ... DB_File See 4.5.1. and every time it says GDBM think of DB, GDBM_File needs an external library called libdb, or Berkeley DB. 4.6. ... module documentation http://ls6-www.cs.uni-dortmund.de/ir/projects/SFgate/CPAN/ 4.6.1. ... DBI/DBD/database access documentation http://www.symbolstone.org/technology/perl/DBI/ 4.7. ... Perl FAQs http://theory.uwinnipeg.ca/CPAN/perl/perlfaq.html 4.8. ... Perl mailing lists The Perl Institute (www.perl.org) carries several Perl-related mailing lists http://www.perl.org/maillist.html At the same place you can find pointers to archives of mailing lists. On request The Perl Institute can create new mailing lists. 4.9. ... Perl journals/magazines As of August 1999 there's only one publication dedicated to Perl, the quarterly Perl Journal: http://www.tpj.com/ 4.10. ... Perl courses/training See www.perl.com for the most recent information. 5. How do I search for ...? 5.1. ... anything? http://theory.uwinnipeg.ca/search/cpan-search.html 5.1.1. ... really ANYTHING? http://www.altavista.com/ http://www.hotbot.com/ http://www.lycos.com/ http://www.yahoo.com/ (too many to list) 5.2. ... 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 when your module/script was installed. (Thanks to Perl's pod-style documentation, "it is very hard to misplace your documentation".) In UNIX (and Win32?) environments the commands perlpod Module::Name perlpod scriptname should bring forth the documentation. But if the documentation still seems to be somehow misplaced you can try the following: http://ls6-www.cs.uni-dortmund.de/ir/projects/SFgate/CPAN/ 6. How do I contribute ...? 6.1. ... modules http://www.perl.com/CPAN/modules/04pause.html 6.2. ... scripts http://www.perl.com/CPAN/scripts/index.html 6.3. ... documentation See item 7.1. below. 6.4. ... fixes See item 7. just below. 7. How do I report/fix a bug in ...? 7.1. ... 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. See 7.2. below. Here is a checklist, from "perlbug". It is a bit on the long side, but please read it carefully: the better your bug report, the better its chances of getting fixed. What version of Perl you are running? Type perl -v at the command line to find out. Are you running the latest released version of perl? Look at http://www.perl.com/ to find out. If it is not the latest released version, get that one and see whether your bug has been fixed. Note that bug reports about old versions of Perl, especially those prior to the 5.0 release, are likely to fall upon deaf ears. You are on your own if you continue to use perl1 .. perl4. Are you sure what you have is a bug? A significant number of the bug reports we get turn out to be documented features in Perl. Make sure the behavior you are witnessing doesn't fall under that category, by glancing through the documentation that comes with Perl (we'll admit this is no mean task, given the sheer volume of it all, but at least have a look at the sections that seem relevant). Be aware of the familiar traps that perl programmers of various hues fall into. See the perltrap documentation. Check in perldiag to see what any Perl error message(s) mean. If message isn't in perldiag, it probably isn't generated by Perl. Consult your operating system documentation instead. If you are on a non-UNIX platform check also perlport documentation, some features may not be implemented or work differently. Try to study the problem under the Perl debugger, if necessary. See the perldebug documentation. Do you have a proper test case? The easier it is to reproduce your bug, the more likely it will be fixed, because if no one can duplicate the problem, no one can fix it. A good test case has most of these attributes: fewest possible number of lines; few dependencies on external commands, modules, or libraries; runs on most platforms unimpeded; and is self-documenting. A good test case is almost always a good candidate to be on the perl test suite. If you have the time, consider making your test case so that it will readily fit into the standard test suite. Remember also to include all the exact error messages, if any. "Perl complained something" is not an exact error message. If you get a core dump (or equivalent), you may use a debugger (dbx, gdb, etc) to produce a stack trace to include in the bug report. NOTE: unless your Perl has been compiled with debug info (often -g), the stack trace is likely to be somewhat hard to use because it will most probably contain only the function names and not their arguments. If possible, recompile your Perl with debug info and reproduce the dump and the stack trace. Can you describe the bug in plain English? The easier it is to understand a reproducible bug, the more likely it will be fixed. Anything you can provide by way of insight into the problem helps a great deal. In other words, try to analyze the problem (to the extent you can) and report your discoveries. Can you fix the bug yourself? A bug report which includes a patch to fix it will almost definitely be fixed. Use the diff program to generate your patches (diff is being maintained by the GNU folks as part of the diffutils package, so you should be able to get it from any of the GNU software repositories). If you do submit a patch, the cool-dude counter at perlbug@perl.com will register you as a savior of the world. Your patch may be returned with requests for changes, or requests for more detailed explanations about your fix. Here are some clues for creating quality patches: Use the -c or -u switches to the diff program (to create a so-called context or unified diff). Make sure the patch is not reversed (the first argument to diff is typically the original file, the second argument your changed file). Make sure you test your patch by applying it with the patch program before you send it on its way. Try to follow the same style as the code you are trying to patch. Make sure your patch really does work (make test, if the thing you're patching supports it). Can you use perlbug to submit the report? perlbug will, amongst other things, ensure your report includes crucial information about your version of perl. If perlbug is unable to mail your report after you have typed it in, you may have to compose the message yourself, add the output produced by perlbug -d and email it to perlbug@perl.com. If, for some reason, you cannot run perlbug at all on your system, be sure to include the entire output produced by running perl -V (note the uppercase V). Whether you use perlbug or send the email manually, please make your Subject line informative. "a bug" is not informative. Neither is "perl crashes" nor "HELP!!!" These don't help. A compact description of what's wrong is fine. Having done your bit, please be prepared to wait, to be told the bug is in your code, or even to get no reply at all. The Perl maintainers are busy folks, so if your problem is a small one or if it is difficult to understand or already known, they may not respond with a personal reply. If it is important to you that your bug be fixed, do monitor the Changes file in any development releases since the time you submitted the bug, and encourage the maintainers with kind words (but never any flames!). Feel free to resend your bug report if the next released version of perl comes out and your bug is still present. 7.2. ... a module/script? Please contact the author of the module/script. The documentation of the module/script should contain a contact address. Most of the checklist in 7.1. above applies also here: make your bug report as good as possible if you really want the bug fixed. If the module/script comes with the Perl distribution, follow the instructions of 7.1. 8. How do I join/found 8.1. ... a Perl user group http://www.pm.org/ 8.2. ... a Perl mailing list See 4.8. 9. How do I mirror CPAN? Either by FTP or by rsync. 9.1. ... What do I need? "Good" Internet connectivity, "a lot" of disk, and some software. Good: How many clients do you have? A lot: As of May 1999 at least 750 MB, and growing. The file CPAN/indices/du-k.gz tells you the current size. For FTP there is a Perl script (which assumes a command line FTP client): http://www.perl.com/CPAN/scripts/ftpstuff/scripts/ftpstuff/mirror-2.8.tar.gz The FTP address for the CPAN master site is ftp://ftp.funet.fi/pub/languages/perl/CPAN/ and for rsync http://rsync.samba.org/ The rsync address for the CPAN master site is ftp.funet.fi::CPAN 9.2. ... 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.perl.com/CPAN/SITES.html Please organize the mirroring with the corresponding FTP maintainer (their email addresses from the file http://www.perl.com/CPAN/MIRRORED.BY) so that you will not overload their site and that your mirror starts just after theirs has finished. For your mirror site to be useful to your users you should mirror daily. You can also provide a HTTP interface to CPAN if you want to. 9.3. ... How do I register? Finally, if you want to publicize your CPAN mirror (meaning that other people can use your mirror, too), please fill in the template that can be found from the top of the file http://www.perl.com/CPAN/MIRRORED.BY 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.