I've made some changes, in what I think is the right direction. Feedback always welcome, even if you are only throwing rotten vegetables :)

*****

Introduction:
CPAN.pm is a Perl module that allows you to install and manage other Perl modules, providing you with a command line interface to do so. The first time you run CPAN, you'll be presented with a configuration script that sets variables for your system, and checks your $PATH for the progams, such as "make", that CPAN requires to build the modules you select. This guide aims to walk you through the configuration script and explain the various options and the differences between them.

To root? Not to root? Or perhaps sudo?:
Being an Ubunutu user, a lot of what I do requires the use of sudoers. For the purpose of this guide, I will attempt to highlight the differences between privilaged (root) and non-privilaged (Joe User) configurations, and where the differences between the two may have an impact on your configuration. Assume for the purpose of this guide that wherever you see <sudo>, you should be logged in as root or su'd to root on your system if you have the rights. A quick note: adding sudo functionality to your system is a common good practise, and worth doing if you haven't already. A Google Search will pull up a myrid of helpful results, or you can man sudoers to find out more.

Top to bottom: installing as root.
For the sake of this part of the guide, I'll make the crass assumption that you can root / su / sudo for the configuration of CPAN. I've included some catch-me's at the bottom that you will want to be aware of if you cannot, or simply do not want to, do this as a superuser. Open your terminal of choice and type the following:

<sudo> perl -MCPAN -e 'shell'

The CPAN script will launch, providing you with a brief description of what CPAN.pm is about and what it can do for you. It'll also provide some small comfort for those of you unhappy at the prospect of poking at your system, this being that the configuration can be done automatically. This may however gloss over some important things, like the fact that Ubunutu out the box lacks "make", which CPAN needs to build modules. Taking a few minutes to go through the config is well worth it. Once you've confirmed that you wish to start installing manually, you're ready to go.

Setting your build and cache directories:
The first options ask where you'd like to create the build and cache directories. By creating these, you can save source files for the modules you build, so should something break, or you remove a module and want it back, the build can be run quicker second time around. The default location for these directories is set to /root/.cpan. Pick somewhere where you have a lot of space. You could create these directories in /usr/share/cpan for example, where they're not tied into a single account's home dir. Next, you're asked to specify a size, the default setting being 100Mb. Unless you build *everything* in CPAN, this is fair for the majority of people. You also have the option of setting this to 0, which means that no data will be cached, and should you rebuild a module in future, you'll be pulling it from a repository on the web. Once you've done this, you'll be asked about Cache Scanning. Scanning provides two options, namely atstart and never. Choosing atstart will scan your cache every time CPAN is initiated, keeping the cache size in sync with your chosen settings. Choosing never is pretty self explanetory, and means CPAN will not regulate the current size of your cache. If you picked a 100Mb or more, I doubt you have much to worry about.

Storable - caching metadata:
To make CPAN run quicker when you start it, you can select to use Storable to cache metadata on modules within CPAN. As this stores a small subset of information on available modules, CPAN has less to "read" through and is therefore quicker. If you do not choose to cache this metadata, or the cache is somehow unavailable, standard indexing will be used to gather the same information, albeit fractionally slower.

Terminal charset:
Most module names are in English, so a UTF-8 or ISO-8859-1 character set will work fine. However, the script does point out that some aliens upload modules that have names outside the ASCII range. So if you plan on installing a full whack of modules written by Daleks or Klingons, you'll have a few problems. Otherwise, the options provided will suffice. To use ISO-8859-1, answer yes, and to use UTF-8, answer no

Little bit of history repeated:
This option, provided you have Term::ReadLine::Perl or Term::ReadLine::Gnu installed, will give your CPAN command line interface history support. It's questions deal with the location of the histfile and how many lines it should save. I elected to add the histfile to the /usr/local/share/cpan directory I chose earlier, and kept the default 100 lines, figuring that this is more than enough command history for CPAN to remember.

Upload date for modules and distributions:
From the command line interface, you can specify d or m. These commands, by default, show you the upload dates that the commands have in memory, and should not require an Internet connection to lookup against http://www.cpan.org. If you were to set the show_upload_date variable to true, d and m will try to lookup the upload dates of the modules and distributions themselves, which may require a trip across the web to accomplish. With always on broadband a common tool now, you can safely set this option to yes. If you don't like the idea of your machine trying to lookup date information from the packages themselves when you run these commands, play it safe and set to no

Handling Dependencies:
CPAN has three distinct methods for handling any dependencies that crop up while you are building modules. These are follow, ask and ignore. Ignore is easy. CPAN will simply pretend that the dependency does not exist, that it wasn't asked and will soldier on without even thinking about building the required dependency. This is probably a good way of making sure that your system breaks routinely. Follow is the exact opposite of ignore in that it will build every dependency without stopping to consider any consequences, such as updating a module for your current build that may just break something else that you use. Which is annoying. This leaves us with ask. Should the issue of a dependency crop up during a build, CPAN will ask you what to do. This gives you final say in what CPAN builds or updates. If you ask me (no-one does but I live in hope), I'd tell you to chose ask. This also has the added benefit of not making CPAN build the latest stable Perl during a dependency update.

