Next: , Previous: Older C APIs, Up: C Programming


9.2.3 C compiling and linking

The source code for a graphics application written in C, if it is to use the GNU libplot C API (C application programming interface), must contain the lines

     #include <stdio.h>
     #include <plot.h>

The header file plot.h is distributed with libplot, and should have been installed on your system where your C compiler will find it. It contains a prototype for each of the functions in the C API, and some miscellaneous definitions.

To each Plotter operation there corresponds a function in the C API whose name begins with "pl_" and ends with "_r". To invoke the Plotter operation, this function would be called. For example, the openpl operation would be invoked on a Plotter by calling the function pl_openpl_r, the first argument of which is a pointer to the Plotter. All such functions are declared in plot.h.

In releases of GNU libplot before libplot 3.0, Plotter operations were performed in a different way. For example, there was a function pl_openpl that operated on a Plotter that was `selected', rather than specified as an argument. The old C API is still supported by plot.h. For more information on it, see Older C APIs.

In even older releases of GNU libplot, and in the non-GNU versions of libplot that preceded it, the "pl_" prefix was not used. If you need to compile code written for early versions of GNU libplot or for non-GNU libplot, you should also include the header file plotcompat.h. That file redefines openpl as pl_openpl, and so forth.

To link your application with GNU libplot, you would use the appropriate ‘-l’ option(s) on the command line when compiling it. You would use

     -lplot -lXaw -lXmu -lXt -lXext -lX11 -lpng -lz -lm

or, in recent releases of the X Window System,

     -lplot -lXaw -lXmu -lXt -lSM -lICE -lXext -lX11 -lpng -lz -lm

These linking options assume that your version of libplot has been compiled with PNG support; if not, you would omit the ‘-lpng -lz’ options.

As an alternative to the preceding, you may need to use ‘-lplot -lXm -lXt -lXext -lX11 -lpng -lz -lm’, ‘-lplot -lXm -lXt -lXext -lX11 -lpng -lz -lm -lc -lgen’, or ‘-lplot -lXm -lXt -lXext -lX11 -lpng -lz -lm -lc -lPW’, on systems that provide Motif widgets instead of Athena widgets. In recent releases of the X Window System, you would insert ‘-lSM -lICE’. Recent releases of Motif require ‘-lXp’ and possibly ‘-lXpm’ as well.)

On some platforms, the directories in which libplot or the other libraries are stored must be specified on the command line. For example, the options ‘-lXaw -lXmu -lXt -lSM -lICE -lXext -lX11’, which specify X Window System libraries, may need to be preceded by an option like ‘-L/usr/X11/lib’.

On most systems libplot is installed as a shared library. This means that the linking with your application will take place at run time rather than compile time. The environment variable LD_LIBRARY_PATH lists the directories which will be searched for shared libraries at run time. For your application to be executable, this environment variable should include the directory in which libplot is stored.