Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

This article is meant as an extension to tachyon's well written A Guide to Installing Modules. But this one focuses on the peculiarites of installation on Windows machines.

Why ppm?
Invoking ppm
Installing modules
What is a repository?
Adding a repository
Repositories.pm
Getting around the proxy
Creating a local repository
Manual installation
Resources

Why ppm?

Installing modules directly from CPAN is easy, as long as the module contains no XS-extensions (C-code). Most Windows installations don't have a C-compiler, and even if there is one, the compilation of the XS-extensions is a tricky thingy, that can easily fail. So what can you do if you can't compile? The answer is: use a precompiled version.

The probably most popular port of Perl for Win32 is ActivePerl from ActiveState. It ships with a tool named ppm, aka the Programmer's Package Manager. ppm is a tool for installing modules, similar to the CPAN-shell. With it you can download and install modules, with or without XS-Extensions, with a few keystrokes.

The following describes the ppm Version that comes with Perl 5.8.0 and above. It differs slightly from the pppm that came with Perl 5.6

Sidenote:
Perl modules built for Perl 5.8 are not binary compatible with modules build for Perl 5.6! That means they are not interchangeable.

Advantages and features of ppm

  • No need for a C/C++ compiler and 'make' utility
  • Automatic installation and deinstallation of modules
  • Automatic resolution of module dependencies
  • Automatic integration of module documentation into the html-documentation that comes with ActivePerl.
  • Maintainance of a database of installed modules and module versions.
  • An easy-to-use shell

As always, there are some tripwires and things you should know.

Disadvantages

  • Core modules are not part of ppm's database
  • Less security. You cannot tell if the supplier added evil code to the XS-part of a module.

Invoking ppm

To invoke ppm, simply type ppm at the Windows console ("DOS") command line. The result will look similar to this:

C:\>ppm PPM - Programmer's Package Manager version 3.1. Copyright (c) 2001 ActiveState Corp. All Rights Reserved. ActiveState is a devision of Sophos. Entering interactive shell. Using Term::ReadLine::Stub as readline lib +rary. Type 'help' to get started. ppm>

To get immediate help in the ppm-shell, type help or help <command>.

Installing modules

In order to install a module you have basically two possibilities.

  • Specify a module to install directly
  • Search for a module and choose a one from the results shown

Direct install

To install a module (here: Death::Star) directly, simply type

ppm> install Death::Star

There is a drawback to using this method. If ppm finds more than one version of a module, you cannot choose which one gets installed. Naturally the most recent version gets installed, but there may be a case when you need to install another version. E.g. the most recent version can be buggy, or incompatible with another module you use.

You don't neccessarily need to use the ppm-shell to install a module. You can also use the following command to install a module directly from the command line.

C:\> ppm install Death::Star

Search-and-Install

To search for a module you use the search <string>-command. The parameter <string> for search is a case insensitive regex, thus if you don't know the module's full name, you can also search for pieces of it and you will get a list to choose from.

ppm> search Death::Star Searching in Active Repositories 1. Death::Star [1.0] a module to kill planets 2. Death::Star [2.0] kill planets with more firepower ppm>

You can find out more about a module by using the desc <module>-command.

ppm> desc 2 ==================== Package 2: Name: Death::Star Version: 2.0 Author: Darth Vader (anakin@the-empire.com) Title: The Deathstar Abstract: a planet killing module Location: ActiveState PPM2 Repository Available Platforms: 1. MSWin32-x86-multi-thread-5.8 ====================

To install a module from the list, type install, followed by the module's number.

ppm> install 2

Regardless which method you choose, ppm will start to install the module and produce output like this:

Package 2: ==================== Install 'Death::Star' version 2.0 in ActivePerl 5.8.6.811. ==================== Downloaded 4657 bytes. Installing C:\Perl\html\site\lib\Death\Star.html Installing C:\Perl\site\lib\Death\Star.pm Successfully installed Death::Star version 2.0 in ActivePerl 5.8.6.811 +. ppm>

If the module has dependencies (that is, it requires another module to work correctly) the dependencies are installed first.

What is a repository?

From above, you may have noticed the term Active Repositories. ppm downloads the modules from special websites that are called repositories. A repository is a just a directory or a script that serves a list of ppd files to ppm. From these ppd files, ppm gets the actual location of the module's tarball. A freshly installed ActivePerl will come with two repositories. To find out about them, type rep.

ppm> rep Repositories: [ 1] ActiveState PPM2 Repository [ 2] ActiveState Package Repository ppm>

In order to find out, which url a repository points to, you can use the rep desc <repository>-command.

ppm> rep desc 1 Describing Active Repository 1: Name: ActiveState PPM2 Repository Location: http://ppm.ActiveState.com/cgibin/PPM/ppmserver-5.8-windows.pl?urn:/PP +MServer Type: PPMServer 2.0 ppm>

Adding a repository

