| Previous | Table of Contents | Next |
8.2 Using CPANYou can of course download tarballs (compressed archives of file trees created with the tar program) of modules from CPAN and build them manually. I'll show you how to do that shortly. But first, I'll show you the easy way. 8.2.1 Using CPAN.pmPerl makes it phenomenally easy to install most modules by providing a handy layer of automation for talking to CPAN right in the core. That layer is implemented by—you guessed it—a module, amazingly enough called CPAN.pm.[5]
Installing a new module with CPAN.pm is extremely easy, especially if you are the system administrator or otherwise have write access to the directories in perl's @INC where it wants to install new modules. To install a module called, say, Mac::iTunes, just type:
% perl -MCPAN -e 'install Mac::iTunes'
What launches CPAN.pm into the realm of superstardom is that it can detect and install dependencies; when the module you are installing requires other modules to work (and Mac::iTunes requires a bunch), but you don't already have them. Provided the module author properly listed those prerequisite modules (and the Mac::iTunes author did), then CPAN.pm will install those modules; and if any of them have unrequited prerequisites, CPAN will install them, and so forth. If a module in this dependency chain did not specify its prerequisites properly, you can usually get around it by reissuing the original install command after the first attempt fails. If you want to use CPAN.pm to install modules to a private directory (perhaps because you don't have administrator privileges to install to the site_perl targets in the @INC compiled into perl), you have to work a little harder. CPAN.pm uses a configuration file that contains settings for, among other things, where to build downloads and where to install completed modules. You need to make a version just for you that has special settings. This file needs to be called MyConfig.pm and live in a directory .cpan/CPAN under your home directory. You can let CPAN.pm build this file for you by typing this command:
% perl -MCPAN -e shell
and answering the questions. However, if the superuser has already done so, you may get a message about permission being denied to access their .cpan directory. In that case, first copy the CPAN::Config module that is part of the installed perl so you can edit it: % mkdir ~/.cpan % mkdir ~/.cpan/CPAN % cp `perl -MCPAN::Config -e 'print $INC{"CPAN/Config.pm"}'` \ ~/.cpan/CPAN/MyConfig.pm Then edit ~/.cpan/CPAN/MyConfig.pm to change the paths of the build_dir, cpan_home, and keep_source_where parameters to point to directories you have write permission for. Now you can now run CPAN.pm in interactive mode:
% perl -MCPAN -e shell
cpan shell -- CPAN exploration and modules installation (v1.76)
ReadLine support available
Now, give a configuration command to the CPAN shell:
cpan> o conf makepl_arg PREFIX=/home/peter/myperl
In this case, /home/peter/myperl is the private directory where you want to install new modules. (Don't try using ~ in this path.) Finally, commit the configuration change (cause the change to makepl_arg to become permanent) and exit the CPAN shell: cpan> o conf commit commit: wrote /home/peter/.cpan/CPAN/MyConfig.pm cpan> q Lockfile removed. You can now build a module using CPAN.pm and the install command will put the installed module under /home/peter/myperl. You will need to add the directory /home/peter/myperl/lib/perl5/site_perl to perl's @INC to find the modules that are installed there.[6] Therefore a Perl program that wants to use these modules should start out:
use lib qw(/home/peter/myperl/lib/perl5/site_perl); because that directory is not in the default @INC. 8.2.2 Manual Module InstallationOn rare occasions CPAN.pm won't work for some reason. You may have an idiosyncratic environment, or the module may require some configuration. Modules that require your input to configure are supposed to engage you in an interactive dialog when you issue the CPAN.pm install command. The module author programs this dialog in a file called Makefile.PL (see Section 3.3). If the CPAN.pm install command doesn't work for a particular module, then you can build it by hand and invoke Makefile.PL yourself. First download the module; the look command in the CPAN.pm shell is ideal for that: % perl -MCPAN -e shell cpan> look Foo::Bar [output deleted] Working directory is /home/peter/.cpan/build/Foo-Bar-0.44 % It might look from that last prompt as though the perl command has returned, but in fact it's still running, and has downloaded and unwrapped the latest version of the Foo::Bar module and launched a shell in the build directory for you to play with the module. The manual equivalent of the look command is to download the module's tarball from CPAN (that Download link on search.cpan.org), then: % gunzip Foo-Bar-0.44.tar.gz % tar xf Foo-Bar-0.44.tar % rm Foo-Bar-0.44.tar % cd Foo-Bar-0.44 The first two steps can be combined if your tar program accepts the -z option. Now look for a README file and peruse it. Normally, the steps to build the module are: % perl Makefile.PL % make install make install will expand in this case to make; make test; make install, with each step being executed only if the previous one succeeds. Since you're presumably building this module by hand because the CPAN.pm install command isn't good enough, rather than some masochistic desire to make life difficult, you'll need to intervene at this stage. Most likely you'll be editing Makefile.PL before the first command. It's hard to imagine legitimate circumstances for editing the Makefile before running make given that you can set just about every parameter in that Makefile that matters through arguments to the first command. To find out more about those arguments, read the documentation for the ExtUtils::MakeMaker module. (That's what Makefile.PL uses to create a Makefile.) If you began this build process with the CPAN.pm look command, remember that you're in a subshell and you need to exit it: % exit cpan> q % I sometimes forget this and only find out that I'm still in the CPAN.pm shell when I log out at the end of the day. 8.2.3 PPMOn a Windows platform CPAN.pm will not be useful due to the absence of the make program. You can either get a version for Windows such as nmake[7] or dmake, get one in a UNIX emulation environment such as Cygwin,[8] or you can take the easier step of using the ppm (Perl Package Manager) program included in ActiveState's Windows Perl distribution.[9] PPM only knows about modules that have been ported to the PPM repository, so it will always lag behind CPAN; but on the other hand, all the compilation has already been done for you, so installation of modules with binary components can be much easier than on a UNIX machine. An extreme example of this is PerlTk, which on UNIX requires that you first acquire and build the underlying Tk and Tcl libraries, whereas on Windows everything will be installed for you with the single PPM install command.
8.2.4 Module DistributionWhen you want to package your own module for distribution, the obvious choice today is called ExtUtils::MakeMaker. That's a core module that's invoked by h2xs to create the Makefile.PL when you first create a new module. If, however, you want to do more than what the default Makefile.PL does, you need to edit it and insert directives drawn from the ExtUtils::MakeMaker documentation. Some people have pointed out lately that this interface is not as easy to use as they would like, and they have started developing alternatives:
Expect that in the next few years these modules will get greater attention and more widespread use. |
| Previous | Table of Contents | Next |