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.  For some additional details about the
core paging and familying code see ../src/README.pages.  Finally, 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 are some short notes on what PLplot source tree files need
to be added or modified in order to add a device (which we'll call <device>) to
a device driver (which we'll call <driver>).

The following PLplot source-tree files are affected:

1. drivers/<driver>.driver_info.in
2. cmake/modules/drivers-init.cmake
3. include/drivers.h
4. include/plDevs.h.in
5. include/plcore.h
6. plplot-test/plplot-test.sh.in
7. examples/plplot_configure.cmake_installed_examples.in
8. include/pldll.h.in

1. Add a line to drivers/<driver>.driver_info.in consisting of the following
colon-separated fields:

<device>:<description string>:<interactive?>:<driver>:<device number>:<device>

This should be the exact duplicate of the corresponding entry in the
driver source code for plD_DEVICE_INFO_<driver>.

MAINTENANCE (2018-08-24):
To check the consistency of these results I used the following
commands (under Linux) to collect these data in two different ways in
order of device number (to make sure those are unique):

cat *.driver_info.in |sort -n --field-separator=":" --key=5 >| /tmp/sorted_drivers.1

grep '"[^:]*:[^:]*:[^:]*:[^:]*:[^:]*:[^:]*'  * |grep -vE 'README|txt' |cut --delimiter='"' --fields=2 |grep -v '%d' |sed -e 's?\\n??' |sort -u -n --field-separator=":" --key=5 >| /tmp/sorted_drivers.2

(The grep -vE 'README|txt' pipeline stanza gets rid of non source-code files that match this
colon pattern.  The grep -v '%d' stanza gets rid of a printf line that matches this colon pattern.
The -u option on the sort command is used to eliminate duplicates created by the
deprecated version of the wxwidgets device driver.)

diffing the two results shows there is the stanza

wxpng:wxWidgets PNG Driver:0:wxwidgets:52:wxpng

in the driver code that is not replicated in the relevant *.driver_info.in file, but
this is a well-known case of a disabled device so this difference is not significant.

Furthermore, checking the sorted device numbers in
/tmp/sorted_drivers.1 (or /tmp/sorted_drivers.2) shows they are
strictly ascending, i.e., unique as of the above maintenence date.

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

"<dev>:<driver>:ON:<kind>:<familied>"

where that file documents how the last two fields should be set depending
on the characteristics of the device you are adding.

3. Add the following line to include/drivers.h:
PLDLLIMPEXP_DRIVER void plD_dispatch_init_<device> ( PLDispatchTable *pdt );

4. Add the following line to include/plDevs.h.in
#cmakedefine PLD_<device>

5. Add the following 3 lines to include/plcore.h:
#if defined(PLD_<device>) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_<device>,
#endif

6. For each interactive and file device of the driver add the
following line to plplot_test/plplot-test.sh.in:

PLD_<device>=@PLD_<device>@

Note, that the interactive and file devices are dealt with in separate places
in that script so be careful where you put the above change.

7. Add the following line to
examples/plplot_configure.cmake_installed_examples.in:
set(PLD_<device> @PLD_<device>@)

8. For dynamic drivers (the most likely situation), add <driver>_EXPORTS
to the #ifdef ENABLE_DYNDRIVERS statement of include/pldll.h.in

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

The code for the driver itself should be in a file called <driver>.c or
<driver>.cpp in the drivers directory.