Installing modules

Author: John M. Gabriele | back to index

  • Installing modules

    • ---

    Managing extra modules

    For your own non-system Perl installation, you should almost always install extra modules using the CPANPLUS module. However, in a pinch, you can also download/unpack/build/install them by hand, if necessary. If doing it by hand, you'll have to manually find and install dependencies as well. Installing by hand can sometimes be useful if a module is failing tests (or otherwise having issues) and you want to personally tend to its installation. But normally, you should be using CPANPLUS.

    Installing by hand

    You can download and unpack the module source to any directory you like, and then delete it when you're done with the following steps.

    To build and install modern modules that use Module::Build, do: 

    perl Build.PL
./Build
./Build test
./Build install

    To build and install modules which use ExtUtils::MakeMaker: 

    perl Makefile.PL
make
make test
make install

    The version of perl that the shell finds is used to figure out where the module gets installed. If you've got your own ~/opt/perl/bin/perl first in your PATH, then your modules will get installed into directories under ~/opt/perl.

    Modules installed that way end up in the site_perl directories, with other pieces scattered elsewhere (for example, in the bin or man directories).

    To see a listing of site modules installed, have a look at: 

    perldoc perllocal

    If tests fail

    If one or more tests fail during the ./Build test or make test steps, I'm not yet sure of an easy way to skip individual tests. If you deem the failing test (or tests) not significant, you can of course just skip the ./Build test or make test step at your own risk.

    Using CPANPLUS

    Often, modules have prerequisites (which may also themselves have prerequisites) and it's much easier to just use the CPANPLUS module to install what you need. CPANPLUS runs those build commands (shown above) for you, pulling in prereq's as-needed (by default it asks you for confirmation before installing anything you haven't explicitly asked for).

    Note: CPANPLUS replaces the CPAN module.

    Old notes on CPAN: The first time you run the CPAN shell (perl -MCPAN -e shell), it'll ask you a bunch of configuration questions. If you botch up answering them, just Ctrl-C to get out, run the command again, and at the CPAN prompt, enter o conf init.

    At the CPAN prompt, hit h for help.

    By the way, you can switch back and forth between using CPAN and CPANPLUS if you like.

    Installing CPANPLUS

    If you're running 5.10 or later, you've already got CPANPLUS installed, and can just start it up for the first time and run through the configuration script.

    If you're running 5.8, download and unpack the CPANPLUS distribution. It comes with a utility to get all its prereq's installed. See the README for details. It's just two commands, and then you do the usual incantation to install CPANPLUS itself.

    Initial CPANPLUS configuration

    There's no long configuration step for CPANPLUS like there was for the CPAN module. Just install CPANPLUS and then use it (most often via the cpanp command).

    Managing your own module directory

    You may not want to install modules into your ~/opt/perl directory. Maybe they're experimental, and you'd rather put them into some transient location. Maybe they're just your own personal modules you have kicking around. Or could be you're on a system where (A) you don't have root access, (B) you haven't installed your own Perl, and (C) you've got modules you want to install.

    For this purpose, many folks keep a ~/perllib directory. If you're just dealing with your own simple .pm files, life is simple and you can just dump them right into ~/perllib. If you want to install modules that have been packaged up into a real distribution, there's a little more to it. What happens is, Perl likes to install its files in an orderly fashion, spread out into appropriate subdirectories under one main directory. It doesn't really like to just dump the build products all jumbled together into that one main directory.

    I believe the customary way to deal with this issue is to just let the simple modules (the .pm files you chuck in there) peacefully coexist with the packaged modules (the ones that want a main parent directory with subdirectories to install into).

    Installing packaged modules into ~/perllib

    If the distribution you want to install uses Module::Build: 

    # Organize everything neatly in subdirs under ~/perllib.
perl Build.PL --install_base ~/perllib
./Build
./Build test
./Build install

    If the distribution uses ExtUtils::MakeMaker: 

    perl Makefile.PL PREFIX=~/perllib LIB=~/perllib
make
make test
make install

    Then use the module from your own scripts by putting in either 

    use lib '/home/me/perllib/site_perl';

    or 

    use lib '/home/me/perllib';      # or
use lib '/home/me/perllib/lib';

    Helping your scripts find these local modules

    For your code to make use of modules in ~/perllib, what's usually done is to add the following line to the top of files which use those modules: 

    use lib '/path/to/perllib';

    If you'd rather not add that to your code (maybe you expect your users to have such modules installed in one of the @INC directories) the other options are to either set the PERL5LIB environment variable, or else to call your script with the -I~/perllib option.