http://qs1969.pair.com?node_id=128077

This is a brief guide to installing modules. For some background on what a module is and where they live on the system see the Simple Module Tutorial

The Basics of Module Installation

Fixing common problems

Tools to make the job easier CPAN and PPM

Installing Modules that include elements coded in C

The Basics of Module Installation

Most modules are available from CPAN - the Comprehensive Perl Archive Network. They are supplied in what is known as a tarball. A tarball is a gzip compressed tar file. When a module is made the directory structure it lives in is converted to a single file that contains both the files and the directory information. A program called tar performs this function and the resultant file is called a tar file. Tar files have a .tar file extension. This tar file is then compressed using the gzip (GNU Zip) program. Gzipped files have a .gz extension thus a standard module will be called something like:

Some-Module-0.01.tar.gz

The first part is the name, the next part the version number and the last part the .tar.gz extension signifying that this is a tarball. You uncompress a tarball using the tar program like this (the $ represents the command prompt):

$ tar -zxvf Some-Module-0.01.tar.gz

All *nix systems will have a tar program. On windows you can use CYGWIN which is a set of UNIX tools ported to Win32 to get tar but programs like WinZip will handle extracting tarballs just fine.

One issue with Winzip is that it does not deal well with .tar.tar as an extension. Fix it by changing the extension to tar.gz.

Once your have extracted your tarball you then need to make and install your files. You do that like this. At the command prompt navigate your way to the directory created where you extracted the tarball.  Making your extractions in a /temp dir is a good idea in case of problems with badly made distributions. There may be several directories to move through. In our hypothetical example above we would expect the tarball to extract into a directory called "Some-Module-0.01", however it may extract to "Some" or even straight into the current working directory (this is not fun to clean up, thus the suggestion of using a /temp dir). Within this module directory we should find a file called "Makefile.PL" although it *may* be several dirs deep. Once you find the Makefile.PL you do the following:

$ perl Makefile.PL
$ make
$ make test
$ make install

This should all proceed smoothly and your module should be installed, if not see below. Note on Win32 you will need to use a program called nmake. You can get a copy from M$ here: nmake via FTP or here nmake via HTTP Once you have downloaded it you need to run the program (it self extracts) and make sure that you do this in a directory that is on your PATH. The PATH is a list of directories that Win32 will search for executable files. When you type nmake you want Windows to be able to find the program so it must be in one of the directories on the PATH. To see your current PATH type PATH at the command prompt. C:\WINDOWS or C:\WINNT will be a fairly safe bet.

Now that you have got nmake and extracted it in a directory on your PATH you just do this:

C:\> perl Makefile.PL
C:\> nmake
C:\> nmake test
C:\> nmake install

Ok either everything went fine or you got some errors. Note in the following read nmake for make if your are on Win32

Fixing common problems

When I perl Makefile.PL or make test I get a Warning: prerequisite Foo::Bar failed to load: Can't locate foo/bar.pm in @INC....

Some modules have dependencies. They depend on other modules to function. These are specified in the Makefile.PL in the line:

'PREREQ_PM' => { Foo::Bar => 1.5 }

This line specifies that the module you are trying to install require a module called Foo:Bar and that the version of this module must be 1.5 or greater. If you get these type of errors you will need to download and install these module(s) first. You should find details in the README file - did you READIT?

Some Authors forget to edit their Makefile.PL with dependencies - in this case you will generally get this error message when you run the tests as the new module tries to load non-existent modules on which it is dependent.

I get an error saying "Can't find make"

As noted before when you say make/nmake the operating system looks along the path for an executable by the right name. If it can't find one you get this error. To fix it simple modify your path or specify the full path to the executable such as:

$ ~/make

This tells the operating system to use the make executable in your home directory where you just put it OK

make/nmake reports missing files

When you run make/nmake it looks for a file called MANIFEST which lists all the files that should be present in the distribution. If some are missing you get an error like:

$ make
Checking if your kit is complete...
Warning: the following files are missing in your kit:
Foo.bar
Please inform the author.
$

This is slack on the authors part for producing a broken distribution. Get a good one!

make test reports errors

While modules should be portable across operating systems some are not. To ensure that a module is working correctly most authors develop a test suite of programs that ensure the module is behaving as expected. When you run:

$ make test

These scripts are all run. Some errors are trivial but some are significant. If you get errors consult the README and look at the results to see what is broken. The author will want to know about these and may be able to help fix them.

If you get a lot of errors it is probably wise not to make install and install the module.

