# Perl/Modules on CPAN

As you learn to use Perl you'll use more than just the language syntax. In order to use it effectively, you'll need to learn to use modules from the Comprehensive Perl Archive Network (CPAN). This is an invaluable resource for the Perl community - and like many other Open Source projects, it's entirely operated by volunteers and generous sponsors. Many people around the world contribute to CPAN in the following ways:
* They write Perl modules for CPAN, or submit patches and bug reports to authors.
* They provide servers which provide local mirrors of the modules in their part of the world.
* They test modules which others have uploaded and report their results.
* And there are more ways to contribute.
* Online Resources
* Remember and save these references. You will use them when developing any significant amounts of Perl code.
* The CPAN web site is at http://www.cpan.org/ which includes lists of popular CPAN modules. But remember there isn't a single page with all the CPAN modules - there are just too many for that.
* A CPAN search engine is at http://search.span.org/

## Installing Perl modules from CPAN

Your perl installation should come with the perlmodinstall manual page which documents how to install Perl modules from CPAN. We'll include a summary here. But you should also refer there for specifics for your system, whether you're on a Unix, Windows, Mac or other system.
Perl comes with the CPAN.pm module which handles most details of downloading, building and installing Perl modules from CPAN. It even loads other modules that are dependencies of the modules you request, if needed. One thing you'll quickly notice is that all Perl modules, whether from CPAN or direct from their authors, end in a .pm file suffix. It stands for "perl module". When installed on your system in a directory where Perl can find it, it can be used by any Perl script simply by its name.

### Making your own CPAN workspace

In order to learn how to use CPAN without needing system administrator privileges or interfering with system-wide modules already installed on your system, you'll want to make a private workspace.
On systems with a command line shell (Unix, Mac and Windows/Cygwin), you can use this shell script. (Windows users on Cygwin can run the script but will need to use backslashes (\) instead of slashes (/) in directory paths. )
Call the script "cpan-wv" so that we're all using the same name for it in the following discussion.
In order to make the script executable, don't forget to run "chmod a+rx cpan-wv" on it. Then run the script just as "cpan-wv".
The first time you run it, you will see that CPAN is initializing some data files. We have a little work to do helping CPAN settle down on your system. This is just a one-time setup - then you can benefit from it every time you run cpan-wv in the future. Here are prompts you'll see and answers you should give it. In each case, if there is a default answer, it will be in square brackets - that's what you'll get if you just hit Enter. The defaults that are presented to you will probably differ in some cases on your system as Perl determines a different answer is more appropriate. In most cases, the default will be correct or good enough.
Hit Enter.
Hit Enter at each of these prompts.
For this one, we're going to have CPAN do more work for us. Tell it "follow" and hit Enter.
That means that when CPAN identified other modules which are dependencies of ones that you request, it will automatically install them too. In some cases modules have so many dependencies that it would be tedious to have to approve each and every one. It's acceptable to do this automatically for your personal workspace. You might or might not choose to do that for a production server depending on your circumstances.
Hit Enter at each of these prompts. Optionally, if any are blank, Perl didn't find the program. If you have it and know where it is, you can enter its full path.
Hit Enter for all of these. One of these parameters was already provided by the cpan-wv script. Some of the defaults are coming from Perl, which saved information about how it was built on your system.
Then you'll be prompted for your network configuration.
If you need to tell CPAN to access the Internet through a proxy, this is the place to do it. If you don't know, then hit Enter. If that doesn't work, ask your system administrator or service provider what network settings you should use.
On the next step, you're on your own for a moment. You need to select one or more CPAN mirrors that you will use. Select your continent and country to find servers which are in your part of the world. If there aren't any servers in your country, try the nearest country listed that you expect will be closely connected to yours by telecommunications lines.
Tip: you can use the ping and traceroute commands to test which servers are responsive and nearest to your location.
When you find three good ones, call it done and move on. If you can't find three nearby, use the nearest two you can find and add http://www.perl.com/CPAN/ as the last one.
With that CPAN will save the configuration. It will use it again when you run "cpan-wv".
* Exercise: install your first CPAN module
* The cpan-wv script above leaves you in the CPAN shell. When you want to exit, just use your operating system's end-of-file key (usually CTRL-D on Unix and CTRL-Z on Windows).
* At the CPAN shell prompt, type the following command, which will install a Perl module from CPAN called Wikiversity::Hello.
* install Wikiversity::Hello
* If there are any build, install or test errors, the module will not be installed. You'll need to read the errors to determine if there's anything you need to change or fix on your system.
* Once the module is installed, you should be able to bring up documentation. Exit from cpan-wv back to the system shell. Since it's in your workspace, we need to give Perl its location. Just add "lib" to the path you used in cpan-wv for your workspace path - that's a directory which CPAN created in your workspace. So use that path in the "-I" parameter in the following command.
* perldoc -I/home/username/cpan/lib Wikiversity::Hello
* You can run the code with this command, making the same addition to Perl's module path so that it can find it in your workspace.
* perl -I/home/username/cpan/lib -MWikiversity::Hello -e hurrah
* When everything works, you will receive words of congratulations. That's all this module does.