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 PNG files. With this library you can create PNG 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 g. support for TrueType font rendering, via libfreetype. h. support for spline curves, via GD::Polyline i. support for symbolic font names, such as "helvetica:italic" j. support for symbolic color names, such as "green", via GD::Simple k. produces output in png, gif, jpeg and xbm format l. produces output in svg format via GD::SVG. For full information on usage, see the accompanying man and html documentation. Also check the FAQ at the bottom of this document. => IMPORTANT: This version of GD REQUIRES libgd 2.0.28 or higher. If you <= => have an older version of libgd installed you must remove libgd.a, <= => libgd.so (if present) and gd.h. Then install the new version of <= => libgd from www.boutell.com (see below). This particularly <= => applies to users of Linux systems. Older versions of GD are <= => available at http://www.cpan.org. <= COPYRIGHT INFO The GD.pm interface is copyright 1995-2004, Lincoln D. Stein. It is covered by the Perl "Artistic License", which allows for free usage and redistribution. See the Artistic License in the Perl source package for details. INSTALLATION: Read these instructions all the way through before you start! 1. Make sure you have downloaded and installed the following packages: a. Perl 5.6.0 or higher: http://www.perl.com/ b. The gd graphics library: http://www.boutell.com/gd/ c. The PNG graphics library: http://www.libpng.org/pub/png/libpng.html d. The zlib compression library: http://www.gzip.org/zlib/ (OPTIONAL) e. The FreeType font rendering library for TrueType fonts: http://www.freetype.org/ f. The JPEG library, version 6b or later: ftp://ftp.uu.net/graphics/jpeg/ g. The XPM library, a standard part of modern X Windows distributions. If you don't have a modern version of X, don't try to get XPM working. If this module fails to compile and link, you are probably using an older version of libgd. Symptoms of this problem include errors about functions not being recognized in the gd.h header file, and undefined symbols from the linker. If you are having this type of error, please REMOVE all versions of libgd, gd.h from your system and reinstall libgd 2.0.28 or higher. Do not contact Lincoln for help until you have done this. Use GD 1.41 for libgd versions 1.8.4 and lower. 2. Unpack the tar file: zcat GD-2.XX.tar.gz | tar xvf - (Where "XX" is the most recent revision number.) This will create the directory GD-2.XX. 3. To compile GD.pm on a system that supports dynamic linking: a. cd GD-2.XX b. perl Makefile.PL c. make d. make test (optional) e. make html (optional) f. make install This will create GD.pm, its HTML manual page, and install GD into the system-wide Perl library directory. You'll need root privileges to do the install step. If you don't have them, see below. During step (b), Makefile.PL will look for the program gdlib-config that newer versions of libgd install for you. If this program is not present, the Makefile.PL script will ask you whether to build support for JPEG, FreeType and/or XPM image formats. Please answer "y" (the default) if libgd was built with the feature, and "n" if it was not. Failure to answer correctly will lead to link errors. If, during step (b) you see notes about missing libraries, then this module will probably not link correctly, even though the warning may say "probably harmless". 4. To compile GD.pm statically on systems that do not support dynamic linking: a. cd GD-2.XX b. perl Makefile.PL LINKTYPE=static c. make perl d. make -f Makefile.aperl inst_perl MAP_TARGET=gdperl This will create a new version of Perl and install it in your system binaries directory, under the name "gdperl". 5. Before you install GD, you will want to run the regression tests. You can do this after the "make" step by typing: make test If any tests fail, you might want to run them verbosely with: make test TEST_VERBOSE=1 6. There are some demos you can run in ext/GD/demos. They print PNG files to standard output. To view the files, pipe their output to "display" or "xv" in this way: a. cd GD-2.XX/demos b perl shapes.pl | display - You will need a graphics program that can read and display PNG format. I recommend Image::Magick's display program, available from ftp://ftp.wizards.dupont.com/pub/ImageMagick/ If you don't have any display programs handy, you can save to a temporary file and display with recent versions of Netscape or Internet Explorer. 7. A program named fonttest is included in this package under demos. This generates an image showing all the built-in fonts available. If you have built libgd with TrueType support, and you have a directory containing some TrueType fonts, you can create a simple font listing by running the program truetype_test, also located in demos. 8. 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-2.XX b. perl Makefile.PL LIB=/home/fred/lib c. make d. make install (change /home/fred/lib as appropriate for your home directory). This will install GD.pm in /home/fred/lib. You may get some errors about not being able to install the manual pages. Either don't worry about it, or run the "perl Makefile.PL" step with the INST_MAN3DIR variable set to some directory you have write permission for. 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'; 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.fastcgi.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-2.XX b. edit Makefile.PL and uncomment the line 'DEFINE' => '-DFCGI' c. /usr/local/fcgi/bin/perl Makefile.PL d. make e. make install Note that these instructions have not been verified for a long time, and may no longer work. If you successfully use this module with FastCGI and find that the instructions are no longer valid, please send me the updated information. 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. Other problems may be fixed by compiling libgd as a shared library, as described in step (2) of the installation instructions. If you are trying to compile and link GD on a Windows or Macintosh machine and fail, please verify that you are able to build the Perl distribution from source code. If you can't do that, then you don't have the compiler/linker/make tools required for building Perl modules. You may not even need to do this, as ActiveState and MacPerl both include precompiled versions of GD. 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 GD::SIMPLE LIBRARY GD::Simple is a simplified API for GD. It supports turtle graphics, a unified interface for drawing text, and symbolic color names (like "green"). Run "perldoc GD::Simple" for information on using it. The GD::SVG LIBRARY GD::SVG, which is available separately on CPAN, provides a subset of GD method calls. For this subset, you can create images in SVG (scaleable vector graphics) format. 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. I get a warning about prerequisite Math::Trig not being found The version of Math::Trig that comes with Perl version 5.6.0 and lower has a bug in it that causes it not to be found even when it is installed. Try running perl -MMath::Trig -e0 from the command line. If you get no errors, go ahead and install GD. If you get an error, install Math::Trig from CPAN. 2. Why do I get errors about functions not being found when building this module? You need libgd (the C library that does all the work) version 2.0.28 or higher. Older versions will give you errors during GD installation. Get the latest version from www.boutell.com and install it. Sometimes just installing the new version of libgd is not enough: you must remove the old library first. Find the gd.h include file and all libgd files and remove them from your system. 3. Why do I get errors about symbols being undefined when building this module? See (1). 4. The %&#&#! thing doesn't compile at all! I'm getting lots of compile errors! Does "make" fail with messages like these? GD.xs: In function 'newDynamicCtx': GD.xs:440: error: 'gdIOCtx' has no member named 'gd_free' GD.xs: In function 'gd_cloneDim': GD.xs:460: error: 'struct gdImageStruct' has no member named 'alpha' GD.xs:460: error: 'struct gdImageStruct' has no member named 'alpha' GD.xs:466: error: 'struct gdImageStruct' has no member named 'thick' GD.xs:466: error: 'struct gdImageStruct' has no member named 'thick' If so, then you may have an old gd.h include file located somewhere in your system include path. Please find it and remove it. A typical location is /usr/include/gd.h. The way to make sure you are removing the correct gd.h is to run "gdlib-config --cflags" to find out where the current gd.h lives: % gdlib-config --cflags -I/usr/local/include This tells you that /usr/local/include/gd.h is the correct gd.h. Please find and remove any other gd.h. 5. My scripts fail with "Can't locate object method 'png' via package "GD::Image". libgd can now be built with support for one or more of the PNG, GIF, XPM or JPEG formats. If one or more of these formats are not supported by libgd, then the corresponding GD::Image methods will be unavailable. Unfortunately, many older scripts assume that the png() method will always be present. You can work around this issue with code like the following: my $image = $gd->can('png') ? $gd->png : $gd->gif; or if you prefer eval {} my $image = eval {$gd->png} || $gd->gif; As of libgd 2.0.33, GIF support is always compiled in, so (for the time being!) this is a safe fallback. 6. Is there a utility to convert X Windows BDF fonts into GD fonts. Yes. See the utility bdf2gdfont.pl. Run "bdf2gdfont.pl -h" to get help on using this. 7. Does GD run with Macintosh OS X? Yes. GD compiles just fine under OSX. However, you may need to remove old versions of libgd, libpng, and libz and reinstall the current versions before you try to install GD. 8. Does GD run with Win32 Perl? The latest ActiveState binaries for Win32 systems come with GD already compiled in and ready to go. I don't own any Win32 systems, and cannot provide you with help in compiling GD from scratch on such systems. 9. GD won't compile on system XX. Because libgd relies on multiple external libraries, GD does as well. Unfortunately, different systems place their libraries in different places and sometimes are picky about the order in which libraries are linked. The best thing to do is to install the latest version of libgd. Recent versions of libgd contain a gdlib-config utility, which GD will use to determine which libraries are necessary and in which order to link them. Another thing to be aware of is that some Unix distributions provide a faulty precompiled version of Perl which is unable to build and load new C-based modules (like this one). If you are getting errors like this: /arch/auto/GD/GD.so: undefined symbol: SetCPerlObj at .... then you may have such a faulty version of Perl. The most reliable thing to do is to recompile Perl from source code, thereby ensuring that it is complete. 10. When I try to load an XPM file, all I get is blackness! The libgd createFromXpm() function works with some XPM files, and not with others. The problem is buried deep in the libXpm library somewhere. 11. The stringFTCircle() method doesn't work! I know. I think this might be a problem in libgd because I have never gotten it to work as a C program. If you have any insight into this problem let me know. 12. Test XX fails The regression tests for GD involve generating images, saving them as PNG, JPEG or GIF files, and then comparing the files bit-for-bit to known "correct" files. Sometimes one of the underlying C libraries such as libz, libpng or libgd is updated, causing GD to generate an image that is subtly different. These differences are usually insignificant, such as a reordering of colors in the color table, but they will call isolated tests to fail. If you are seeing the great majority of GD tests pass, but one or two fail, then you are probably seeing the effect of a new library. Just go ahead and install GD and drop me a note about the problem. BUG REPORTS Feel free to contact me via e-mail, subject to the caveats below. Provide the version numbers of GD, Perl, make and model of your operating system, and make and model of your Web server, if appropriate. Provide a small script that demonstrates the bug. Do NOT contact me for issues involving compilation failures on Windows, VMS, or Macintosh systems. I do not have any such systems on hand, and cannot help you out. Also do NOT contact me for issues involving the images looking distorted, having the wrong color tables, or other such low-level issues. These problems should be referred to Tom Boutell because they pertain to the underlying libgd library. ACKNOWLEDGEMENTS: I'd like to thank Jan Pazdziora, Geoff Baysinger, and David Kilzer for their contributions to the library, as well as Thomas Boutell who wrote libgd. UPDATES: The current version of GD can be found in CPAN. AUTHOR: Lincoln Stein lstein@cshl.org http://stein.cshl.org/~lstein