by Steven J. Owens (unless otherwise attributed)
> perl -MCPAN -e shell
>and the CPAN shell should start up. If it's the first time you've
>used it, it will ask you all sorts of questions about its configuration.
>Most are easily answered; do make sure you have the URL of your nearest
>CPAN mirror to hand.
Good advice from an obviously skilled Perl monger. However, I'd like to caveat this with the fact that while the -MCPAN option is handy and very useful when it works, it doesn't always work. This can be a very frustrating experience.
In fact, I've never gotten -MCPAN to work, despite blithe assurances by various Perl gurus on #perl and elsewhere. On many systems as mentioned above, it isn't installed or isn't configured. Apparently this is because it's sometimes quite difficult to install and chokes on obscure problems. I have, on rare occasions, gotten Perl gurus to admit that -MCPAN is arcane and not always reliable :-). When -MCPAN isn't available, the process of fetching CPAN modules and installing them can be a bit more tedious (and intimidating to novices).
This is particularly so when you consider that the novice probably doesn't have access to install the modules in the site-perl directory and hence has to skull it out a bit to figure out how and where to install them and to tell their script where to find the modules. It's not that it's that hard, but it's poorly documented due to "guru blind spot syndrome". The people who know how to do it don't have to (because they're gurus and usually have full access) and hence don't place a lot of importance on it. These are the same people who write most of the docs, of course... a classic case.
More frustrating, you'll find a lot of dependencies between modules and even between bundles. I've never really worked with the FTP module, but last month I built a script to post data to a search engine (long story). Once I had everything in place, it was quite trivial to write the actual script (well, I had a puzzling couple of hours trying to figure out why it was hanging, till I figured out it was just search engine lag mucking up the works). But getting everything in place was quite frustrating:
Download this module, ungzip, untar, make, whoops, it says I need these other two modules. Go get the two prerequisite modules mentioned in the make and install them. Now go get the five prerequisite modules mentioned in THOSE makes and install THEM. Now go get... etc.
I think I spent about three hours total finding, getting and installing about a dozen modules. None of this was mentioned in the Perl Cookbook section I was using (which all too typically just blithely said "go get this module from CPAN and install it" - an excellent book aside from this typical blind spot).
Perl and CPAN have a mechanism to deal with this, but so far it's ill-supported in the actual modules. I've heard there's a team of volunteers going through the CPAN archive and correcting this, so CPAN will actually be able to tell you right off the bat which other modules you need to get, but it's tedious and time-consuming. It'll be well worth it, though. CPAN is one of Perl's significant advantages in making inroads into the corporate sector. [update: the volunteer effort mentioned has made tremendous headway, and CPAN is much easier to use as a result].
My point in all this is that while CPAN modules can be very useful and make major projects a trivial task, using CPAN is not as trivial as it's made out to be. Well worth the investment of time and energy, but don't be misled by the casual "Oh, just go get the blah module from CPAN."
>When all is set up, you just need to type 'install Net::FTP' and the
>module should be installed.
You'll need about a dozen modules. Unfortunately the system I did this on is a continent away and behind a rather restrictive firewall, so I can't simply list them. Start with net-lib and work your way down. If you have a fast connection, my advice is to just peruse CPAN and snag anything that looks vaguely related. It's always easy to delete it if you don't need it.
To start with, point your browser at cpan.perl.com. Select a mirror site - one of several sites which maintain copies of the CPAN archive and keeps cpan.perl.com from being overloaded. Unfortunately it's not always easy to figure out which mirror you should use. Click on the "Nearest CPAN Site" link on the left side of the cpan.per.com page and it'll try to make an educated guess about where to send you. If it works, great. If it doesn't, try it again. I usually end up giving up and just working from cpan.perl.com.
So, first let's look for "ftp" in the CPAN search engine. Hm, no results for query. Let's try that again with "net::ftp" as the query. Aha, now we get some results. libnet1.060600. Click on that link and you'll download the libnet package.
The page also lists three dependencies, IO::Socket and Socket and Data::Dumper. This is probably that project I mentioned above. Yay! I thought I was going to have to spend half an hour chasing down modules in the hierarchy. Let's see, Socket is for using Sockets from Perl and IO::Socket is a friendlier package that uses Sockets. Data::Dumper is for saving things like hashes as files and then reading them in again; offhand I can't think what libnet uses Data::Dumper for, but let's leave that mystery for later.
Click on IO::Socket and it takes you to the page for the IO package. Click on the link at the top of the page (in the light blue box on my browser, hopefully it'll look vaguely the same on yours) and download that package. Socket is part of Perl 5.005020 and up, so if you have that version or later, you don't have to grab Socket. Grab Data::Dumper. Hm. It appears that this is all you need for Net::FTP, though I don't have a UNIX system handy to install and test it.
You should now have two files one named libnet-1.0606.tar.gz and one named Data-Dumper-2.10.tar.gz. Get them to your UNIX server and ungzip and untar them. If you don't know how to do that, then you are really a novice and you're better off at this point finding somebody who knows more than you and getting them to walk you through it.
Once they're untarred, cd into the directory and read any README files. Most of the time, you just have to type "make" and everything goes smoothly. If there's something more complex required, this is probably not a module you should be installing by yourself (i.e. you or somebody who has a clue needs to go do some homework). Pay attention to any messages it displays. I usually like to do all of this from inside an EMACS shell buffer so I can easily scroll up and down to check the messages. If your favorite telnet client has a nice log paging facility, you can use that.
If "make" gives you some error messages, look at them and see if you can puzzle them out. If you understand them, great, fix it and go on. If you understand them but aren't sure about the answers, this'll be a learning experience for you. If you're boggled, then once again this is probably not a module you should be installing on your own at this point in your education.
If the module makes without any error messages, do "make test", which will run some tests built into the module to make sure everything is in order. If it doesn't pass the tests, see the previous paragraph. If it does, then it's time to actually install it with "make install".
This is where the question of where to install it comes up. If you have full access to the system, there's a standard directory where Perl is installed and under that directory there's a standard directory for modules and such. Just do "make install" and everything'll go there. If you don't have access, you can install the module elsewhere, in a directory you do have access to. Unfortunately this opens up a whole can of worms.
First off, if you're going to install several modules, you should think about picking some spot on the system and putting a directory there for all the modules. This keeps things from getting cluttered and centralizes the modules for easier management.
Second, there's the issue of permissions, particularly if you're planning to use this module from a CGI script. CGI scripts are typically executed as some minimal-access userid, for security purposes. This means that the directory you put the module in and the files in the module need to be accessible to that userid. The details here vary a lot depending on your system, server and particular configuration issues, so there's no easy answer here. Time to talk to somebody who knows a lot more than you and is familiar with your specific situation.
Assuming you resolve the above, check the README in the module directory and it'll tell you the proper arguments to use with "make install" to tell it which directory to put the files in.
Oh, at this point you can blow away the untarred directory, though if you have the space you might want to keep the various blah.tar.gz files around in case you need them later.
>If you don't have access to the command line, you may still be able to
>install by ftping the module from CPAN and uploading it to your cgi
>directory (I may have oversimplified that: read the docs that come
>with the module). You can then use the module by including the lines
> use lib '.';
> use Net::FTP;
This is true, but it also opens up a whole 'nother can of worms, particularly with something as powerful as net-lib and Net::FTP. Anything in your CGI directory can be invoked directly from the outside world. At one point in the web's infancy, various bozos were actually recommending that people put the Perl executable in their CGI directory! Eek!
I wish I had an easy answer, but if their access is so limited, they're better off getting better access, either by talking to their system adminstrator or finding a better service provider.
Caveat Emptor: as mentioned above, most of this is from memory without a server handy to test it out on. Any errors were deliberately inserted as an exercise for the student. :-)