A lot of modules are not available from the standard repositories. Thank crunchy, the community provides a lot of alternative repositories that offer the missing modules. For example our fellow brother jenda hosts a repository at http://jenda.krynicky.cz/perl.

If you want to add such a repository to ppm you will have to use the rep add <name> <location>-command.

ppm> rep add jenda http://jenda.krynicky.cz/perl Repositories: [ 1] ActiveState PPM2 Repository [ 2] ActiveState Package Repository [ 3] jenda ppm>

From there on, the repository is known to ppm and will be used for future searches.

You don't need to permanently add a repository to install a module from it. You can specify the repository from the command line.

C:\> ppm install http://the.empire-rules.com/ppm/Death-Star.ppd

Repositories.pm

So how, you might ask, do I find out where these repositories are? The answer to this question is PPM::Repositories.pm. That's a module that basically consists of a list of all known repositories. The, at the time of this writing, most recent version (0.9) is available at bribe's repository at http://www.bribes.org/perl/ppm/

With the following script, you can use PPM::Repositories.pm to add all known repositories to your ppm.
use PPM::Repositories; for ( keys %Repositories ) { print `ppm repository add $_ $Repositories{$_}->{location}`; }

You should be aware that the more repositories you add, the longer it takes for a search to finish.

Getting around the proxy

If you are behind a proxy, you will notice that ppm cannot connect to the internet. To make it work, you will have to set a bunch of environment-variables, where xxx.xxx.xxx.x is the ip-address of the proxy, and y the port:

c:\> set http_proxy=http://xxx.xxx.xxx.x:yyyy c:\> set http_proxy_user=username c:\> set http_proxy_pass=password

Instead of entering the variables each time you before you start ppm, you have other possibilities to set them:

  • Click Start->Settings->Control Panel->System. Select the Expanded Tab, Click Environment. Click New, enter the appropriate values and click Ok.
  • Edit /perl/bin/ppm.bat and insert above lines right after @echo off

Creating a local repository

Still there may be some environments where that fails. But don't worry, there is an alternative, namely creating a local repository.

The first step doing so is to create a directory on your system that serves as the repository. Name and position of that directory is not important, I use /perl/ppm/repository as an example.

Then add that directory to your ppm using the command described in adding a repository.

ppm> rep add myRepository /perl/ppm/repository
The next step is to download the ppd file of the module and save it to your repository. A ppd file is a xml file that contains information about the module's position, version, etc. It looks like
<SOFTPKG NAME="Death-Star" VERSION="2,00,0,0"> <TITLE>The Deathstar</TITLE> <ABSTRACT>a planet killing module</ABSTRACT> <AUTHOR>Darth Vader (anakin@the-empire.com)</AUTHOR> <IMPLEMENTATION> <ARCHITECTURE NAME="MSWin32-x86-multi-thread-5.8" /> <OS NAME="MSWin32" /> <CODEBASE HREF="x86/Death-Star-2.0.tar.gz" /> </IMPLEMENTATION> </SOFTPKG>

Identify the line that says <CODEBASE HREF="x86/Death-Star-2.0.tar.gz" />. It informs you about the relative position of the module's tar.gz-file, aka tarball. Now download that tarball and save it into the same relative postion. In this example that would be /perl/ppm/repository/x86/Death-Star-2.0.tar.gz.

Now you can use ppm to install the module from your local repository.

Manual installation

You also have the choice to install the module manually. To do so, simply download the tarball and extract it with WinZip or a similar program.

A typical ppm-distribution looks like this:

C:/blib/ +---arch/ +---auto/ +---Death/ +---Star/ #Star.dll +---html/ +---site/ +---lib/ +--Death/ #Star.html +---lib/ +---Death/ #Star.pm

Now you can copy the files manually into your Perl's library tree, namely

C:\> copy \blib\lib\Death\Star.pm \Perl\site\lib\Death\Star.pm C:\> copy \blib\arch\auto\Death\Star\Star.dll \Perl\site\lib\auto\Deat +h\Star\Star.pm C:\> copy \blib\html\site\lib\Death\Star.html \Perl\html\site\lib\Deat +h\Star.html

Be aware that the module's html-documentation will not be integrated into the ActiveState-docs automatically. But if you do a complete rebuild of the HTML documentation, it will be added:

perl -MActivePerl::DocTools -e "UpdateHTML(1)"

Resources

Using PPM to install modules
PPM::Make - Make a ppm package from a CPAN distribution
ppm3 - Programmer's Package Manager, version 3.1
how to create a ppm-distribution
HowTo build and distribute a PPMed module for Win32

I hope this article can make its way into the tutorials section. I hereby invite every monk to improve this document.

Update: Corrected error concerning "Getting around the proxy"
Update: Included thundergnat's tip in the text, as suggested by GrandFather.


holli, /regexed monk/

In reply to A guide to installing modules for Win32 by holli

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others musing on the Monastery: (11)
    As of 2014-08-20 13:52 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      The best computer themed movie is:











      Results (114 votes), past polls