This document is a quick overview of building and configuring drivers from
the perspective of what system files have to be modified.  (For actual details
about how to construct a new device driver read the source for some of
the drivers in plplot/drivers.  Also, there are several useful sections in
the DocBook documentation [see, for example, "Output Devices" and "Driver
Functions" in Chapter 3] that you should look at.)

The following PLplot system files must be modified to add a new driver to
PLplot:

plplot/config.h.cmake
plplot/cmake/modules/drivers-init.cmake
plplot/include/drivers.h
plplot/include/plDevs.h.cmake
plplot/include/plcore.h
plplot/test/plplot-test.sh.cmake

The following are some short notes on what you need to add to these files
to add a new driver (which we'll call foo) to PLplot.

1. Add the following 2 lines to config.h.cmake:
/* Define if foo driver is present */
#cmakedefine PLD_foo

Note that drivers are listed in alphabetical order.

2. Add the following line to cmake/modules/drivers-init.cmake in set(DRIVERS_DEVICE_LIST...
"foo:foo:ON"

This is also (mostly) in alphabetical order.

3. Add the following line to include/drivers.h:
void plD_dispatch_init_foo      ( PLDispatchTable *pdt );

4. Add the following line to include/plDevs.h.cmake
#cmakedefine PLD_foo

5. Add the following 3 lines to include/plcore.h:
#if defined(PLD_foo) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_foo,
#endif

6. For each _file_ device of the driver add the following line to 
test/plplot-test.sh.cmake.  For completeness you may want to specify
the interactive devices there as well but be sure to comment them out since
the configured plplot-test.sh script does not work with interactive devices.
PLD_foo=@PLD_foo@

If the driver requires additional additional files or external libraries for
compiling and linking then you should add a file called foo.cmake to
plplot/cmake/modules and add a call to this file in the file plplot/cmake/
modules/drivers.cmake (include(foo)). The file foo.cmake should consist of 
cmake instructions for finding and the files and libraries and setting the 
appropriate environment variables (PLD_foo, foo_COMPILE_FLAGS and 
foo_LINK_FLAGS).

The code for the driver itself should be in a file called foo.c or foo.cpp in
the plplot/drivers directory.






==========================================================================
Deprecated Autotools Information
==========================================================================

The following is the list of PLplot system files that must be modified if
you are creating a new PLplot driver:

plplot/configure.ac
plplot/cf/*.ac  (e.g., plplot/cf/gd.ac)
plplot/cf/drivers-pre.ac
plplot/cf/drivers-post.ac
plplot/include/plDevs.h.in
plplot/drivers/Makefile.am
plplot/include/drivers.h
plplot/include/plcore.h
plplot/drivers/*.c (e.g., plplot/drivers/gd.c)

where plplot is the top-level directory for the plplot software tree that is
created when you unpacked the tarball (or used cvs checkout).

Some short notes follow on what is done for the individual files mentioned
above. Basically, you should be okay if you just try to follow what is done
for the gd.c driver, the associated png and jpeg devices, and any additional
headers or libraries you might require for your driver.  (libgd, libjpeg,
libpng, and libz are required for the gd driver to work and are found on
the user's system with the aid of the macros in the cf/gd.ac file.).

* plplot/configure.ac with plplotcf/gd.ac as an example of what is required
for the gd device driver (which could be used as a template for other new
devices).

Note, configure.ac has the line

m4_include(cf/gd.ac)

that includes the gd.ac file.  That latter file is used to find the system
resources used by the gd device. If you look in that file you will see logic
for finding and testing the required system headers and include libraries,
enabling or disabling the jpeg and png devices associated with the gd
driver, and ultimately forming GDINCCMD and GDLIBCMD which summarizes this
information.  For your new driver, follow this same paradigm, i.e. include
command in configure.ac, and the corresponding cf/*.ac for your particular
device driver.  For more details see plplot/cf/README.

* Some additional setup of the png and jpeg devices for the gd driver is
done in plplot/cf/drivers-pre.ac with the line

png:gd:yes, jpeg:gd:yes,

Add in a similar line for your own list of devices for your driver.

* Some additional setup of devices is done in  plplot/cf/drivers-post.ac.
I have no idea why that is separated from plplot/cf/drivers-pre.ac, but
there is nothing relevant to gd there, and probably not for your device driver
as well.

* plplot/include/plDevs.h.in

The entries in this file for the png and jpeg devices associated with the gd
driver are

#undef PLD_png
#undef PLD_jpeg

These entries inform the configure script to store the actual configured
results

#define PLD_png 
#define PLD_jpeg 

(say) in the created file plplot/include/plDevs.h.

In turn, the information in this header is used in drivers/gd.c to decide
which of the associated devices to compile.

* plplot/drivers/Makefile.am

This file tells automake and libtool how to build the various drivers, what
libraries must be linked to them, etc., for the two cases of
--enable-dyndrivers (where the drivers are built as loadable modules [i.e.,
plug-ins or DLL's]) and --disable-dyndrivers (where the drivers are built
and stored in a libtool convenience library which eventually becomes part of
libplplot).  For the gd driver look for all references to gd.  You will see
references to GDINCCMD and GDLIBCMD that are set up with sysloc.in and
configure.ac above.

* plplot/include/drivers.h

This file contains prototype definitions that occur in drivers/*.c.  For the
gd driver, these prototypes are

void plD_dispatch_init_jpeg	( PLDispatchTable *pdt );
void plD_dispatch_init_png	( PLDispatchTable *pdt );

The point of plD_dispatch_init_??? is to initialize the driver dispatch
table with the data it needs to know.  Look for void plD_dispatch_init_jpeg
and void plD_dispatch_init_png in drivers/gd.c.

* plplot/include/plcore.h

This file contains a definition of the table static_device_initializers.  In
the jpeg and png case the relevant lines are 

#if defined(PLD_png) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_png,
#endif
#if defined(PLD_jpeg) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_jpeg,
endif

* plplot/drivers/*.c

This is where the core of the driver software is defined.  plplot/drivers/gd.c
contains the software defining the gd driver with the associated png and jpeg 
devices.
