How to Install CPAN Modules

Introduction

CPAN (Comprehensive Perl Archive Network) is a large repository of Perl modules. Standard Perl already has many CPAN libraries pre-installed.

As of Foswiki 2.0, Foswiki no longer ships with any CPAN modules. It is recommended that you use your system package manager, or if necessary, App::cpanminus to install any missing dependencies. This guide tells you how to do that.

For building the CPAN modules from sources it is assumed that you have a fully working Perl and C development environment (including a C compiler and make tool) - but you may have much easier alternatives. This is not required if you can install the libraries as packages (rpm, deb, etc.)

What Do I Need?

If you have not yet installed Foswiki: Review the SystemRequirements that is shipped with your version of Foswiki. It lists the required modules.

If Foswiki is installed and operational:

• For Foswiki 1.1.9 or older, run bin/configure and review the contents of the Web Server Environment tab. there is a subsection "Perl modules" which lists the version of the installed modules and also the missing modules. (On oldest 1.0.x versions of Foswiki, the "CGI Setup" tab in configure lists dependencies).
• For Foswiki 2.0, visit PerlDependencyReport, or run tools/dependencies from the command line. This will report any missing dependencies.

Which CPAN Libraries Do I Have?

To test if you have a specific CPAN modules installed, follow this easy method:

This is best explained by example:

• To check for perl module FileHandle: perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
• To check perl module Time::Local: perl -e 'use Time::Local; print $Time::Local::VERSION."\n"'

If you think a perl module is installed, but the system claims it can't find it, then it's worth reviewing HowFoswikiFindsPerlLibraries to help understand what is going on.

Install CPAN Modules using the package management system

If your system is one of the more popular Linux distributions then by far the easiest way to install additional CPAN modules is to use the package management system.

For distributions like RedHat, CentOS, Fedora, Mandriva, etc. most CPAN libraries are available as RPM packages. If you need a CPAN library called CPAN:CGI::Session then the naming convention normally used is perl-CGI-Session. (add perl- prefix, and replace :: with -). Not all the CPAN libraries can be found on your CD/DVD or in the official distribution package repositories. But there are many additional repositories that carry nearly all the CPAN libraries. You may need to first install epel-release EPEL is Extra Packages for Enterprise Linux

For Debian based distributions, including Ubuntu, the naming convention is a little different. For example, the CGI::Session library is called libcgi-session-perl. (Change to lowercase, add lib prefix, replace :: with - and add -perl suffix). The good thing with Debian is that they carry most of the CPAN libraries on the official package repositories so once you know what they are called they are just a simple apt-get away, e.g. apt-get libcgi-session-perl installs the CGI::Session module from CPAN. You can also use GUI tools such as Synaptic to find and install such modules.

On Ubuntu you might find that by default CGI v3.37, 3.43 or 3.47 are installed. These versions, according to Foswiki documentation, must be avoided. One possible solution is to install libcgi-pm-perl, which currently replaces the default version by a supported one (2011-0-10). To do so, type sudo apt-get install libcgi-pm-perl from the command line or install it with your favorite package manager.

Gentoo has ebuilds for the CPAN. E.g. CGI::Session is called CGI-Session. See http://packages.gentoo.org/packages/?category=dev-perl for an overview of Perl CPAN related ebuilds.

Install CPAN modules into your local Perl library using App::cpanminus

CPAN has evolved and the easiest way now to install CPAN modules is using the CPAN:App::cpanminus installer. It can be run with or without root privileges. (Generally running as root is not recommended.) When run as root it installs into the system libraries. When run without root privileges, it installs into a local perl library. For example, run here with root access, cpanm is installed into the System perl libraries, and then Archive::Zip is installed.

curl -L https://cpanmin.us | perl - App::cpanminus
cpanm Archive::Zip

Check your system documentation. You may be able to install App::cpanminus using system tools.

