The bindings will work for either Ada 95 or Ada 2005 but there is
a slightly subtle point regarding the use and declaration of vectors and
matrices. The package PLplot_Auxiliary
declares the
types
type Real_Vector is array (Integer range <>) of Long_Float; type Real_Matrix is array (Integer range <>, Integer range <>) of Long_Float;
These declarations mimic exactly the declarations described in
Annex G.3, Vector and Matrix Manipulation, of the Ada 2005 reference
manual when the generic package therein described is specialized for
Long_Float
. The reason for this approach is to avoid
requiring the user program to with
Ada.Numerics.Long_Real_Arrays
simply to gain access
to these types and in the process require linking to the BLAS and LAPACK
numerical libraries.
Ada 2005 introduced an annex G.3 which formally defines vector and
matrix support to Ada, along with some common mathematical operations on
those types. (This feature is a specific to vectors and matrices and
extends the usual array apparatus.) The Ada PLplot user has a choice on how
to deal with this. The default, as described in
PLplot_Auxiliary.ads
,
has Real_Vector
and Real_Matrix
declared therein, separate from the Ada 2005 declarations. This allows the
widest compatibility and does not require an Ada 2005 compiler. However,
many users will want to gain the benefit of the built-in declarations of
Ada 2005. This is easily done: Read the short comments in
PLplot_Auxiliary.ads
on how to comment-out two lines and
uncomment three lines. Either configuration will compile correctly, but
depending on the Cmake configuration to expose an Ada 2005 compiler in the later
case. (Note that at some points in the documentation, Ada 2005 is referred
to as Ada 2007, including some Cmake flags.)
This policy was changed in SVN version 11153. Before this, the type of compiler (Ada 95 or Ada 2005) had to be specified at the time that PLplot was built, and in the case of Ada 2005, the BLAS and LAPACK libraries had to be present and were subsequently linked.
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 interface with C code. These pragmas are also used in Ada Examples 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.
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.
with PLplot_Auxiliary, PLplot; use PLplot_Auxiliary, PLplot; procedure Simple_Example is x, y : Real_Vector(-10 .. 10); begin 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) preinstalled 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 preinstalled.)
#!/bin/bash /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 \ /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/liblapack.dylib
The resulting binary program can be run by typing ./simple_example