I don't have permission to install a module on the system!

If you don't have root permission you will not be able to install a module in the usual place on a shared user system. If you do not have root access you may get errors like:

$ make install
Warning: You do not have permissions to install into 
/usr/local/lib/perl5/site_perl/5.005/i386-freebsd at 
/usr/libdata/perl/5.00503/ExtUtils/Install.pm line 62.
mkdir /usr/local/lib/perl5/site_perl/5.005/CGI/Simple: 
Permission denied at /usr/libdata/perl/5.00503/ExtUtils/Install.pm line 120
*** Error code 2

 This is easy to get around. You just install it locally in your home directory. Make a directory called say /lib in your home directory like this:

# first navigate to your home directory
$ cd ~
# now make a directory called lib
# on UNIX
$ mkdir lib
# on Win32
C:\> md lib

Now you have a directory called ~/lib where the ~ represents the path to your home dir. ~ literally means your home dir but you knew that already. All you need to do is add a modifier to your perl Makefile.PL command

$ perl Makefile.PL PREFIX=~/lib LIB=~/lib

This tell MakeMaker to install the files in the lib directory in your home directory. You then just make/nmake as before. To use the module you just need to add ~/lib to @INC. See Simple Module Tutorial for full details of how. In a nutshell the top of your scripts will look like this: 

#!/usr/bin/perl -w
use strict;
# add your ~/lib dir to @INC
use lib '/usr/home/your_home_dir/lib/';
# proceed as usual
use Some::Module;

Tools to make the job easier CPAN and PPM

There are some tools to make installing modules even easier. They may be difficult to get working through firewalls or proxies. Read the docs for configuration hints.

CPAN.pm

CPAN.pm is a perl module that installs perl modules! It is part of the standard distribution so you should have a copy available. The easiest way to use it is like this (note the use of different quotes on different OSs):

# Win32
C:\> perl -MCPAN -e "shell"
# UNIX
$ perl -MCPAN -e 'shell'

This fires up the interactive shell. Follow the prompts and accept the defaults.

PPM

PPM is the Perl Package Manager from ActiveState. See A guide to installing modules for Win32 for full details. It installs special versions of CPAN modules wrapped in an XML format called a PPD file. To file up the shell:

C:\>PPM
PPM>

Type help at the prompt for commands and see the docs. If you can't get PPM to work through your proxy/firewall then download the .zip files of the PPD files from here, unzip them, navigate to the directory you unzipped them into and then run:

C:\>PPM install Some-Module.ppd

Installing Modules that include elements coded in C

The most difficult modules to install are generally those that include parts of the module written in C. These modules require that you have a *good* C compiler on your system - generally gcc is best. On most UNIX systems you will have a C compiler but on Win32 you will probably not have as it is not a part of Windows. If you do not have a C compiler you will need to install one. Get a copy of gcc direct from the source here:

http://www.gnu.org/software/gcc/gcc.html

Getting modules compiling on Win32 can be tricky. See A Practical Guide to Compiling C based Modules under ActiveState using Microsoft C++. Just getting cygwin/MinGW and gcc is not enough. The easiset solution is to try to find a precompiled binary version (try ActiveState for a PPM or the Author) or email the Author the tale of your woes. If you are using Win32 expect the author to suggest you get a real OS but.....

cheers

tachyon

Corrected a few technical inexactitudes (similar to issues ;-) thanks to Hanamaki

Replies are listed 'Best First'.
Re: A Guide to Installing Modules
by Hanamaki (Chaplain) on Nov 28, 2001 at 23:46 UTC
    ++ for tachyon's nice introduction to module installation. Since I have already done about 600-700 tests for the CPAN-testers I would like to supply some comments (footnotes) from my experience.

    Some Footnotes

    1. In our days, fortunately most authors use h2xs and make dist. Therefore, these tarballs expand to Some-Module-0.01, and if you cd into the directory you don't have to search for the place to do your perl Makefile.PL.
    Tarball distributions which expand just to Some are really a pain, especially if you download a few modules from the Some:: Namespace.
    Unfortunately there are also some tarball distributions which don't get expanded in their own directories, but in the current directory -- Have fun with the cleanup afterwards.

    2. Unfortunately, many CPAN authors are still not used to -- or don't know about -- setting PREREQ_PM in Makefile.PL. So be prepared to get the "Can't locate foo/bar.pm in @INC" error while running make test.

    3. While you should find important information in the Readme File, don't be surprised if you just find a Readme template, where the author never cared to replace "blabla".

    4. If make test just does one test (1..1) it is in most cases just a load test. This means, your module will get loaded without problems, but it does not tell you wether the supplied functions work as expected. While make test is a important step for confidence building you should test the Module with your own scripts, and report errors to the author if appropriate. Be prepared, that many tests supplied by the author do not test all functions.

    Hanamaki

    Edited by footpad, ~Wed Nov 28 20:04:16 2001 (GMT)

