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.

WHAT'S NEW IN VERSION 1.10

	- Modified gd library now included in the package.
	- Performance improvements.
	- Extensive code cleanup.
	- Runs correctly with FastCGI.

INSTALLATION:

1.  You'll need perl 5.002 or higher (5.003 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.10.tar.gz | tar xvf -

    This will create the directory GD-1.10. 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.10
	b.  perl Makefile.PL
	c.  make
	d.  make install

    This will create GD.pm and copy itm 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.10
        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.10
        b.  perl Makefile.PL MAP_TARGET=gdperl
        c.  make gdperl
        d.  make inst_perl

5.  GD has a series of regression tests which you can run with:

	make test

    Unfortunately it seems that the color tables generated by GD are
    slightly different on different systems, making the
    regression tests worthless for anything but a Linux/Pentium.  
    Try running the demos instead (next step) and seeing if the output
    looks reasonable.

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.10/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 trick:

	cd ~
	mkdir lib
	mkdir lib/perl
        mv    GD-1.10/blib/* lib/perl

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.10
	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?

   No.  If you manage to compile and get it running, let me know.

4. Are there any Windows NT binaries of GD?

   It ought to, but I don't know of anyone who actually has done so.
   Although a Windows NT system is available to me, I don't have any
   developers tools.  I'm happy to accept donations! :-)

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@genome.wi.mit.edu
http://www-genome.wi.mit.edu/~lstein