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.17 WHAT'S NEW IN 1.17 - Patches from Gurusamy Sarathy that allow GD to compile correctly on Win32 systems. - Patches from Jan Pazdziora to handle the full ISO-Latin-2 alphabet, along with some bug fixes. 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.15 - 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.17.tar.gz | tar xvf - This will create the directory GD-1.17. 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.17 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.17 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.17 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.17/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.17 b. perl Makefile.PL INSTALLDIRS=site \ INSTALLSITELIB=/home/fred/lib \ INSTALLSITEARCH=/home/fred/lib/arch c. make d. make install p 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.17 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 95/NT binaries of GD? Thanks to Gurusamy Sarathy, GD-1.17 now compiles correctly on Win32 systems. If you have a C compiler, you can compile and install it as a .DLL library. (If you don't have a C compiler, you can get a free version of gcc at Cygnus, ftp://ftp.cygnus.com/) 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. As of January 16, David Roth's site has been inaccessible for some time (first it was not recognized by the DNS; now it asks for a user name and password). An OLD GD binary is available on CPAN, in modules/by-module/GD/DAVEROTH/Win32_gd_v961016.zip I don't know if it will work. Let me know if you have success. Alternately, download the "standard" port of perl 5.004 from a CPAN site near you. It contains a prebuilt version of GD, statically linked to the binary. 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. 6. How come the fonts are so limited? The font support comes from libgd, where the fonts are compiled into the binary. In order to keep the binary size down, only a few fonts are compiled in. Some day, perhaps, a future version will come with support for true type fonts, postscript fonts, but don't hold your breath. If you want to add fonts, and have access to X11-style BDF fonts, you can use Jan Pazdiora's utility, bdftogd. It will produce a font in a form that can be linked into libgd. You will also need to hack the files GD.xs and GD.pm to add the appropriate name for the new font. If you are savvy enough to figure bdftogd out, you'll be able to figure out what to do. bdftogd is included in this distribution with Jan's kind permission. 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