[reply]
[d/l]
[select]
      How do you uninstall a module ?
[reply]
        If the module was installed in a normal fashion (perl Makefile.PL ...), it should've left a .packlist file.

        Then you just use ExtUtils::Installed (you could use File::Find, but why go through the trouble when somebody already done it) 

        use ExtUtils::Installed;
my $inst = ExtUtils::Installed->new();
print "$_\n" for $inst->files('CGI');

=head1 on my machine, I get

    C:\Perl\lib\CGI\Util.pm
    C:\Perl\lib\CGI\Cookie.pm
    C:\Perl\lib\CGI.pm
    C:\Perl\lib\CGI\Push.pm
    C:\Perl\lib\CGI\Pretty.pm
    C:\Perl\lib\CGI\Fast.pm
    C:\Perl\lib\CGI\Carp.pm
    C:\Perl\lib\CGI\Switch.pm
    C:\Perl\lib\CGI\Apache.pm

=cut

# and now for the "deletion" part
print "unlinking ", unlink( $inst->files('CGI') );

        [download]
        update:

        Hmm, works just fine for me on various perls/systems, what exactly did you try, and what version of ExtUtils::Packlist/ExtUtils::Installed do you have?

        How did you install Image::Magick?

        I have used CPAN to install modules and tested this, and it all works out as expected. I suspect one of the ExtUtils modules you're using is messed up. Seeing how you're still getting a file list, a workaround is easy (use File::Find to locate those files in @INC and acquire absolute paths).

        ____________________________________________________
        ** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]
[d/l]
        Why would you need to?

        I don't believe there are any mechanisms available to completely uninstall a module (assuming it wasn't installed with a package management system like RPM). If you just want to make a module unavailable to scripts, just find and delete the Module.pm file.

[reply]
I don't have PPM, how can I install a package?
by PodMaster (Abbot) on May 25, 2003 at 11:06 UTC
    Acquire PPM, or (if you insist), follow these instructions.

    First, make sure you're downloading the right package (one intended for your version of perl), and then simply download it (ex: WWW-Curl.tar.gz).
    Then, uncompress it so now you have a blib directory in your current working directory, and then execute 

         perl -MExtUtils::Install -e install_default WWW/Curl
    and voila. It's what PPM basically does.

    BE AWARE that the .ppd file may contain instructions to download extra files needed for install, which are not packaged with the tarball (like libcurl.dll, libeay32.dll, ssleay32.dll). You'll have to examine the .ppd file to make sure.

    If you look at WWW-Curl.ppd you'll see a reference to install_libcurl.

    PPM would download this file and attempt to execute it.
    install_libcurl would check for the existence of specified files in your path, and prompt you whether to install them if they're not found.

    If you want autogenerated html docs (my packages generally don't include these), simply execute 

        perl -MActivePerl::DocTools -e ActivePerl::DocTools::WriteTOC()
    or (the one I prefer) 
        perl -MPod::Master -e Update
    You can acquire Pod::Master from perlmonks.org here.

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

[reply]
Re: A Guide to Installing Modules
by Anonymous Monk on Oct 17, 2003 at 16:00 UTC
    I have been assigned to install a whole load of CPAN modules on the machines I admin for. The machines are a collection of differing RedHat boxes used by techies who like to change configurations and versions (so we have a lot of different RedHat and Perl versions). I tried CPAN but it requires an initial setup for each machine and I just want to install a directory full of perl-module.tar.gz's; I tried a script that essentially did uncompress, perl Makefile.PL; make; make test; make install but some packages throw up prompts on the Makefile.PL step and I don't know of a way to just indicate the defaults to each package. Any help would be appreciated.
[reply]

      Module::ScanDeps. Then build a test system that conforms to the minimal spec. Then make a build order. Then test.

      cheers

      tachyon

      s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print

[reply]
        I am a retired web host provider ,we used to provide free webhosting for reurned servicemen in US UK and here in Australia. Until I retired they deleted them all.After my complaining theyve given me a shared server but Im not allowed to use admin privelidges. Obviously I jumped at ir. It seems I was a bit too keen because I have no access to mysql or php. I'm not sure what is the best way around this. I need to provide accounts but don't need accounting(creditcard etc) Simply need to have a way to supply free webhosting . I have been recomended phpmywebhosting but can't seem to get it started. The site is freehostultra.com You can see where I've started and got stuck at www.freehostultra.com/install/ I know it's probablt an easy fix but does anyone have a way to install all php,sql,in one go remotely via ftp? Regards Hey It's for a good cause) Regards Allan Optus australia