A supporting cast of programs:
We're making good progress here. At this point in the config, CPAN will be wanting to know where the various tools it needs to unpack and make your modules are. These can be broken down into programs that uncompress, unpack, build and fetch your modules. It is safe to assume that the majority of modules are going to be compressed using BZip2 or GZip, packed with tar, will require make for the actual build, and tools like wget (HTTP and FTP) to retrieve packages. The programs that CPAN asks you about are pretty common Unix fare, and should be familiar to anyone who uses a Unix/Linux/BSD operating system. All CPAN is asking is for you to confirm that you want it to use a particular program, and if so, where it can find it. It's safe to say that most programs are going to be found in /bin and /usr/bin. If you aren't sure, a quick which <program-name> will reveal the path. If the path doesn't match the config default, replace it with your own. Of course, if which returns no path, the program is more than likely not installed, or installed outside of the $PATH for your system. In this case, locate or slocate (both have man pages) may help. If you need to install something, use your package manager of choice (apt-get, pkg_add, yum) for your distro. You can install a program and then point your CPAN config at the directory where the new app was installed to. At this point, you'll also be asked which shell you use. If you aren't sure, one way of checking is to type w in your terminal, which will print out the name of your shell under WHAT. Of course, if you see a program that you don't want to install, you can make CPAN ignore it by typing space once and then enter to move on.

Module::Build
Inside of every module you build, there is a Makefile.PL, which specifies build instructions, dependency information and more for make. At this point, your configuration script will be politely waiting for you to tell it which of the two build methods available you would like to take precedence. Pick EUMM, or ExtUtils::MakeMaker if you will, as the Makefile.PL seems to be by far the most popular method by module owners. In the event of Makefile.PL being absent, there will be a build.PL, and your CPAN will happily fall back to using this. All you're doing at the moment is instructing CPAN to use Makefile.PL first if both exist inside the module you wish to deploy.

Parameters? WTF???:
I only had one comment the first time CPAN asked me this, and that question was "que?" (ala Manuel from Faulty Towers). I understand the basic principles of passing prefixes to build instructions, telling the complier to build me a package in X location --with Option A but --without Option B. The config lets you know that a non-root user can pass PREFIX=~/perl, but as a basic rule of thumb, if there's no burning, must have, flashy light, bell and whistle option you want applied to modules you build, then simply aim your pointing finger at enter and skip to the next parameter, which is...

-j3 # dual processor system

Last time I checked, there was only one silcon and transistor sandwich cooking in the guts of my notebook. Again, I'm afraid I'm voting with my finger, leaving the option set to [] and moving on.