• Ubuntu/Debian: apt-get install cpanminus
• RedHat /Centos: yum install perl-App-cpanminus (Requires EPEL also be installed yum install epel-release)

Setting up a private CPAN library

If you want to install required CPAN modules locally, this is how you do it. The instructions are written for Unix/Linux users, such as shared web hosting users, or users of an intranet Unix/Linux server. Previous versions of this topic documented the old way to do this using CPAN.

• Install CPAN:App::cpanminus documented above.
• If you can change your Foswiki installation directories:
  • Change to your Foswiki lib directory, typically /var/www/foswiki/lib
• If you can NOT change your foswiki installation directly, create a CPAN directory in your local home directory.
• Issue cpanm -l CPAN Package::To::Install (-l is lowercase letter L )

This will create the CPAN directory and install the requested packages in that location.

~ $ cpanm -l CPAN Crypt::Eksblowfish::Bcrypt
--> Working on Crypt::Eksblowfish::Bcrypt
Fetching http://www.cpan.org/authors/id/Z/ZE/ZEFRAM/Crypt-Eksblowfish-0.009.tar.gz ... OK
Configuring Crypt-Eksblowfish-0.009 ... OK
==> Found dependencies: Class::Mix
--> Working on Class::Mix
...
3 distributions installed
~ $ ls CPAN
lib  man

Using your private CPAN repository in Foswiki

CPAN modules installed directly into Foswiki's foswiki/lib/CPAN (technically speaking, foswiki/lib/CPAN/lib ) directory are automatically detected and used by Foswiki. The Foswiki:Extensions.CpanContrib places modules directly into foswiki/lib/CPAN/lib. Unfortunately cpanminus builds into a different library structure, and bin/LocalLib.cfg must be edited.

Update @localPerlLibPath in bin/LocalLib.cfg in your Foswiki installation. The actual installation directories will vary based upon your system architecture. Two libraries are required; one for the platform independent modules, and one for architecture specific modules. For example, the above install created:

/var/www/foswiki/lib/CPAN
  ├── lib
  │   └── perl5
  │       ├── Class
  │       │   └── Mix.pm
  │       └── x86_64-linux
  │           ├── auto

• CPAN/lib/perl5 contains the pure perl modules
• CPAN/lib/perl5/x8_64-linux contains the architecture specific modules.

However you should also add the lib directory, so that any modules installed by the Foswiki:Extensions.CpanContrib override any system modules. The specific bin/LocalLib.cfg setting for this installation is:

@localPerlLibPath = (
          '/var/www/foswiki/lib/CPAN/lib',
          '/var/www/foswiki/lib/CPAN/lib/perl5', 
          '/var/www/foswiki/lib/CPAN/lib/perl5/x86_64-linux'
    );

Installing CPAN modules manually

If you are behind a hefty firewall and cannot run CPAN and your Unix machine does not have ready made packages available the method is to manually install the package. Some packages contains binary compiled modules and requires a fully working Perl and C development environment (including a C compiler and make tool).

If you have a machine using the same architecture as your server that can access the Internet, install cpanminus on that system, install the required modules into a local CPAN directory, and copy the installed CPAN library to the Foswiki server.

If you do not have access to a machine with the same architecture. you can use tools like CPAN:CPAN::mini to create your own local mirror of CPAN.

• Install CPAN:CPAN::Mini cpanm CPAN::Mini
• Mirror all of CPAN to a local directory: minicpan -l mycpan (This is very large - 1 Gig or larger, and takes a long time to download!)
• move the complete mycpan structure over the the Foswiki server.
• Install modules on the Foswiki system using cpanm, with the -M option, specifying the path to the mirror: cpanm -M /path/to/mycpan Module::To::Install

ActiveState Perl

ActiveState has provided compiled modules that make CPAN installation very easy:

