Windows 2000 PerlMagick Web Server How-to

Part of Dylan's Collection of PerlMagick Stuff

June 2013: This article is also online in Serbo-Croatian - thanks to Anja Skrba for the translation!

This document describes the installation and configuration of ActivePerl, ImageMagick and PerlMagick under Microsoft's IIS5 web server, part of the Windows 2000 Server and Advanced Server operating systems. After following these instructions, you should have a system capable of dynamically creating and manipulating images and sending them directly to a remote users' web browser or storing them on the server's local filesystem.

ActivePerl is the leading Windows version of the popular Perl scripting/programming language. For more information see

ImageMagick is an open-source image manipulation library available for most operating systems and platforms. For more information see http://www.imagemagick.org/

PerlMagick is an object-oriented Perl interface to ImageMagick, allowing Perl scripts to create and manipulate images. For more information see http://www.imagemagick.org/www/perl.html

Prerequisites

Windows 2000 and IIS

You should already have a working installation of Windows 2000 Server or Advanced Server, with IIS installed and configured. IIS configuration is beyond the scope of this document, and I won't go into any more detail than is necessary.

Not running Windows 2000?

Notes on installing PerlMagick under other versions of Windows (95, 98, Me, NT or XP) are available here. These notes are generally contributed by other users - I haven't tested any of them personally.

Note on Versions

In my experience, PerlMagick is *extremely* sensitive to version differences. PerlMagick requires two components - the PerlMagick module itself, and the ImageMagick binaries (.DLLs). Version inconsistencies between these two packages almost invariably crash - for instance, PerlMagick 5.2.5 will not work with ImageMagick 5.2.6.

These instructions are based on a complete install of ImageMagick 5.4.4 using ActiveState ActivePerl build 631. I've also included instructions for rolling your own modules from other versions of the source code.

The Really Easy Way

This doesn't include any ImageMagick command line tools, just the Perl module and required binaries.

Ingredients
Instructions
  1. Install ActivePerl. Following all the defaults works for me. To check if it's installed and working, save the following as hello.pl in a directory on your web server - here we're using /cgi-bin/. Ensure the directory has execute permissions under IIS. 
    #!/bin/perl
print ("Content-type:text/html\r\n\r\n");
print ("<html><body><h1>Hello World!</h2></body></html>");

    Pointing a browser at http://myserver/cgi-bin/hello.pl should display something like:

    Hello World!

    If it doesn't, your Perl/IIS configuration isn't working properly - go hassle the IIS gurus and come back when it's working :)
    From here on in, we assume you've installed Perl in c:\perl. If you've installed it elsewhere, replace c:\perl\ with whatever your path is in the following instructions - it's been highlighted in red throughout these examples.

  2. Download the latest full PPM package from the downloads page. Unzip it into c:\temp. Make sure you expand the folders inside the ZIP file - the -d option if you're using unzip.exe or the 'Use folder names' option in WinZip. You should now have a folder c:\temp\x86 with a file called Image-Magick.tar.gz in it.

  3. Do this: 
    C:\temp>ppm install Image-Magick.ppd
    Installing package 'Image-Magick.ppd'...
    Installing C:\Perl\site\lib\auto\Image\Magick\colors.mgk
    -- removed lots of lines similar to the above ---
    Installing C:\Perl\site\lib\auto\Image\Magick\Magick.lib
    Installing C:\Perl\site\lib\Image\Magick.pm
    Writing C:\Perl\site\lib\auto\Image\Magick\.packlist
    
C:\temp>
    If you see the above, it means it's worked. If you get: 
    C:\temp>ppm install Image-Magick.ppd
'ppm' is not recognized as an internal or external command,
operable program or batch file.

C:\temp>
    it means your installation of ActivePerl isn't configured properly - you need to make sure that the folder containing ppm.bat (usually c:\perl\bin) is in your system path:
  4. You now need to set two environment variables - either from the command line, or by right-clicking 'My Computer', Properties, Advanced, Environment Variables:
    1. set MAGICK_HOME=c:\perl\site\lib\auto\Image\Magick
    2. add c:\perl\site\lib\auto\Image\Magick to your system path.
  5. Restart the computer. It seems IIS won't acknowledge the modified environment variables unless it's rebooted - just restarting IIS isn't sufficient.
Testing

Save the file imagedemo1.pl into the /cgi-bin/ directory we discussed earlier. Now point your browser at http://myserver/cgi-bin/imagedemo1.pl If you see the following:

then PerlMagick is installed OK. If you get anything else, you have a problem. Generally a 'broken image' icon indicates that Perl is working fine and PerlMagick is having difficulties, while an HTTP 500 error means either there's an error in the Perl script or a problem with your ActivePerl installation. See 'Troubleshooting' below for more info, or refer to my page of PerlMagick debugging tips.