[reply]
Re: A Guide to Installing Modules
by wfsp (Abbot) on Jul 30, 2004 at 07:22 UTC
    Hi,
    I have activestate on winXP.
    I have installed/updated modules using ppm without a hitch.
    I want to try Win32::Rase but have not been able to find it with ppm so I (nervously) tried the cpan.pm method you describe.
    The 'install' command doesn't find it but the 'i' command seems to know about it.
    Any advice please? Thanks in advance. 
    C:\Perl>perl -MCPAN -e "shell"
Terminal does not support AddHistory.

cpan shell -- CPAN exploration and modules installation (v1.7601)
ReadLine support available (try 'install Bundle::CPAN')

cpan> install Win32::Rase
CPAN: Storable loaded ok
Going to read \.cpan\Metadata
  Database was generated on Thu, 29 Jul 2004 06:14:41 GMT
Warning: Cannot install Win32::Rase, don't know what it is.
Try the command

    i /Win32::Rase/

to find objects with matching identifiers.

cpan> i /Win32::Rase/
Module id = Win32::RASE
    DESCRIPTION  Dialup entries and connections on Win32
    CPAN_USERID  MBLAZ (Mike Blazer <blazer@peterlink.ru>)
    CPAN_VERSION 1.01
    CPAN_FILE    M/MB/MBLAZ/Win32-RASE-1.01.tar.gz
    DSLI_STATUS  Rdpf (released,developer,perl,functions)
    INST_FILE    (not installed)


cpan>

    [download]