1. Browse to the ActivePerl PPM archives
2. Select your ActivePerl version (8xx means perl 5.8)
3. Select your operating system. This procedure has been successfully used to extend the set of CPAN modules provided with the Windows Installer for TWiki 4.2.0. However ActiveState also provides downloads for Darwin, HP-UX, Linux, and Solaris.
4. Download the module(s) you need. File are named xxx-xxx, not xxx::xxx.

The rest of these steps only apply to Windows downloads from ActiveState:

1. Extract the ZIP(s) to a directory on the server, e.g., . Warnings about overwriting README files during extraction can be safely ignored. The installer expects the ZIP to be extracted directly in that directory, and not in sub-directories for each module. So the directory will contain *.ppd files and a directory called which contains *.gz files.
2. Start the GUI for the Perl Package Manager that was installed with ActivePerl: i.e., Start > Run... > ppm
3. In the program Preferences, check that Areas points to your Perl install. "Add Repository" for the directory with the extracted modules.
4. The modules should now appear in the list. Right-click + Install to mark them to be installed. Click as many as needed, and it will check the pre-requisites as it goes.
5. Under the File menu, select "Run Marked Actions". Check for errors, and that's it: no need to restart Apache or re-Configure plug-ins.

Unfortunately a PPM package isn't always available (and I couldn't get nmake to work). In those cases:

1. Open the URL http://trouchelle.com/ppm/
2. Download the PPD (IE downloads it as XML, just rename it)
3. Also download the ZIP from the location specified in the PPD file
4. Extract the ZIP and edit install-nomake to change the shebang from #!/bin/sh to #!D:/perl/bin/perl (or wherever you perl is)
5. At a command prompt (the -s flag, described in the comments of install-nomake, installs it to a remote directory of your choosing):
   cd D:\download_location
perl install-nomake -s D:\Perl\site

External Links

• badlink-->http://sial.org/howto/perl/life-with-cpan/ - good introduction to CPAN modules, and different ways to install them
• http://www.perl.com/pub/a/2002/04/10/mod_perl.html - good description of how to do local installs of Perl modules without superuser privileges

Contributors: MartinCleaver, CrawfordCurrie, WillNorris, PeterThoeny, KennethLavrsen, LarsBruunxHansen, SvenDowideit, GeorgeClark - 07 Jul 2007

Discussion

Debian also has dh-make-perl ; if the repos don't have the cpan module, you can always make it yourself. needs fakeroot, a bit of sense, and disk space (also you'll need to configure CPAN via the way mentioned above).

-- SimonRaven - 20 Sep 2007

dh-make-perl looks useful - enables Ubuntu as well as Debian users to create .debs that are easily tracked through APT - see http://www.debian-administration.org/articles/78 this dh-make-perl tutorial.

-- RichardDonkin - 20 Sep 2007

For windows, on 64 bit systems, use dmake: http://tools.openoffice.org/dmake/dmake_4.6.zip

-- NicolaeRacovita - 16 Dec 2011

I've recently discovered CPAN Minus (cpanm) which appears to be a lighter-weight option for installing needed CPAN modules in local directories. It takes less overhead than CPAN proper so is more compatible with shared hosting.

-- LynnwoodBrown - 15 Aug 2013

For Gentoo linux, I've installed the following ebuilds for basic Foswiki operation:

 dev-perl/Algorithm-Diff
 dev-perl/CGI-Session
 dev-perl/Crypt-PasswdMD5
 dev-perl/HTML-Parser
 dev-perl/HTML-Tree
 dev-perl/Authen-SASL     (Needed for perl to authenticate to a SMTP email server)
 dev-perl/IO-Socket-SSL   (Needed for perl to support encrypted email connection:  STARTTLS or SSL)
 dev-perl/libwww-perl

Some of these pull in other dependencies, but these are listed in my world file.

-- GeorgeClark - 05 Jan 2014

The first of the external links no longer points where it should. I've made it non-clickable.

-- DavidRimmer - 04 Jul 2016

Commenting is disabled while not logged in