The Hard Way

This allows you to roll your own PPM package - useful for deploying on remote servers which don't have Visual C++ installed.

Instructions

  1. Make sure ActivePerl is installed and configured - you should be able to do this:

    C:\>perl -e "print 'Hello World!';"
Hello World!
C:\>

    If you get a 'not recognised yada yada yada' message, then your path isn't set up properly - refer to the instructions above. Ignore the bit about web servers unless your build workstation is also your web server.

  2. Make sure zip.exe, unzip.exe, tar.exe and gzip.exe are in your search path - the easiest way to do this is to copy them to c:\windows\system32 (or wherever your copy of format.com resides - that's where Windows keeps the command-line DOS utilities)

  3. Unzip the ImageMagick source tree to a local drive. The source tree includes full path information so just unzipping it to C:\ should give you a full source tree under C:\ImageMagick-5.4.0\ or whatever.

  4. Build ImageMagick according to the instructions, which you'll find in \ImageMagick-5.4.0\www\install.html (or wherever you put it.) If you hold an LZW license from Unisys and want to enable LZW compression, you should edit the 'magick_config.h' file and uncomment the #define HazLZW line. Make sure you set the project configuration to All - Win32 Release (Build -> Set Active Configuration in VC++) This will put all the DLLs (along with the command-line tools such as convert.exe) in ImageMagick-5.4.0\VisualMagick\bin. These DLLs need to be present in the /perl/bin directory on the PerlMagick system - it's worth taking a ZIP snapshot of the DLLs for future deployments.

  5. From a command prompt, cd to the ImageMagick-5.4.0/PerlMagick directory and do the following:

    C:\ImageMagick-5.4.0\PerlMagick>perl makefile.nt
C:\ImageMagick-5.4.0\PerlMagick>nmake
C:\ImageMagick-5.4.0\PerlMagick>nmake ppm

You should now have a file PerlMagick.zip in the \PerlMagick directory. This contains a PPM (Perl module package) of the Image::Magick module.

Deployment

(Assuming ActivePerl is installed and running on the target machine - if not, follow the ActivePerl install instructions in the 'Quick Way' section above)

  1. Copy or unzip all the DLLs from step (4) into the perl\bin directory on the target machine
  2. Create C:\imagemagick (or whatever your system drive is) and move the *.mgk files from the DLL archive into this folder.
  3. Extract PerlMagick.zip into c:\temp - make sure you expand it with folder names (-d on pkunzip.exe or 'Use folder names' in WinZip)
  4. Do the following: 
    C:\TEMP>ppm install Image-Magick.ppd
Retrieving package 'Image-Magick.ppd'...
Installing D:\perl\site\lib\auto\Image\Magick\Magick.dll
Installing D:\perl\site\lib\auto\Image\Magick\Magick.lib
Installing D:\perl\site\lib\auto\Image\Magick\Magick.exp
Installing D:\perl\site\lib\auto\Image\Magick\Magick.bs
Installing D:\perl\site\lib\auto\Image\Magick\autosplit.ix
Installing D:\perl\site\lib\Image\Magick.pm
Writing D:\perl\site\lib\auto\Image\Magick\.packlist
  5. C:\TEMP>
  6. That's it - assuming everything's gone OK, your system should now be ready to go.

Sample Scripts

Once you get into PerlMagick, you'll realise actually installing it was the easy part... :) Here's a couple of simple scripts to get you started - they've got an extra .txt extension to allow you to view the source code straight from your browser; remove the .txt if you're saving them locally to try out.

imagedemo1.pl - a simple bevelled button

imagedemo2.pl - a bevelled button with colours specified using CGI parameters

imagedemo3.pl - as above, with some annotated text specified using CGI parameters

buttons.html - HTML file showing how to use imagedemo3.pl

Further Info / Troubleshooting

I've created a page of debugging and troubleshooting tips for PerlMagick scripts here which you may find useful.

Ron Savage has created a set of hax - small, trivial example scripts - intended to demonstrate the various features of PerlMagick. These are available here.

For all ImageMagick/PerlMagick related questions, your first port of call should be the ImageMagick mailing lists at http://www.imagemagick.org/www/magick-list.html - I read them daily, and so do lots of people who know a lot more about it than I do.

If you have a specific problem and/or solution relating to the material in this document, send it to me at <imagemagick [at] dylanbeattie [dot] net> and I'll try and incorporate it into future revisions.

This document may be freely redistributed. It may be edited on the condition that you indicate clearly
which bits are original and which are your own amendments - I don't want people emailing me 'cos you screwed up.

Copyright (c) 2001 Dylan Beattie <imagemagick [at] dylanbeattie [dot] net>

http://www.dylanbeattie.net/magick/