How to use the Ada bindings

Ada 95 versus Ada 2005

The bindings will work for either Ada 95 or Ada 2005. The only difference that concerns PLplot users is that Ada 2005, in Annex G.3, provides declarations for real-valued vectors and matrices (along with some other functionality). These declarations make available type Real_Vector and type Real_Matrix.

The installation process for PLplot requires you to select Ada 95 or Ada 2005. After that, the correct bindings are generated automatically depending on your choice. The differences are very minor: If Ada 2005, the type declarations provided according to Annex G.3 are used; if Ada 95, similar type declarations are provided explicitly in the bindingss. For the most part, you don't need to think about this much. However, see Section 9, Compilation Notes, if you are using Ada 95 and need to declare vectors or matrices. The design goal in either case is to encourage users to use Real_Vector and Real_Matrix since these are the "official" versions of these entities as of Ada 2005. Someone using objects based on these type definitions in Ada 95 in their PLplot programs should expect their programs to work without modification if they should switch to Ada 2005.

GNAT versus non-GNAT

The bindings were made using the GNAT compiler and there is a slight dependence on that compiler. Specifically, the Unrestricted_Access attribute of GNAT was used in making the function Matrix_To_Pointers in plplotthin.adb and in a few callbacks. Matrix_To_Pointers is called whenever an Ada matrix (2D array) is passed to a PLplot subroutine. For more about Unrestricted_Access attribute, see Implementation Defined Attributes in the GNAT Reference Manual. This dependency shouldn't be difficult to remove by either incorporating the GNAT code which implements it, by following the TO-DO comment near the function definition in plplotthin.adb, or by providing the proper aliasing.

Another GNAT dependency is used to parse command line arguments in a C-like way.

Pragma Warnings (Off, "some text") and Pragma Warnings (On, "some text") are used in the bindings to suppress warnings about a particular method used to intereface with C code. These pragmas are also used in Ada Exaamples 21 to suppress a particular warning. Pragma Warnings is a GNAT extension. Non-GNAT usage could simply remove these pragmas with the resulting warnings ignored as they are benign.

Most of the GNAT dependencies can be found by searching the source code for "GNAT", "Unrestricted_Access and Pragma Warnings."

The GNAT dependence, though slight, will no doubt frustrate users of other Ada compilers. We welcome comments from those users, especially comments with specific suggestions on how to remove any GNAT-specific usages.

Sample command line project

It is instructive to present a simple example that can be compiled and run from the command line. Although this example is specific to one installation, it should be fairly straightforward to adapt it to another installation. Toward that end, it is helpful to understand the PLplot lingo of "build directory" and "installation directory."

Here is a simple program that will generate a plot of part of a parabola.

	procedure Simple_Example is
	   x, y : Real_Vector(-10 .. 10);
	   for i in x'range loop 
	      x(i) := Long_Float(i);
	      y(i) := x(i)**2;
	   end loop;
	   Initialize_PLplot; -- Call this only once.
	   Simple_Plot(x, y); -- Make the plot.
	   End_PLplot;        -- Call this only once.
	end Simple_Example;

Next is a bash script that will compile, bind, and link it. It is installation-specific in that paths to the GNAT compiler, PLplot libraries, and BLAS (Basic Linear Algebra System) and LAPACK (Linear Algebra Package) are hard-coded. You will have to adjust the paths to fit your installation. Some Linux installations which have GNAT 4.3 or later (Ada 2005) pre-installed might have already set the paths to the BLAS and LAPACK libraries.

(Note that the G.3 Annex of Ada 2005, in the GNAT version, depends heavily on BLAS and LAPACK. These packages are tried-and-true packages that are available from several places in either C or Fortran versions. The present example is specific to OS X which has both C and Fortran versions pre-installed.)

	/usr/local/ada-4.3/bin/gnatmake simple_example.adb \
	-aI/usr/local/plplot_build_dir/bindings/ada \
	-aL/usr/local/plplot_build_dir/bindings/ada/CMakeFiles/plplotadad.dir \
	-largs \
	/usr/local/plplot/lib/libplplotd.dylib \
	/Developer/SDKs/MacOSX10.4u.sdk/usr/lib/libblas.dylib \

The resulting binary program can be run by typing ./simple_example