How to use the Ada bindings

Ada 95 versus Ada 2005

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 numerics libraries.

For users who wish to either attain compatibility with Ada 2005 Annex G.3 or to access its features which actually depend on BLAS and LAPACK, there are two routes. One is to build PLpot normally and then to edit PLplot_Auxiliary.ads as is indicated in that file. This is a very simple process requiring commenting two lines and uncommenting three lines. Then recompile only the Ada bindings and use the newly-created compiled files in the user project. The other way is to type-convert the Real_Vector and Real_Matrix objects in the user program so that they are compatible with the declarations of Annex G.3 when accessing the numerics functionality in that annex. (In GNAT, the relevant file is a-nlrear.ads.)

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.

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.


 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) 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.)


 #!/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