chrislale@users.sourceforge.net
Revision History | ||
---|---|---|
Revision 0.01 | 8 May 2004 | Revised by: cl |
Initial release. |
CPAN is the Comprehensive Perl Archive Network (http://www.cpan.org). It contains a large number of Perl modules. Some of the modules are grouped together in bundles. The modules are the Perl equivalent of Debian .deb packages, and the bundles are like Debian tasks. (You use the Debian task installer tasksel to install Debian tasks.)
This article assumes that you only have the minimum base install of Debian GNU/Linux. You probably have much more installed (eg the x window system, gnome, kde etc). Even so, you can follow these instructions in full to make sure that everything you need is installed. If you try to install a package that is already installed on your system, Debian will tell you so and exit gracefully.
You carry out all the work from the command line, logging in as a normal user and using su to obtain Root user (superuser) privileges. You may find it convenient to use a second terminal, or a terminal window, to manage your internet connection and to perform checks while CPAN.pm is running in the first terminal.
Log in as a normal user. Switch user to user Root.
$ su # |
Use <CTRL><ALT><F2> to access a second terminal, log in as a normal user and switch user to Root.
$ su # |
Switch between the two terminals using <CTRL><ALT><F1> and <CTRL><ALT><F2>.
Log in as a normal user and start an X session. Open a terminal window (eg gnome terminal).
Switch user to user Root.
$ su # |
Open a second terminal window and su to user Root.
$ su # |
You need a C compiler to build modules from the downloaded files. You may need some other C packages. The easiest way to make sure that you have everything you need is to install the C and C++ task in the 'Development' section of the Debian task installer tasksel.
Work in the first terminal or terminal window. Enter the tasksel command.
# tasksel Debian Task Installer v1.18 - (c) 1999-2001 SPI and others |
Use the arrow keys to move the cursor to C and C++ in the 'Development' section. Press the space bar to tag C and C++ with an asterisk. (If you cannot find C and C++, the task has already been installed. Skip to the next section.)
-------------------| Select tasks to install |------------------- -- Development ---------------- [*] C and C++ |
Use the <TAB> key to highlight <Finish> (in blue) and press <ENTER>
<Finish> |
Installation of the Debian packages proceeds normally. Follow the instructions on the screen.
You must have Perl! You can check which version you have by invoking perl with the -v switch.
# perl -v This is perl, v5.6.1 built for i386-linux ... |
It is highly unlikely that perl is not already installed on your system. If necessary, you can re-install it using apt.
# apt-get install perl |
You should also install the perl-modules package of architecture independent library files for Perl.
# apt-get install perl-modules |
CPAN.pm is a Perl module that accesses the CPAN archive. CPAN.pm is provided by the perl-modules package. You can check that CPAN.pm has been installed successfully by invoking cpan with the -v switch.
# cpan -v cpan script version 1.01 CPAN.pm version 1.59 |
You need a pager. A pager is a program that lets you see a long file or list one screenful at a time. A base install of Debian includes the pager more. If you have not already done so, you may like to take this opportunity to install less. less is a program similar to more, but it allows backwards movement in the file as well as forwards movement.
# apt-get install less |
There are a few other Debian packages that you need:
ftp - an internet file transfer program using the File Transfer Protocol
lynx - a general purpose distributed information browser for the World Wide Web
make - GNU make utility to maintain groups of programs
ncftp - a browser program for the File Transfer Protocol
unzip - a program to list, test and extract compressed files in a ZIP archive
wget - a utility for non-interactive download of files from the World Wide Web
The simplest thing is to try to install them all using apt. apt will tell you which ones you have already and which ones it will install.
# apt-get install ftp lynx make ncftp unzip wget |
You may need to search for files on your system using locate. Now would be a good time to bring locate.s database up to date.
# updatedb # |
You can check the database by trying to locate one of your newly installed files. For example, to locate CPAN.pm:
# locate CPAN.pm /usr/share/perl/5.6.1/CPAN.pm # |
If you have a dial-up internet connection and only one terminal, now is the time to consider making the connection. If you are using a second terminal to manage the connection, you can wait a bit longer.
Open a CPAN shell in your first terminal. This allows you to work interactively with the remote archive.
# perl -MCPAN -e shell /usr/share/perl/5.6.1/CPAN/Config.pm initialized. CPAN is the world-wide archive of perl resources. It consists of about 100 sites that all replicate the same contents all around the globe. Many countries have at least one CPAN site already. The resources found on CPAN are easily accessible with the CPAN.pm module. If you want to use CPAN.pm, you have to configure it properly. |
Now to the real business.
Since this is the first time that you have used CPAN.pm, you must spend a few minutes configuring it. You need to tell CPAN.pm your geographical location and where to find certain programs on your system. You must also choose some CPAN mirror sites and a WAIT server on the internet. Do not worry if you do not understand any configuration questions - just choose the default and you should be OK.
If you do not want to enter a dialog now, you can answer 'no' to this question and I'll try to autoconfigure. (Note: you can revisit this dialog anytime later by typing 'o conf init' at the cpan prompt.) Are you ready for manual configuration? [yes] |
Press <ENTER> to accept the default.
The following questions are intended to help you with the configuration. The CPAN module needs a directory of its own to cache important index files and maybe keep a temporary mirror of CPAN files. This may be a site-wide directory or a personal directory. First of all, I'd like to create this directory. Where? CPAN build and cache directory? [/root/.cpan] |
Press <ENTER> to accept the default.
If you want, I can keep the source files after a build in the cpan home directory. If you choose so then future builds will take the files from there. If you don't want to keep them, answer 0 to the next question. How big should the disk cache be for keeping the build directories with all the intermediate files? Cache size for build directory (in MB)? [10] |
Press <ENTER> to accept the default.
By default, each time the CPAN module is started, cache scanning is performed to keep the cache size in sync. To prevent from this, disable the cache scanning with 'never'. Perform cache scanning (atstart or never)? [atstart] |
Press <ENTER> to accept the default.
To considerably speed up the initial CPAN shell startup, it is possible to use Storable to create a cache of metadata. If Storable is not available, the normal index mechanism will be used. Cache metadata (yes/no)? [yes] |
Press <ENTER> to accept the default.
The next option deals with the charset your terminal supports. In general CPAN is English speaking territory, thus the charset does not matter much, but some of the aliens out there who upload their software to CPAN bear names that are outside the ASCII range. If your terminal supports UTF-8, you say no to the next question, if it supports ISO-8859-1 (also known as LATIN1) then you say yes, and if it supports neither nor, your answer does not matter, you will not be able to read the names of some authors anyway. If you answer no, names will be output in UTF-8. |
If you use LATIN1 characters, say yes.
Your terminal expects ISO-8859-1 (yes/no)? [yes] |
The CPAN module can detect when a module that which you are trying to build depends on prerequisites. If this happens, it can build the prerequisites for you automatically ('follow'), ask you for confirmation ('ask'), or just ignore them ('ignore'). Please set your policy to one of the three values. |
CPAN prerequisites are like Debian dependencies. When CPAN.pm is building a module it may find that it needs to build another module first. Choose 'ask', and CPAN.pm will always tell you what it is about to do and wait for you to tell it to continue.
Policy on building prerequisites (follow, ask or ignore)? [ask] |
Press <ENTER>.
This should be a straightforward confirmation of program paths. You installed these programs in the section on installing other Debian packages.
The CPAN module will need a few external programs to work properly. Please correct me, if I guess the wrong path for a program. Don't panic if you do not have some of them, just press ENTER for those. To disable the use of a download program, you can type a space followed by ENTER. |
If you want to be doubly sure, or if CPAN.pm cannot find a particular program, switch to your second terminal and runlocate. For example, to check the location of gzip, pipe the output of locate to a pager.
# locate gzip | less /bin/gzip ... |
However, CPAN.pm should find all the program paths. All you need to do is to accept each default answer by pressing <ENTER>.
Where is your gzip program? [/bin/gzip] Where is your tar program? [/bin/tar] Where is your unzip program? [/usr/bin/unzip] Where is your make program? [/usr/bin/make] Where is your lynx program? [/usr/bin/lynx] Where is your wget program? [/usr/bin/wget] Where is your ncftpget program? [/usr/bin/ncftpget] Where is your ftp program? [/usr/bin/ftp] What is your favorite pager program? [/usr/bin/less] What is your favorite shell? [/bin/bash] |
Press <ENTER> for each question to accept the default.
This is where the options become a little more obscure. As usual, if you don't understand the question, accept the default answer (which may be empty) by pressing <ENTER>.
Every Makefile.PL is run by perl in a separate process. Likewise we run 'make' and 'make install' in processes. If you have any parameters (e.g. PREFIX, LIB, UNINST or the like) you want to pass to the calls, please specify them here. If you don't understand this question, just press ENTER. |
Parameters for the 'perl Makefile.PL' command? Typical frequently used settings: POLLUTE=1 increasing backwards compatibility LIB=~/perl non-root users (please see manual for more hints) Your choice: [] |
Press <ENTER> to accept the (empty) default.
Parameters for the 'make' command? Typical frequently used setting: -j3 dual processor system Your choice: [] |
Press <ENTER> to accept the (empty) default.
Parameters for the 'make install' command? Typical frequently used setting: UNINST=1 to always uninstall potentially conflicting files Your choice: [] |
Press <ENTER> to accept the (empty) default.
Sometimes you may wish to leave the processes run by CPAN alone without caring about them. As sometimes the Makefile.PL contains question you're expected to answer, you can set a timer that will kill a 'perl Makefile.PL' process after the specified time in seconds. If you set this value to 0, these processes will wait forever. This is the default and recommended setting. Timeout for inactivity during Makefile.PL? [0] |
Press <ENTER> to accept the default.
If you are using a dial-up connection but you are not yet connected, now is the time to dial up.
Switch to the second terminal and turn ppp on.
# pon # |
Switch back to the first terminal. If yours is a home PC, you probably do not use proxies. Just answer each question with an empty string by pressing <ENTER>.
Your ftp_proxy? Your http_proxy? Your no_proxy? |
Press <ENTER> for each question (unless you know that you are using proxies).
CPAN.pm helps you to choose the nearest ftp sources.
Ignore messages about installing bundles of other modules.
You have no /root/.cpan/sources/MIRRORED.BY I'm trying to fetch one LWP not available |
Ignore any messages like this.
Please, install Net::FTP as soon as possible. CPAN.pm installs it for you if you just type install Bundle::libnet |
Perl's '::' syntax | |
---|---|
'::' in Perl translates into '/' in the pathname. When you install 'Net::FTP', the FTP.pm module is placed in a subdirectory 'Net' eg ,/usr/local/share/perl/5.6.1/Net/FTP.pm'. |
CPAN.pm fetches information about ftp servers from the main Perl ftp site, ftp://ftp.perl.org.
Trying with "/usr/bin/lynx -source" to get ftp://ftp.perl.org/pub/CPAN/MIRRORED.BY ... |
Select your continent from the list.
(1) Africa (2) Asia (3) Central America (4) Europe (5) North America (6) Oceania (7) South America |
If you are in Europe, enter 4.
Select your continent (or several nearby continents) [] 4 |
Select your country from the list.
(1) Austria (2) Belgium (3) Bosnia and Herzegovina ... (30) Turkey (31) Ukraine (32) United Kingdom |
If you are in the United Kingdom, enter 32.
Select your country (or several nearby countries) [] 32 |
Select your mirror ftp sites from the list.
(1) ftp://cpan.etla.org/pub/CPAN (2) ftp://cpan.teleglobe.net/pub/CPAN (3) ftp://ftp.demon.co.uk/pub/CPAN/ (4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/ (5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ (6) ftp://ftp.mirror.anlx.net/CPAN/ (7) ftp://ftp.plig.org/pub/CPAN/ (8) ftp://usit.shef.ac.uk/pub/packages/CPAN/ (9) http://cpan.hambule.co.uk/ |
Choose two or three mirror sites in case one of them becomes unavailable during download.
Select as many URLs as you like, put them on one line, separated by blanks [] 5 3 |
You can add more mirrors, or exit by pressing <ENTER>.
Enter another URL or RETURN to quit: [] |
You get confirmation of the site(s) that you picked, and CPAN.pm goes straight on to finding a WAIT server.
New set of picks: ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ ftp://ftp.demon.co.uk/pub/CPAN/ |
WAIT support is available as a Plugin. You need the CPAN::WAIT module to actually use it. But we need to know your favorite WAIT server. If you don't know a WAIT server near you, just press ENTER. Your favorite WAIT server? [wait://ls6.informatik.uni-dortmund.de:1404] |
Make your choice. In this case there is only one server in the list, so just press <ENTER> to accept it.
That's it. CPAN.pm writes and commits a configuration file /usr/share/perl/5.6.1/CPAN/Config.pm.
commit: wrote /usr/share/perl/5.6.1/CPAN/Config.pm |
You are now up and running, and ready to install your first module or bundle from CPAN.
cpan shell -- CPAN exploration and modules installation (v1.59_54) ReadLine support available (try 'install Bundle::CPAN') |
This message is good advice. Installing the CPAN bundle will upgrade you to the latest version of CPAN.pm. You also get some other modules in the bundle which make using CPAN more fun. At least, that's what the Bundle::CPAN manual page says (man Bundle::CPAN).
Enter the install command at the cpan> shell prompt.
cpan> install Bundle::CPAN Trying with "/usr/bin/lynx -source" to get |
CPAN.pm downloads three files - a mailrc text file ...
ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/authors/01mailrc.txt.gz gzip: /root/.cpan/sources/authors/01mailrc.txt: not in gzip format Going to read /root/.cpan/sources/authors/01mailrc.txt.gz |
... a packages details text file ...
Trying with "/usr/bin/lynx -source" to get ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/modules/02packages.details.txt.gz gzip: /root/.cpan/sources/modules/02packages.details.txt: not in gzip format Going to read /root/.cpan/sources/modules/02packages.details.txt.gz Database was generated on Fri, 07 May 2004 01:33:12 GMT HTTP::Date not available |
and a modlist data file.
Trying with "/usr/bin/lynx -source" to get ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/modules/03modlist.data.gz gzip: /root/.cpan/sources/modules/03modlist.data: not in gzip format Going to read /root/.cpan/sources/modules/03modlist.data.gz |
Ignore messages that urge you to install this module or that bundle. You are, in fact, already running a process which will have exactly the outcome that the messages urge. Here is an example. I will not quote any others.
There's a new CPAN.pm version (v1.76) available! [Current version is v1.59_54] You might want to try install Bundle::CPAN reload cpan without quitting the current session. It should be a seamless upgrade while we are running... |
Here comes the new version of CPAN.pm.
Trying with "/usr/bin/lynx -source" to get ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/authors/id/A/AN/ANDK/CPAN-1.76.tar.gz Scanning cache /root/.cpan/build for sizes CPAN-1.76/ CPAN-1.76/lib/ CPAN-1.76/lib/CPAN.pm CPAN-1.76/lib/CPAN/ CPAN-1.76/lib/CPAN/Admin.pm CPAN-1.76/lib/CPAN/Nox.pm CPAN-1.76/lib/CPAN/FirstTime.pm CPAN-1.76/lib/Bundle/ CPAN-1.76/lib/Bundle/CPAN.pm CPAN-1.76/t/ CPAN-1.76/t/loadme.t CPAN-1.76/t/vcmp.t CPAN-1.76/t/signature.t CPAN-1.76/t/mirroredby.t CPAN-1.76/t/Nox.t CPAN-1.76/PAUSE2003.pub CPAN-1.76/MANIFEST CPAN-1.76/MANIFEST.SKIP CPAN-1.76/scripts/ CPAN-1.76/scripts/cpan CPAN-1.76/META.yml CPAN-1.76/BUNDLE/ CPAN-1.76/BUNDLE/Test/ CPAN-1.76/BUNDLE/Test/Builder.pm CPAN-1.76/BUNDLE/Test/More.pm CPAN-1.76/Todo CPAN-1.76/ChangeLog CPAN-1.76/Changes.old CPAN-1.76/Makefile.PL CPAN-1.76/README CPAN-1.76/SIGNATURE |
The other modules download in similar fashion. From time to time you may be asked if you wish to download a prerequisite module. Always answer 'yes'. Here is an example.
---- Unsatisfied dependencies detected during [K/KW/KWILLIAMS/File-Spec-0.87.tar.gz] ----- Test::More Shall I follow them and prepend them to the queue of modules we are processing right now? [yes] |
Press <ENTER> to say 'yes'.
Here is a list of the remaining modules and bundles.
Bundle-libnet-1.00.tar.gz File-Spec-0.87.tar.gz Digest-MD5-2.33.tar.gz Compress-Zlib-1.33.tar.gz |
There is lots of activity on the screen. You may see messages like this from time to time.
Looks Good. Up/Downgrade complete. Checking if your kit is complete... Looks good |
You may also notice activity concerned with writing makefiles, running make, running make test and running make install.
Eventually you will reach the end.
CPAN: Term::ReadLine::Perl loaded ok ................... 19 subroutines in Term::ReadLine redefined cpan shell -- CPAN exploration and modules installation (v1.59_54) ReadLine support enabled cpan> exit Lockfile removed. # |
If you are using a dialup connection, switch ppp off. If necessary, switch to the second terminal first.
# poff # |
You can check that you now have a newer version of CPAN.pm.
# cpan -v CPAN.pm version 1.76 # |
Exit from user Root.
# exit $ |
Log in as a normal user and su to user Root. Visit the CPAN search page to find the module you want. For instance, if you use the lynx browser, you could do this.
$ su # pon # lynx http://search.cpan.org |
Open a CPAN shell and install the module using the install command. When the download and installation is finished, exit the CPAN shell, switch and exit from user Root.
cpan> exit Lockfile removed. # poff # exit $ |
Copyright ©2004 Chris Lale <feedback.chrislale@coolscience.co.uk>. Permission is granted to copy, distribute and/or modify this document with no Invariant Sections, with no Front-Cover texts and with no Back-Cover Texts under the terms of the GNU Free Documentation License, version 1.1 or any later version, published by the Free Software Foundation. A copy of the license can be found at http://www.fsf.org/copyleft/fdl.html.
You can get the latest version of this document from http://newbiedoc.sourceforge.net.
If you find any errors, omissions etc, please let me know via the newbieDoc Discussion list; send a message to <newbiedoc-discuss@lists.sourceforge.net>. Even better, join as a sourceforge.net member and subscribe to newbieDoc discussion first.
I have written this document in English. I have used American spellings for some technical terms eg 'program' where these have become widely accepted.
You can find guides to English spelling, punctuation and grammar at http://www.cral.ac.uk/guidelines/.
Three dots ...
if before text, indicates text has been omitted in front of the text
if after text, indicates that following text has been omitted.
if on one line by themselves indicates that lines have been omitted.
A '$' at the start of a line indicates that the rest of the line is input from a normal user. A '#' indicates that the Root user inputs the rest of the line.
Filenames, application names, package names and text displayed by a console or terminal window look like this.
my-file.txt my-directory /my-path/my-directory/ my-application my-package This is some terminal text. |
Filenames, application names, package names and text displayed in an X window look like this.
my-file.txt my-application my-package This is some text in an X window. |
Commands issued from a terminal look like this. Use of the <ENTER> key is implied but not shown.
$ my command |
This example shows a command issued in an X application.
Menu bar: File -> Close
|
man more - file perusal filter for crt viewing
man less- Less is a program similar to more (1), but which allows backward movement in the file as well as forward movement.
man cpan - easily interact with CPAN from the command line
man Bundle::CPAN
CPAN - the Comprehensive Perl Archive Network (http://www.cpan.org)
CPAN search - http://search.cpan.org