CPAN Search FAQ

Frequently Asked Questions

1. What does this site run on?
2. Why is "Module X" missing?
3. Why is "Module X" missing, yet it appears on search.cpan.org?
4. Why is the documentation for "Module X" missing?
5. Why are some, or all, of the package prerequisites missing?
6. What is the syntax for queries?
7. How do I use the ppm respositories that appear?
8. Are there any other search engines for CPAN?
9. What conventions are employed that may be used for external links?
10. I found a problem. Who do I contact?
11. Is the source code for running this site available?

What does this site run on?

  The basic machine is a linux box. Software used includes mysql, Apache and mod_perl, Template-Toolkit, and, of course, Perl. The multiplexer used to redirect downloads to (hopefully) nearby CPAN mirrors is based on GeoIP. The network connection is provided by the University of Winnipeg.

Why is "Module X" missing?

  Assuming that it has been indexed successfully on CPAN, and that sufficient time has elapsed so that the local mirror has picked it up, this may be due to the distribution following a non-conventional structure. In particular, it is assumed here that the distribution unpacks into a subdirectory derived from the name of the distribution, and that the distribution name and a valid version string are extractable using Graham Barr's CPAN-DistnameInfo module.

Why is "Module X" missing, yet it appears on search.cpan.org?

  The indexing used is based on the CPAN indices, which is more restrictive than what search.cpan.org uses. Thus, if a module doesn't appear here, chances are it also will be missing from tools like `CPAN/CPANPLUS`. This can be due to a number of reasons - it may be a development version (indicated as such with an underscore in the distribution's version number), or it may not be registered with PAUSE, or perhaps registered but under a different CPAN id. Note also that only the most recent versions of distributions are kept in the database, which thus excludes modules existing only in older versions of distributions from appearing.

Why is the documentation for "Module X" missing?

  This may be due to problems extracting the pod and/or converting it into html. Another possibility is that it doesn't conform to the assumed convention for the `NAME` section of the pod that the name of the module is specified. Finally, it may be that it is present, but not in a standard location - you can check, for example, http://cpan.uwinnipeg.ca/htdocs/libnet/ for a listing of all documents associated with a given distribution.

Why are some, or all, of the package prerequisites missing?

  Information for the prerequisites is extracted from a file `META.yml` within a distribution. Not all distributions have this file, as it is generated when making a distribution only with relatively recent version of either `ExtUtils::MakeMaker` or `Module::Build`.

What is the syntax for queries?
  - A basic query such as for `foo bar` will search, depending on the search type specified, through module names and abstracts, distribution names and abstracts, or CPAN ids and full names, and return results matching all query terms specified. In searching through abstracts, only search terms longer than two letters will be used.
  - If you wish to exclude a search term from the results, prepend that term with a minus sign (eg, `foo -bar`).
  - Searches may also be made using regular expressions - these are recognized by the appearance of one or more of the characters `^, $, *, +, ?, |` in the query term.
How do I use the Win32 ppm respositories?

  Consult the documentation that comes with ActivePerl for general directions for using ppm. The ppm packages that appear here can be installed with the ppm utility. For the ActivePerl packages, you should just be able to install the package as `install Package-Name` from within the ppm shell; for the other packages, you may have to add the indicated location to your list of repositories:

  - http://www.bribes.org/perl/ppm, for the Perl 5.6/5.8 bribes repository
  - http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer, for the uwinnipeg Perl 5.6 repository
  - http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer58 (ActivePerl Builds < 819) / http://theoryx5.uwinnipeg.ca/ppms/ (ActivePerl Builds >= 819), for the uwinnipeg Perl 5.8 repository

  Make sure that you use a repository appropriate for your Perl version (5.6 repositories for ActivePerl builds 6xx, and 5.8 repositories for ActivePerl builds 8xx). Also note that the name of the package that appears here, based on the CPAN distribution name, is the one to use when installing a package; this often, but not always, corresponds to the name of the main module in the package.

  If you maintain a ppm repository and wish it included in the database here, at present a summary.ppm summary file of available ppm packages on the repository is required. How to generate this is described in a script available in the PPM distribution on CPAN. After generating this, please contact Randy Kobes with details of your repository.

Are there any other search engines for CPAN?
  Yes.
  - search.cpan.org.
  - www.perldoc.com.
  - wait.cpan.org.
What conventions are employed that may be used for external links?
  - A link such as http://cpan.uwinnipeg.ca/~gbarr will bring up information on the CPAN author with id `GBARR`.
  - For information on a particular distribution or module, use a link such as http://cpan.uwinnipeg.ca/dist/libnet (for distributions) or http://cpan.uwinnipeg.ca/module/Net::FTP (for modules). For distributions, http://cpan.uwinnipeg.ca/~gbarr/libnet also can be used, if you know the CPAN author.
  - For alphabetical listings of distributions or modules, use http://cpan.uwinnipeg.ca/dist/A/ or http://cpan.uwinnipeg.ca/module/A/ for all distributions or modules beginning with a certain letter. Use http://cpan.uwinnipeg.ca/dist/Apache/ or http://cpan.uwinnipeg.ca/module/Apache/ to list, respectively, distributions matching `Apache-*` or modules matching `Apache::*`. Note the trailing forward slash in these links.
  - For linking to a category listing, one can use http://cpan.uwinnipeg.ca/chapter for the main chapter headings, http://cpan.uwinnipeg.ca/chapter/World_Wide_Web_HTML_HTTP_CGI for a specific chapter, and http://cpan.uwinnipeg.ca/chapter/World_Wide_Web_HTML_HTTP_CGI/Apache for a subchapter.
  - Links to documents for particular modules can be made as http://cpan.uwinnipeg.ca/htdocs/libnet/Net/FTP.html for finding the documentation for `Net::FTP` in the `libnet` distribution. Alternatively, one can use http://cpan.uwinnipeg.ca/perldoc?Net::FTP. (this also works for the core perl documentation - for example, http://cpan.uwinnipeg.ca/perldoc?perlfaq will bring up the perlfaq documentation). Note that these documentation links may not work for all modules, for a variety of reasons, mostly to do with conventions assumed in the CPAN indices and the form of the pod documentation found in the distribution.
I found a problem. Who do I contact?

  Please email Randy Kobes if you encounter problems, including broken documentation links and errors in translation. Please include details (and links) of what you were doing when the problem occurred.

Is the source code for running this site available?

  Yes. See the CPAN-Search-Lite project on SourceForge. A mailing list is available there for asking questions on setting things up, discussing bugs, and for proposing enhancements and features. Note that this project is not intended to "compete" with (the amazing) search.cpan.org, which contains a number of features not present here (previous releases of distributions, `grep` and `diff` capabilities, etc.). One direction this particular code may take is towards services other than standard web ones (for example, soap-based tools).