GD.pm A perl5 interface to Thomas Boutell's gd library. ABSTRACT: This is a autoloadable interface module for libgd, a popular library for creating and manipulating GIF files. With this library you can create GIF images on the fly or modify existing files. Features include: a. lines, polygons, rectangles and arcs, both filled and unfilled b. flood fills c. the use of arbitrary images as brushes and as tiled fill patterns d. line styling (dashed lines and the like) e. horizontal and vertical text rendering f. support for transparency and interlacing For full information on usage, see the accompanying man and html documentation. COPYRIGHT INFO The GD.pm interface is copyright 1995, Lincoln D. Stein. You are free to use it for any purpose, commercial or noncommercial, provided that if you redistribute the source code this statement of copyright remains attached. Code from the gd graphics library is covered separately, under a 1994 copyright by Quest Protein Database Center, Cold Spring Harbor Labs, and by Thomas Boutell. THE LATEST VERSION IS 1.16 WHAT'S NEW IN 1.16 - Patches from Andreas Koenig to use FileHandle correctly (also fixes problems with mod_perl). WHAT'S NEW IN 1.16 - Patches from Ulrich Pfeifer to allow to compile correctly with FastCGI - Patches from Douglas Wegscheid to avoid multiple defined symbol problems under NetBSD - Patches from Weinfriend Koenig to fix problems in filled polygons, plus new routines for scaling, translating and rotating polygons. WHAT'S NEW IN 1.14 - Modified gd library now included in the package. - Performance improvements. - Extensive code cleanup. - Runs correctly with FastCGI. INSTALLATION: 1. You'll need perl 5.003 or higher (5.004 is recommended). Perl is available from: a. Larry Wall's FTP site: ftp://ftp.netlabs.com/pub/outgoing/perl5.0 b. the CPAN archives: http://www.perl.com/CPAN/ Unlike previous versions of this package, you no longer need the C-language version of libgd. This package comes with a version of libgd that has been specially modified to work well with Perl. 2. Unpack the tar file: zcat GD-1.16.tar.gz | tar xvf - This will create the directory GD-1.16. Do NOT install this directory into the Perl source tree. 3. To compile GD.pm on a system that supports dynamic linking: a. cd GD-1.16 b. perl Makefile.PL c. make d. make install This will create GD.pm and copy it and its dynamically loadable module GD.so into the Perl library tree. You'll need root privileges to do the install step. If you don't have them, see below. 4. To compile GD.pm statically on systems that do not support dynamic linking (I think this includes Windows NT): a. cd GD-1.16 b. perl Makefile.PL c. make perl d. make inst_perl This will create a new version of Perl and install it in your system binaries directory, OVERWRITING THE PREVIOUS VERSION OF PERL. If you'd like to install Perl under a different name, such as "gdperl", follow this recipe: a. cd GD-1.16 b. perl Makefile.PL MAP_TARGET=gdperl c. make gdperl d. make inst_perl 5. Before you install GD, you may want to run the regression tests. You can do this after the "make" step by typing: make test 6. There are some demos you can run in ext/GD/demos. They print GIF files to standard output. To view the files, pipe their output to "display" or "xv" in this way: a. cd GD-1.16/demos b perl shapes.pl | xv - 7. See demos/gd_example.cgi for an example of how to use GD to create a picture dynamically with a CGI script. It's intended to be run under a Web server. To see it work, install it in your server's cgi-bin/ directory and invoke it from a browser by fetching a URL like: http://your.site/cgi-bin/gd_example.cgi INSTALLING GD IN YOUR HOME DIRECTORY IF YOU DON'T HAVE PRIVILEGES TO INSTALL GD.pm in your system's main Perl library directory, don't despair. You can install it into your home directory using the following feature of Makefile.PL: a. cd GD-1.16 b. perl Makefile.PL INSTALLDIRS=site \ INSTALLSITELIB=/home/fred/lib \ INSTALLSITEARCH=/home/fred/lib/arch c. make d. make install You'll now need to modify your GD-using scripts to tell Perl where to find GD. This example assumes that your home directory is at path "/home/fred"; change it as appropriate. #!/usr/local/bin/perl use lib '/home/fred/lib/perl/lib', '/home/fred/lib/perl/arch'; use GD; ... etc ... USING GD WITH FAST CGI FastCGI is a protocol from OpenMarket Corporation that markedly speeds up the execution of CGI scripts. To use FastCGI with Perl scripts, you need a specially-modified version of the Perl interpreter which you can obtain in binary and/or source form from: http://www.openmarket.com/ To use GD with a FastCGI version of Perl you'll need to recompile it using the modified Perl. In this example, I assume that this version of Perl is found at '/usr/local/fcgi/bin/perl': modify as appropriate for your system. a. cd GD-1.16 b. edit Makefile.PL and uncomment the line 'DEFINE' => '-DFCGI' c. /usr/local/fcgi/bin/perl Makefile.PL d. make e. make install IF YOU RUN INTO PROBLEMS Some versions of Unix and Unix-like systems such as Linux ship with an incomplete version of the Perl distribution. If you get warnings such as "Module ExtUtils::MakeMaker not found", you may have such a system. Your only option is to obtain the full Perl distribution and reinstall it. If the make and install all seem to go well but you get errors like "Fatal error: can't load module GD.so", or "Fatal error: unknown symbol gdFontSmall" when you try to run a script that uses GD, you may have problems with dynamic linking. Check whether other dynamically-linked Perl modules such as POSIX and DB_File run correctly. If not, then you'll have to link Perl statically, as described above. If you have problems and can't solve it on your own, post a message to the newsgroup "comp.lang.perl.modules". There are some systems that require obscure compiler and linker options in order to compile correctly, and unfortunately I have a limited number of systems at my disposal. You're much more likely to get correct answers from the gurus on the newsgroup than from myself. THE QUICKDRAW LIBRARY Also included in this package is qd.pl, a package of Quickdraw routines. If you are familiar with the Quickdraw Macintosh library, you can create Macintosh pictures (complete with scaleable fonts, draggable objects, etc. etc.) directly in Perl. See README.QUICKDRAW and qd.pl for more information. FREQUENTLY ASKED QUESTIONS 1. Are there plans to include additional fonts in GD? Maybe some day. Not soon. This is Thomas Boutell's provenance. 2. Is there a utility to convert {True Type, X Windows, Postscript} fonts into GD fonts. No. 3. Does GD run with MacPerl? Yes. The latest MacPerl binaries come with GD already compiled in and ready to go. 4. Are there any Windows NT binaries of GD? David Roth has done a port to Windows NT/95. You can find it at: http://roth.net/users/rothd/HOME.HTM Be sure to download the .DLL library version that is correct for your Perl interpreter. If there is a mismatch, you may encounter a "parse error" message. 5. GD won't compile on system XX. The most frequent problem is missing or redundant symbols during the link. If you get an error about missing math symbols (usually "floor"), then uncomment the line in Makefile.PL that starts with 'LIBS'. If you get an error about multiple redundant symbols, then comment out the line. BUG REPORTS Feel free to contact me via e-mail. UPDATES: The current version of GD can be found at: http://www.genome.wi.mit.edu/pub/software/WWW/GD.html AUTHOR: Lincoln Stein lstein@w3.org http://www.genome.wi.mit.edu/~lstein