Make Install:
Okay, now we're ready to rub some funk on this. Up until this point, CPAN has been concerned with manipulating modules, unpacking and uncompressing them, checking the Makefile for instructions, passing any custom requirements on to the builder and so on. Now, it wants to know what to do when we reach critical mass and actually install something. While you're configuring CPAN as root (we're assuming, remember...), it's highly unlikely that you're running as root all the time. I hope. To this end, it may be a good idea to pass CPAN a parameter that will allow it to su to root, or execute sudo. In either scenario, your chosen method will execute, wait for a password and then allow CPAN to resume in its higher user mode to install the software, without going Norman Bates and freaking out about lack of permissions. To set this up, you could use:

  1. sudo make
  2. sudo /usr/bin/make
  3. su root -c make
I personally have an unhealthy obsession with sudo, so I'd pick option 1. Just ensure that sudo is configured for your system.

UNINST:
This option will allow CPAN to uninstall potentially conflicting files while building a new module. What will happen here, is that files in the current build will take precedence over files already on the disk. There is only the slimmest chance that anything will break (extremely remote methinks), but forewarned is forearmed.

Build.PL options:
The above options have seen CPAN concerning itself with what to do when you build modules for your EUMM preference, which is to use the Makefile.PL script. Here, CPAN wants similar information for the alternate option, using Build.PL. The choices are the same here as for Makefile. If you need to install to a different directory than the default Perl location (typically /usr/bin/perl), specify it, as well as the location of any additional libraries you may need. Again, if no alarm bells sound, you can take the default options here. The UNINST option for Build.PL is --uninst 1 to uninstall any potentially conflicting files.

Awaiting input...
Sometimes, a Makefile will contain a question (how long is a piece of string?) that you need to answer before the build can proceed. The default timeout setting is 0 (all times in seconds), which means that CPAN will wait forever for you to answer. I recommend sticking to this, as if you set a 30 second timeout and have to walk away, you may miss the opportunity to do something important. Far better time wasted at this point than trying to suss out why x won't work later ;)

Proxy information:
If there are any HTTP or FTP proxies between you and the Internet, CPAN wants to know about them. If your proxy has a username and password requirement, the next option will allow you to enter this information.

Stand in the place where you live...
CPAN will now ask you for your closest geographical location so that it may match you with the closest (typically fastest) CPAN repository on the web. Once you've entered your Continent/Country info, you'll be provided with a list of mirrors to chose. You can select one of them, all of them or a selection, based on your preference. For example, South Africa has three repos, so I chose 1 2 3 (separate repo numbers with spaces). CPAN will then be able to go from one to the other down the list until it finds a CPAN repo that works. If there is a CPAN repository that you know of that the config script doesn't (say your over zealous admin has a copy on a local fileserver), you have the option to add that too.

The light at the end of the tunnel...
...and just like that, we're back at cpan>. You have completed your configuration of CPAN on your system. Nice one! Stick around however. There are a few more things to discuss.

Check what you done!
The bad English is on purpose, alluding to the fact that CPAN has a quick and easy way of checking out your config, which is to type o conf on the command line. This will produce a neatly formatted list of the variables you input. Cool eh? But, what if you notice something amiss? Do you have to go through all that again. You can. Just type o conf init to re-run the script. There are better ways to make changes though...

...and these are...
All of the values you've just specified are written to Config.pm, which you can edit by hand in any number of text editors. There is a much better way. Much better. If you ran o conf earlier, you'll have seen the list of variable names flanked on the right by their values. The following sequence of commands would, for example, allow me to reset my histfile size from the 100Mb I specified earlier, down to 10Mb.

  1. o conf histfile shift
  2. o conf histfile 10
  3. o conf histfile
Command 1 wipes the existing value from the histfile variable, while Command 2 writes in 10 as the new value. Command 3 simply confirms that the change has been made. By going o conf <var> <action> with any of the names listed by o conf, you make changes to your config on the fly. So, if I've led you down the garden path with this guide, you can fix my errors on the fly without cursing me too much. Before I forget, to commit your changes to the Config.pm file, just type o conf commit, and save the change for prosperity.

To the stars and beyond.
You are now ready to tap into the rich, rich world of CPAN modules, where thousands of developers have input millions of hours into creating a vast resource of modules built for everything from parsing a simple XML documents to complex physics modelling. I have a link to the ideal tool to get you started on your journey. To find out about actually using and installing modules, read this tutorial by tachyon.

Whoa there tiger! What about non-root users!!!
Indeed. What about non-root? No fear here.

What you're aiming to achieve is a configuration where modules install under something like /usr/local/share/perl, manuals go under /usr/share/man and everything else goes under /home/me/.cpan. The settings are as per this guide, you've just got to enter them by hand at first.

That's it from me on the subject of CPAN configuration. Thank you for taking the time to read my debut Perl Monks node!

Replies are listed 'Best First'.
Re: RFC: CPAN config guide for newcomers
by xdg (Monsignor) on Aug 28, 2006 at 23:15 UTC

    This is a great start -- though a bit of a quick-start at that, as it's more of a description of what happens than a guide for what to do. Here are some suggestions for where to go next:

    • Distinguish between "ordinary user" installs and "root" installs -- the decisions for some options are often quite different. (e.g. PREFIX). You might want to lay out the scenarios at the start and then refer to them as you go.

    • Have one entry for each option -- right now, the text blurs many of them together.

    • Provide some recommendations and rationale (or pros/cons) of different choices. E.g. why "follow" prerequisites versus "ask". This will be more helpful than just a description of the different choices.

    • Describe how to manually tweak options afterwards with "o conf option" and "o conf commit".

    If you expand this guide, consider writing it in Pod and submitting it to Andreas Konig (the CPAN maintainer). Perhaps it can be included in a future release.

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

Re: RFC: CPAN config guide for newcomers
by Milamber (Beadle) on Aug 29, 2006 at 23:33 UTC
    Thank you very much for your comments. Very helpful. I rewrote large chunks of it last night in response, and I think it's going the right way. I didn't however stick with the trend of combining related aspects into single sections, though I think the slightly better layout offsets this and makes it less of a problem.

    If the world is my oyster...then where the hell is my pearl?
Re: RFC: CPAN config guide for newcomers
by tphyahoo (Vicar) on Sep 01, 2006 at 14:47 UTC
    Overall, a great contribution to the monastery.

    However, I take issue with your comments after "Whoa there tiger! What about non-root users!!!"

    "No fear here", in my opinion, is wrong.

    At least, it's wrong if you try to do things by monkeying with your environment.

    The proper solution, in my experience, is to install perl locally.

    As a non-root user on a shared web space -- typical scenario, I figure -- the only thing that would prevent you from doing that is lack of compile tools and lack of space. And in 2006, if your web hoster is cheaping you on either of these, you probably should look for a new web hoster.

      I think I may sometimes take too much for granted, owing to the fact that, at the end of the day, I own every system I work on. Therefore, I tend to miss things. I think I'll go away and read your article, and ponder the consequences. It might also serve me well, in light of the fact that I plan to write more, to have a box and effectively "forget" root on it, test any future writeups there before I run off an go moggy with the text editor. Thank you for the pointer. Much obliged.

      If the world is my oyster...then where the hell is my pearl?