[reply]
[d/l]

      Without being too rude the whole idea of this tutorial was to teach you how to install a Module by hand. PPM and CPAN are convenience tools. Like all tools they have issues. You have just found one.

      Go to search.cpan.org. Type in Win32::RASE, search, download the module, extract it (winzip will do). While you are there type in 'enum' - this is another module (enum.pm), so do likewise - download and extract it as well.

      Now get a command prompt. Navigate to dir where you extracted the modules to (I extract into c:\temp) so cd c:\temp\[module name] will do it. Follow instructions above ie perl Makefile && nmake && nmake test && nmake install

      If you try to do RASE first you will note it says it needs enum.pm (that's why you got it) so do that first and RASE second. It is very easy and should take no more that a couple of minutes.

      If you want the docs (from the pod) to appear in the ActiveState docs do one of these after you have installed the modules. 

      # probably this
perl -MActivePerl::DocTools -e ActivePerl::DocTools::UpdateHTML()

# if not this should do it.
perl -MActivePerl::DocTools -e ActivePerl::DocTools::WriteTOC()

      [download]

      cheers

      tachyon

[reply]
[d/l]
[select]
        Sorry for missing the point of your tutorial and thanks for your patience and reply.

        Enum appeared to install ok as follows: 

        C:\enum\enum-1.016>perl makefile.pl
Checking if your kit is complete...
Looks good
Writing Makefile for enum

C:\enum\enum-1.016>nmake
WARNING:  missing nmake.err; displaying error numbers without messages
+.

cp enum.pm blib\lib\enum.pm

C:\enum\enum-1.016>nmake test
WARNING:  missing nmake.err; displaying error numbers without messages
+.
C:\Perl\bin\perl.exe "-MExtUtils::Command::MM" "-e" "test_harness(0, '
+bl
ib\lib', 'blib\arch')" t\dot_dot.t t\new_index.t t\new_package.t t\new
+_tag.t t\s
imple_tags.t
t\dot_dot........ok
t\new_index......ok
t\new_package....ok
t\new_tag........ok
t\simple_tags....ok
All tests successful.
Files=5, Tests=14,  0 wallclock secs ( 0.00 cusr +  0.00 csys =  0.00 
+CPU)

        [download]
        It installed itself here: 
        Directory of C:\perl\site\lib\win32\ole

01/06/2004  12:15             2,839 Enum.pm
               1 File(s)          2,839 bytes
               0 Dir(s)   8,706,207,744 bytes free

        [download]
        But installing Win32::Rase produced: 
        C:\win32-RASE\Win32-RASE-1.01>perl makefile.pl
Checking if your kit is complete...
Looks good
Warning: prerequisite Win32::API 0 not found.
Warning: prerequisite enum 1.014 not found.
Writing Makefile for Win32::RASE

        [download]
        Is the difference between enum 1.014 and enum 1.016 significant?

        I noticed that Win32::API was also not found.

        I have Win32API::File, Win32API::Net and Win32API::Registry. I downloaded Win32::API from CPAN. 

        C:\Win32-API-0.41>perl makefile.pl
Checking if your kit is complete...
Looks good
Writing Makefile for Win32::API::Callback
Writing Makefile for Win32::API

C:\Win32-API-0.41>nmake

Microsoft (R) Program Maintenance Utility   Version 1.50
Copyright (c) Microsoft Corp 1988-94. All rights reserved.

cp Type.pm blib\lib\Win32/API/Type.pm
cp Callback.pm blib\lib\Win32/API/Callback.pm
cp Struct.pm blib\lib\Win32/API/Struct.pm
cp API.pm blib\lib\Win32/API.pm
        C:\Perl\bin\perl.exe C:\Perl\lib\ExtUtils/xsubpp  -typemap C:\
+Perl\lib\E
xtUtils\typemap  Callback.xs > Callback.xsc && C:\Perl\bin\perl.exe -M
+ExtUtils::
Command -e mv Callback.xsc Callback.c
        cl -c    -nologo -Gf -W3 -MD -Zi -DNDEBUG -O1 -DWIN32 -D_CONSO
+LE -DNO_ST
RICT -DHAVE_DES_FCRYPT -DNO_HASH_SEED -DPERL_IMPLICIT_CONTEXT -DPERL_I
+MPLICIT_SY
S -DUSE_PERLIO -DPERL_MSVCRT_READFIX -MD -Zi -DNDEBUG -O1    -DVERSION
+=\"0.41\"
 -DXS_VERSION=\"0.41\"  "-IC:\Perl\lib\CORE"   Callback.c
'cl' is not recognized as an internal or external command,
operable program or batch file.
NMAKE : fatal error U1077: 'C:\WINDOWS\system32\cmd.exe' : return code
+ '0x1'
Stop.
NMAKE : fatal error U1077: 'C:\WINDOWS\system32\cmd.exe' : return code
+ '0x2'
Stop.

        [download]

        Does this mean I need a C compiler?

        Sorry to be a pain.

        Note: I found and moved nmake.err into the path.

[reply]
[d/l]
[select]
Re: A Guide to Installing Modules
by mosince82 (Initiate) on Feb 02, 2010 at 01:01 UTC

    Thanks Tachyon! have been looking for this info for a day, exactly what i needed.
    So i've gone ahead and installed my first module. I received an error:

    ERROR: Can't create '/usr/local/share/man/man3' mkdir /usr/local: Permission denied at /System/Library/Perl/5.10.0/ExtUtils/Install.pm line 479

    I resolved by installing locally in my home directory as you suggested.
    My question now is what to do with the installed module? I need to install 5 or so modules to setup Amazon Cloudfront and don't know how to manage them once installed.

    - Should I leave the 'lib' folder as is?
    - can/should i install the other modules to the same folder or should they be placed somewhere else on my machine?
    thanks in advance and again for this article!
    mo

[reply]
Re: A Guide to Installing Modules
by shagbark (Acolyte) on Mar 01, 2015 at 16:48 UTC

    After 'make install', can I 'rm *' to remove the tarball and all its extracted files?

[reply]
      After 'make install', can I 'rm *' to remove the tarball and all its extracted files?

      Yes. After make install has completed successfully it's safe to delete the installation files. If you'd like to be sure the module installed successfully, run a script that uses it, or just something like perl -MModule::Name -le 'print $Module::Name::VERSION'. (The only exception might be if you've done some customization in the source directory that you want to keep around.)

[reply]
[d/l]
[select]
Re: A Guide to Installing Modules
by Anonymous Monk on Dec 11, 2011 at 22:58 UTC

    nmake not working for you? you probably need to use dmake, or make, it all depends on what perl -V:make prints

    You can override choice ($Config::Config{make}) of makefile ExtUtils::MakeMaker generates by using 

    perl Makefile.PL make=dmake
perl Makefile.PL make=nmake

    [download]
[reply]
[d/l]
[select]
A reply falls below the community's threshold of quality. You may see it by logging in.

Back to Tutorials