With Praxis and AdaCore now teaming up to offer an integration of SPARK technology inside GPS (see http://www.adacore.com/home/products/sparkpro/), many GPS users will be interested in trying out the proof capabilities of SPARK on their own Ada programs. Of course it’s a little more involved than that. SPARK is not only a set of tools for verifying high-assurance systems, but also incorporates a language that must be learned.

The SPARK language is made up of two parts, one of which is a subset of Ada (whose features will obviously already be familiar to Ada programmers!), meant to facilitate code understanding and proofs, and the other part being a specification language, meant to express properties of programs. Quite conveniently, the SPARK specifications (a.k.a. SPARK annnotations, to distinguish them from Ada specifications) are expressed within stylized Ada comments of the following form:

         --# <some annotation here>

so SPARK annotations don’t interfere with normal Ada compilation.

This Gem and the next one demonstrate various of the properties you can prove with SPARK, and how these relate to the SPARK annotations written by the user. As a simple example, we will take a procedure which searches linearly for a value in an array, and returns the index, if any, at which the value is found.

Here is the specification file search.ads:

package Search is

  type IntArray is array (Integer range <>) of Integer;

  procedure Linear_Search
    (Table : in IntArray;
     Value : in Integer;
     Found : out Boolean;
     Index : out Integer);

end Search;

And the body file search.adb:

package body Search is

  procedure Linear_Search
    (Table : in IntArray;
     Value : in Integer;
     Found : out Boolean;
     Index : out Integer) 
  is
     I : Integer := 0;
  begin
     Found := False;

     while I <= Table’Last loop
        if Table(I) = Value then
           Found := True;
           Index := I;
           exit;
        end if;
        I := I + 1;
     end loop;
  end Linear_Search;

end Search;

Let’s first get set up for using SPARK:

1. Copy the files search.ads and search.adb into a directory named search.
2. Open GPS with a default project in the same directory.
3. Expand file search.adb.
4. Select SPARK/SPARKMake from the menu. This generates a file search.idx.
5. Copy the following code to a file called search.cfg:

  package Standard is
     type Integer is range -2**31 .. 2**31-1;
  end Standard;

6. From the Menu, select Project/Edit Project Properties.
7. Go to the page Switches/Examiner.
8. Select the following options:

  Index File            : search.idx
  Configuration File    : search.cfg
  Analysis              : Data Flow only
  Generate VCs          : yes (check it)

That’s it!

Now open search.adb and select SPARK/Examine File. The SPARK Examiner runs and outputs the following messages:

       Flow Error 602 - The undefined initial value of Index may be
                         used in the derivation of Index
       Warning 402 - Default assertion planted to cut the loop
       Note - Information flow analysis not carried out

The Flow Error indicates that, although Index is an out parameter, it is not initialized on all paths through Linear_Search. One could argue that our intent here is to access Index only when Found is set to True. SPARK considers initialization errors too serious to allow such subtleties, and requires that all paths through the procedure must initialize all out parameters. Let’s comply and initialize Index:

  begin
     Found := False;
     Index := 0;

After we rerun the Examiner, we are left with a Note that is simply a reminder of our choice of options, and a Warning that we will explain in the next Gem.

Now, we can continue with proving that our procedure is free from run-time errors, such as integer overflow and out-of-bounds array accesses. Select SPARK/Simplify All. The SPARK Simplifier runs. To see the result of this tool’s execution, select SPARK/POGS. This opens a file search.sum, which summarizes all the proofs in the following table:

VCs for procedure_linear_search :
--————————————————————————–
     |       |                     |  --—Proved In—–  |       |       |
#    | From  | To                  | vcg | siv | plg | prv | False | TO DO |
--————————————————————————–
1    | start | rtc check @ 13      |     | YES |     |     |       |       | 
2    | start |    assert @ 15      |     | YES |     |     |       |       | 
3    | 15    |    assert @ 15      |     | YES |     |     |       |       | 
4    | 15    | rtc check @ 16      |     |     |     |     |       |  YES  | 
5    | 15    | rtc check @ 18      |     | YES |     |     |       |       | 
6    | 15    | rtc check @ 21      |     |     |     |     |       |  YES  | 
7    | 15    |    assert @ finish  | YES |     |     |     |       |       | 
8    | 15    |    assert @ finish  | YES |     |     |     |       |       | 
--————————————————————————–

Each line corresponds to a Verification Condition (VC), which must be proved in order to guarantee that the program is free from run-time errors. Each column corresponds to the result of the proof attempt. If YES appears in one of the 4 “Proved In” columns, the proof was successful. If YES appears in the “False” column, there is something definitely wrong. If “YES” appears in the “TO DO” column, we don’t know: either the program is wrong, or it is too complex to prove.

Since column “TO DO” is not empty here, not all proofs were successful. In the next Gem, we will give you more details about failed proofs. The reason for the failures here is that program Linear_Search is incorrect, meaning that run-time errors can be raised. To see this, just complete the program with the following code in main.adb, and build the executable.

with Search;
use Search;

procedure Main is
   Table : IntArray(1..10) := (others => 0);
   Found : Boolean;
   Index : Integer;
begin
   Linear_Search(Table, 0, Found, Index);
end Main;

Now run the executable, and it raises an exception:

   raised CONSTRAINT_ERROR : search.adb:16 index check failed

This is because we are passing an array to Linear_Search that starts at index 1 in its parameter Table, whereas Linear_Search loop assumes that the array starts at index 0. SPARK correctly assumes that we can pass in such an array to Linear_Search, and thus it fails to prove that Linear_Search is free from run-time errors.

Let’s correct the code of Linear_Search:

  procedure Linear_Search
    (Table : in IntArray;
     Value : in Integer;
     Found : out Boolean;
     Index : out Integer) is
  begin
     Found := False;
     Index := 0;

     for I in Integer range Table’Range loop
        if Table(I) = Value then
           Found := True;
           Index := I;
            exit;
        end if;
     end loop;
  end Linear_Search;

Let’s do it again: Examine, Simplify All, POGS …
This time, columns “False” and “TO DO” are empty, meaning that all proofs were successful.

VCs for procedure_linear_search :
--————————————————————————–
     |       |                     |  --—Proved In—–  |       |       |
#    | From  | To                  | vcg | siv | plg | prv | False | TO DO |
--————————————————————————–
1    | start | rtc check @ 11      |     | YES |     |     |       |       | 
2    | start | rtc check @ 13      |     | YES |     |     |       |       | 
3    | start |    assert @ 13      |     | YES |     |     |       |       | 
4    | 13    |    assert @ 13      |     | YES |     |     |       |       | 
5    | 13    |    assert @ 13      |     | YES |     |     |       |       | 
6    | 13    | rtc check @ 14      |     | YES |     |     |       |       | 
7    | 13    | rtc check @ 16      |     | YES |     |     |       |       | 
8    | 13    |    assert @ finish  | YES |     |     |     |       |       | 
9    | 13    |    assert @ finish  | YES |     |     |     |       |       | 
--————————————————————————–

Thus, we have proved that procedure Linear_Search is free from run-time errors.

In the next Gem, after the summer break, we will prove that procedure Linear_Search actually respects a given contract.

When you open GPS initially, it shows a number of views: the Messages window (which can never be closed), the Project View, showing the list of files in your project, the Outline View, which shows the list of subprograms in the current edit, the Scenario View listing the scenario variables in your project, and a Welcome window to help you get started.

When several windows share the same screen area (which is the case for the project view and the outline view in the default desktop), they are organized into notebooks, and it’s possible to show any view by clicking on its associated tab. By default, GPS will now show the tabs if there is only one window in a given area, to save screen real estate. This behavior can be changed through the “Notebook Tabs Policy” preference. You can also change the location of the tabs (which by default appear below the window) through the “Notebook Tabs Position” preference. This latter preference configures the default location, though, and you can change it on a per-notebook basis by right-clicking in any of the tabs and changing the tabs position.

Windows can also be made to float. They are then put under the control of the operating system (or the window manager), and you can move them to another screen, another virtual desktop, iconify them, and so on. The window will have its own entry in your systems panel (the bar that is generally displayed at the bottom of the screen and shows all open windows). GPS has a mode where all windows it creates are made floating by default (this is the “All Floating” preference). When this mode is not activated, you can move a floating window back into GPS using one of two methods: the /Window/Floating menu, or by clicking on the [x] in the window’s title bar when the “Destroy Floating” preference is unset; at that point, instead of closing the window, GPS will simply put it back in its own window. If you really want to close it, you have to click a second time on [x].

Only one of the views has the focus at any given time, and it receives all keyboard input. Its title bar is then highlighted in a different color (which you configure in the preferences). To save some space on the screen, you could choose to hide the title bars. Indeed, it is obvious most of the time what each window is after you have used them a few times. The only case where you might be missing info is for editors (since the title bar includes the full name of the file). However, this name also appears in GPS’s own title bar. When the title bar is hidden, the notebook’s tab will be color highlighted to show the currently active window.

When a window is not currently visible on the screen (most often this will be when the Messages window is below the Locations window for instance), its tab is highlighted in a special color to bring attention to it and encourage you to check what has changed in that window.

It is rather obvious (or so we hope) that the views can be resized as you see fit simply by dragging the separators between those windows (that is, click on the separator, hold the mouse button, and move the mouse up/down or left/right, depending on the orientation of the separator). The resizing can take one of two forms: either a simple line overlaid on top of the windows to show where the separator will end up when you release the mouse, or by redrawing the windows each time you move the mouse. This behavior can also be configured in the preferences.

However, did you know that you can actually create any number of new areas on the desktop (which we call the MDI, for Multiple Document Interface)? This can be done in a number of ways. The easiest to discover is to use the menu /Window/Split Side-by-Side or /Window/Split Up-Down. For instance, assuming you have the default desktop loaded in GPS, select the project view. Then select the menu /Window/Split Up-Down. This will put the outline view in its own area below the project view, allowing you to see both at the same time.

However, the most flexible way to reorganize windows is by using drag and drop. Start by clicking on the title bar or the tab of any window. Then, without releasing the mouse button, move your mouse to where you would like to put the window you clicked on. Note how a pop-up window appears on top of the GPS window to describe what will happen when you release the mouse. There are six places where you can drop a window: if you release the mouse in the middle of an existing window, the two windows will be stacked into a notebook; if you release on any of the sides of an existing window (there is a margin a few pixels wide on each side), the existing window will be split and the window you are moving will be displayed next to it; finally, you can also release the mouse outside of the GPS window altogether to make the window floating.

As an additional bonus, if you press the shift key when you are dropping an editor window, a new view will be created (showing the same contents) instead of moving the initial editor. This allows you to view several locations in a given file, which is often useful when you want to view data structures when writing code, or when comparing several sections of code.

My own preferred organization (on a wide screen) is as follows: I have two editors side by side (for instance spec and body). Then on the left side I display the Windows view (/Tools/Views/Windows menu), which provides a fast way to select and bring to the front any window no matter where it currently is on the screen. This is a also a convenient place from which to start the drag-and-drop operations (clicking on a file and dropping it where I want to put the editor). Below this Windows view I have the Bookmarks view, which allows me to save places within any of the editors (through the /Edit/Create Bookmark menu), and come back to them later. Below the two editors, I display the Messages window and the Locations window side by side, so that I can see compilation errors easily, while keeping an eye on whether GPS has reported an error in its messages window. Finally, on the right-hand side of the screen I display the Outline view, since this is such a great way to move fast within a file, and the Tasks view that shows what’s being executed in the background (and provides a way to monitor the progress of compilations when using the -d switch to gnatmake). As you see, there are quite a number of views. To save space, I usually hide title bars (which as explained above are not necessary once you know what the windows are for), as well as the status bar at the bottom of the GPS window (since the task view displays the same information already).

Once you have found a layout that you like, however, you probably want to reuse it every time you open GPS. This is called saving the desktop. This process is very configurable, to adapt to the various needs that people might have:

- The default is for GPS to save the project-specific desktop. This means that the layout you have just created will be saved automatically on exit, and reapplied when loading the same project later on. If you load another project, the default layout will be used. One reason to do that is to save the currently opened files in the desktop (this is controlled by another preference, “Save Editor is Desktop”, where you decide whether you want to save editors or not, and if you do, whether only project-specific editors will be saved or any file that happens to be opened at that time.

- If you want to reuse the same layout for all projects on which you work, you should make sure the preference “General/Save Project-Specific Desktop on Exit” is disabled. This means that a single version of the desktop will be saved, and will apply to all projects (in this case it might be a good idea to remove the file $HOME/desktop.xml prior to launching GPS the first time, so that any trace of project-specific desktop is wiped out). In such a case, one of the drawbacks is that you might not want to save the editors since they would not necessarily match the next project you load.

The method I have been using is the following: after removing the desktop.xml file as described above, I launch GPS and set up the various views as I like, but do not open any editor. I then save the current desktop as the default through the menu /File/Save Move/Default Desktop. I then ensure that the preference to save project-specific desktops is on, as well as the preference to save the editors in the desktop. This ensures that every time I open a project that I’ve never opened before, I get the default desktop (with no editor), but when I open a project that I have already opened before, then I get the same editors (and in the same location) as the last time I exited GPS.

There are several ways in which the keyshortcuts can be changed in GPS.

One of the common cases is a user previously using the Emacs editor. GPS comes with a plug-in that will change the default key bindings in GPS. You just need to go to the /Tools/Plug-ins menu, and activate the “emacs.xml” plug-in. Note that for full compatibility with Emacs, you should also load some additional plug-ins (these are documented in the Description tab).

Similar plug-ins can be built for other editors, and shared with the rest of your team.

The most flexible method, however, is to go to the /Edit/Key Shortcuts menu. This will open a dialog in which you can configure shortcuts for any of the menus or any of the actions that GPS has created.

At this point, we should explain the difference between actions and menus. Internally, GPS exports its various features to the GUI as named actions. These actions are implemented either in Ada or using one of the scripting languages supported by GPS (python or XML for instance). They are organized into categories to make them easier to find. You can also create your own actions through XML files (see the GPS documentation for more details).

Most of the time, these actions are hidden and called in the background. But you can activate the “execute extended” plug-in if you want to be able to directly execute these commands by name, as Emacs does through its “M-x” key binding.

Some of these actions are then bound to menus or contextual menus.

Back to the Key Shortcuts editor. The main part of the dialog shows the list of actions exported by GPS. These are organized into categories. One of them is special, and is called “Menus”. It gives you access to all the menus of GPS (so some actions are accessible in two places, either by category/name, or by the menu). If you activate the “Flat List” button, the actions will instead be listed alphabetically and the categories will no longer be visible.

Next to each action or menu, GPS displays the shortcut associated with that action. One limitation here is that the shortcut is either shown next to the menu or next to the action (depending on how it was setup), but not both.

Here’s a small trick if you want to find out what a shortcut is bound to. You can click on both the “Flat List” and the “Shortcuts Only” buttons. This will list only those actions which currently have a shortcut associated. By clicking on the “Shortcut” column header, you can then sort the list by shortcut, thus making it easy to find out what a specific key shortcut does.

Through this dialog, you can change the shortcut for any of the actions. Simply select that action in the list, then press the “Grab” button, and you can then press the keyboard shortcut that you want to assign to it.

Key shortcuts are not limited to a single key (which on a standard keyboard would not provide enough shortcuts for those Emacs users). You can in fact have a series of shortcuts, as in “Control-x k”, which is used in Emacs to close the current window. Due to limitations in the gtk+ toolkit on which GPS is based, however, the menus are only able to display single shortcuts, so if you assign the above shortcut to a menu you can use the shortcut but it will not be visible in the menu itself.

Once you close the dialog with “OK”, the shortcut becomes effective immediately, and will be preserved from session to session. In fact, the key shortcuts you just created are saved in an XML file (keys.xml) in your $HOME/.gps directory. You can thus copy this file to other accounts or setups to automatically get the same shortcuts again.

GNAT allows for a great deal of flexibility in compiling applications. The traditional method is to use gnatmake on the command line, specifying the list of source directories by using “-I” switches, and letting gnatmake decide which files need to be recompiled. One drawback of this approach is that it only works for Ada files. If your application uses sources written in other languages (which is probably the case for the majority of serious applications), then you need some kind of wrapper around gnatmake. This is typically done via a Makefile: first you recompile C, C++, and other source files using standard Makefile techniques, then invoke gnatmake to handle the Ada sources, and finally (although this can also be done as part of gnatmake) bind and link your application.

Gnatmake is what we call a builder. Its role is to examine all source files in your application and decide which ones need to be recompiled. It then relies on other tools to do the actual compilation (gcc), bind (gnatbind) and link (gnatlink).

A few releases ago, a new tool called gprbuild was introduced in the GNAT technology. It is also a builder, reusing and extending gnatmake to support multilanguage applications. This means it knows how to handle C, C++, and many other languages, and is able to determine which source files for each language need to be recompiled. One benefit is that you no longer need to depend on a Makefile to compile those source files prior to binding and linking.

Gprbuild has been carefully designed so that no hard coding was done for any of the languages. Instead, all the information resides in a configuration file (typically having the extension “.cgpr”): how to compile a file, how to decide whether it is up to date, what files get generated as a result of the compilation, and so on.

These configuration files have a syntax similar to that of the project files themselves. They can be hand-edited as required, and maintained in your version control system as for any other component of the environment.

However, developing a configuration file is not always easy, especially when you are using different compiler chains (such as GNAT for Ada files and Diab for C). In particular, the link phase becomes harder to describe. Add to that support for multiple platforms, cross-compilation, libraries, and other subtleties, and the complexity increases quickly.

AdaCore has already taken care of a lot of possible compilers and combinations, so that you do not have to redo that complex setup yourself. We have created a knowledge base that describes the configuration for various common scenarios.

GNAT comes with an additional command-line tool, called gprconfig, which is generally spawned transparently by gprbuild, so you don’t have to invoke it directly in most cases. The role of gprconfig is to create the configuration file based on your specific set of compilers, getting information from the knowledge base.

Now that we’ve described the general organization of things, let’s show a concrete example.

Let’s assume your application is made up of two files, bar.adb and foo.c, with the following code (not very interesting, admittedly, since it will do exactly nothing):

procedure Bar is
   procedure Foo;
   pragma Import (C, Foo);
begin
   Foo;
end Bar;

int foo () {}

gprbuild only works with project files (there are no command-line options to specify source directories, for instance). So you need to write one. The basic elements of information you need to specify in a project file are: languages (C and Ada in our case), source directories and source files (implicit in our case), and main source files (bar.adb in our case). So the project file default.gpr looks like:

project Default is
   for Languages use ("C", "Ada");
   for Main use ("bar.adb");
end Default;

At this point everything is set up, and we can just spawn gprbuild with the command:

gprbuild -Pdefault

Since we did not specify a configuration file through a –config switch, gprbuild will automatically generate one by spawning gprconfig and telling it we want to find the first available Ada and C compilers on the PATH. Gprconfig will then create a configuration file called auto.cgpr, which gprbuild in turn uses to build our executable.

If you relaunch the same command again immediately, no recompilation takes place, not even for the C file.

Notice also how gprconfig selects the first matching compiler on the PATH for each language. If you want to force the use of specific compilers (that might not even be on your PATH), you will need to spawn gprconfig manually yourself and pass it a –config switch. This creates a configuration file which you can then pass along on your invocation of gprbuild.

In lots of legacy systems that were initially developed with technologies other than GNAT, a single source file might include several Ada units (or both spec and body of a single unit).

Where possible, it is best to follow GNAT’s traditional approach and split these files into several files. The main advantage this provides is to limit the amount of recompilation that gnatmake and gprbuild will do. When several units are found in the same file, modifying any of them will force recompilation of all files that depend on any of the units found in the file. In particular, changing the body of a unit when the spec is in the same source file will force recompilation of all units that depend on it. This is contrary to the whole concept of separate specifications.

This is also the recommended method in the Ada Quality and Style manual, so this should really be the preferred approach where possible.

Such splitting of source files can be done through the gnatchop command line tool. If you want to keep the original (multiple-unit) source files and keep modifying these, we recommend using the “-r” switch, which will force GNAT’s error messages to reference the original (unsplit) file.

If however you do not intend to keep them, you should not use “-r”.

Most likely the “-w” switch will also come in handy, to force overwriting of previously split files. Also, since you are recreating the source files that gnatmake sees, you should use the “-m” switch for gnatmake so that it doesn’t pay attention to timestamps. Otherwise you would end up recompiling all files all the time.

Calling gnatchop cannot be done automatically by gnatmake. Instead, you should have a script or a Makefile that first calls gnatchop, and then spawns gnatmake to do the actual compilation.

However, in some cases it isn’t possible to split the source files. Most often, this is because the files are under configuration control and you want to preserve history. In other cases, this is because you still want to compile with your older compiler.

GNAT provides a workaround in cases where you cannot split your source files and cannot or do not want to change your build methods to use gnatchop. Let us emphasize that this is really considered as only a workaround, and is not fully supported by all the tools. For instance, the “-gnatD” and “-gnatR” switches are currently not compatible with the pragmas described below. More important perhaps, GPS will have some known limitations when using multiple-unit source files (cross-references will not work in a lot of cases, and compiling the current file will fail if it contains multiple units)

You have to let GNAT know about your source-file organization, which can be done in several ways.

Method 1: If you are using project files, you can add or create a package Naming inside your project file, and use a syntax like:

 package Naming is
   for Specification ("unit1") use "file1.ada" at 1;
   for Implementation ("unit1") use "file1.ada" at 2;
 end Naming;

The index after the at starts at 1 and indicates the position of the unit inside the source file.

You can either create this Naming package manually by editing the project file, or else by using the gnatname command-line tool. This tool will traverse all the directories you pass it via its “-d” switch, check each file in them, and determine what unit or units they contain. It will then create a new project file called my_project_naming.gpr, and modify the project you specified on the command line in a manner similar to:

 with "my_project_naming";
 project My_Project is
    package Naming renames My_Project_Naming.Naming;
 end My_Project;

GPS was recently modified to properly support such project files, and properly preserve the existing “at” information when you edit a project, as well as to allow you to create new naming exceptions directly from the graphical interface.

Method 2: If you are not using project files yet, you can specify the same information by using pragmas in a configuration file. Through its “-c” switch, gnatname is also able to generate this file of pragmas. The general form of the configuration file is:

 pragma Source_File_Name
   (Unit1, Spec_File_Name => "file1.ada", Index => 1);
 pragma Source_File_Name
   (Unit1, Body_File_Name => "file1.ada", Index => 2);

where the information is similar to what was specified in the project file example above.

There is a difference between using these project attributes or pragmas, and using “gnatchop -r” as we described in the first part: while there is a single command to spawn, and no duplication of source files with the pragmas, you still have the issue that gnatmake will recompile everything that depends on any unit in the file. When using gnatchop, however, that problem does not exist, because gnatmake sees single-unit source files. Also, the pragma-based method is not fully supported by all the tools yet, so the preferred approach is really to split your files (and preferably replace the multiple-unit source files with the resulting single-unit files).

One of Ada’s key strengths has always been its strong typing. The language imposes stringent checking of type and subtype properties to help prevent accidental violations of the type system that are a common source of program bugs in other less-strict languages such as C. This is done using a combination of compile-time restrictions (legality rules), that prohibit mixing values of different types, together with run-time checks to catch violations of various dynamic properties. Examples are checking values against subtype constraints and preventing dereferences of null access values.

At the same time, Ada does provide certain “loophole” features, such as Unchecked_Conversion, that allow selective bypassing of the normal safety features, which is sometimes necessary when interfacing with hardware or code written in other languages.

Ada also permits explicit suppression of the run-time checks that are there to ensure that various properties of objects are not violated. This suppression can be done using pragma Suppress, as well as by using a compile-time switch on most implementations (in the case of GNAT, with the -gnatp switch).

In addition to allowing all checks to be suppressed, Pragma Suppress supports suppression of specific forms of check, such as Index_Check for array indexing, Range_Check for scalar bounds checking, and Access_Check for dereferencing of access values. (See section 11.5 of the Ada Reference Manual for further details.)

Here’s a simple example of suppressing index checks within a specific subprogram:

  procedure Main is
     procedure Sort_Array (A : in out Some_Array) is
        pragma Suppress (Index_Check);  — eliminate check overhead
     begin
        …
     end Sort_Array; 
  end Main;

Unlike a feature such as Unchecked_Conversion, however, the purpose of check suppression is not to enable programs to subvert the type system, though many programmers seem to have that misconception.

What’s important to understand about pragma Suppress is that it only gives permission to the implementation to remove checks, but doesn’t require such elimination. The intention of Suppress is not to allow bypassing of Ada semantics, but rather to improve efficiency, and the Ada Reference Manual has a clear statement to that effect in the note in RM-11.5, paragraph 29:

There is no guarantee that a suppressed check is actually removed; hence a pragma Suppress should be used only for efficiency reasons.

There is associated Implementation Advice that recommends that implementations should minimize the code executed for checks that have been suppressed, but it’s still the responsibility of the programmer to ensure that the correct functioning of the program doesn’t depend on checks not being performed.

There are various reasons why a compiler might choose not to remove a check. On some hardware, certain checks may be essentially free, such as null pointer checks or arithmetic overflow, and it might be impractical or add extra cost to suppress the check. Another example where it wouldn’t make sense to remove checks is for an operation implemented by a call to a run-time routine, where the check might be only a small part of a more expensive operation done out of line.

Furthermore, in many cases GNAT can determine at compile time that a given run-time check is guaranteed to be violated. In such situations, it gives a warning that an exception will be raised, and generates code specifically to raise the exception. Here’s an example:

   X : Integer range 1..10 := …;

   ..

   if A > B then
      X := X + 1;
      ..
   end if;

For the assignment incrementing X, the compiler will normally generate machine code equivalent to:

   Temp := X + 1;
   if Temp > 10 then
      raise Constraint_Error;
   end if;
   X := Temp;

If range checks are suppressed, then the compiler can just generate the increment and assignment. However, if the compiler is able to somehow prove that X = 10 at this point, it will issue a warning, and replace the entire assignment with simply:

   raise Constraint_Error;

even though checks are suppressed. This is appropriate, because (1) we don’t care about the efficiency of buggy code, and (2) there is no “extra” cost to the check, because if we reach that point, the code will unconditionally fail.

One other important thing to note about checks and pragma Suppress is this statement in the Ada RM (RM-11.5, paragraph 26):

If a given check has been suppressed, and the corresponding error situation occurs, the execution of the program is erroneous.

In Ada, erroneous execution is a bad situation to be in, because it means that the execution of your program could have arbitrary nasty effects, such as unintended overwriting of memory. Note also that a program whose “correct” execution somehow depends on a given check being suppressed might work as the programmer expects, but could still fail when compiled with a different compiler, or for a different target, or even with a newer version of the same compiler. Other changes such as switching on optimization or making a change to a totally unrelated part of the code could also cause the code to start failing.

So it’s definitely not wise to write code that relies on checks being removed. In fact, it really only makes sense to suppress checks once there’s good reason to believe that the checks can’t fail, as a result of testing or other analysis. Otherwise, you’re removing an important safety feature of Ada that’s intended to help catch bugs.

Continuing from the example discussed in the last Gem, let’s derive the imported C++ class on the Ada side. For example:

 type DT is limited new Root with record
    C_Value : Natural := 2009;
 end record;

In this case, the components DT inherited from the C++ side must be initialized by a C++ constructor, and the additional Ada components of type DT are initialized by GNAT. The initialization of such an object is done either by default, or by means of a function returning an aggregate of type DT, or by means of an extension aggregate:

 Obj5 : DT;
 Obj6 : DT := Function_Returning_DT (50);
 Obj7 : DT := (New_Root (30, 40) with C_Value => 50);

The declaration of Obj5 invokes the default constructors: the C++ default constructor of the parent type takes care of the initialization of the components inherited from Root, and GNAT takes care of the default initialization of the additional Ada components of type DT (that is, C_Value is initialized to value 2009). The order of invocation of the constructors is consistent with the order of elaboration required by Ada and C++, meaning that the constructor of the parent type is always called before the constructor of the derived type.

Let’s now consider a record that has components whose type is imported from C++. For example:

 type Rec1 is limited record
    Data1 : Root := New_Root (10);
    Value : Natural := 1000;
 end record;

 type Rec2 (D : Integer := 20) is limited record
    Rec   : Rec1;
    Data2 : Root := New_Root (D, 30);
 end record;

The initialization of an object of type Rec2 will call the nondefault C++ constructors specified for the imported components. For example:

 Obj8 : Rec2 (40);

Using Ada 2005 we can use limited aggregates to initialize an object invoking C++ constructors that differ from those specified in the type declarations. For example:

 Obj9 : Rec2 := (Rec => (Data1 => New_Root (15, 16),
                         others => <>),
                 others => <>);

The above declaration uses an Ada 2005 limited aggregate to initialize Obj9, and the C++ constructor that has two integer arguments is invoked to initialize the Data1 component instead of the constructor specified in the declaration of type Rec1. In Ada 2005, the box in the aggregate indicates that unspecified components are initialized using the expression (if any) available in the component declaration. That is, in this case discriminant D is initialized to value 20, Value is initialized to value 1000, and the non-default C++ constructor that handles two integers takes care of initializing component Data2 with values 20 and 30.

In Ada 2005, we can use the extended return statement to build the Ada equivalent of a C++ nondefault constructor. For example:

 function New_Rec2 (V : Integer) return Rec2 is
 begin
    return Obj : Rec2 := (Rec => (Data1  => New_Root (V, 20),
                                  others => <>),
                          others => <>) do
       --  Further actions required for construction of
       --  objects of type Rec2
       …
    end record;
 end New_Rec2;

In this example, the extended return statement construct is used to build in place the returned object, whose components are initialized by means of a limited aggregate. Any further actions associated with the constructor can be given within the statement part of the extended return.

Let’s assume that we need to interface with the following C++ class:

class Root {
public:
   int  a_value;
   int  b_value;
   virtual int Get_Value ();
   Root();              // Default constructor
   Root(int v);         // 1st non-default constructor
   Root(int v, int w);  // 2nd non-default constructor
};

Using the automatic binding generator, or writing manually, we can obtain the corresponding package spec:

with Interfaces.C; use Interfaces.C;
package Pkg_Root is

   type Root is tagged limited record
       A_Value : int;
       B_Value : int;
   end record;
   pragma Import (CPP, Root);

   function Get_Value (Obj : Root) return int;
   pragma Import (CPP, Get_Value);

   function New_Root return Root’Class;
   pragma Cpp_Constructor (New_Root, "_ZN4RootC1Ev");

   function New_Root (v : int) return Root’Class;
   pragma Cpp_Constructor (New_Root, "_ZN4RootC1Ei");

   function New_Root (v, w : int) return Root’Class;
   pragma Cpp_Constructor (New_Root, "_ZN4RootC1Eii");

end Pkg_Root;

On the Ada side, the constructor is represented by a function (whose name is arbitrary) that returns the class-wide type corresponding to the imported C++ class. The return type is required to be class-wide rather than the specific Root type so that the function will not be treated as a primitive dispatching operation of the type. Although the constructor is described as a function, it is typically a procedure with an extra implicit argument (the object being initialized) at the implementation level. GNAT issues the appropriate call, whatever it is, to initialize the object.

Constructors can appear in the following contexts:

- As the initialization expression of an object of type T
- As the initialization expression of a record component of type T
- In a limited aggregate
- In a limited aggregate used as the expression of a return statement

Note that all of the above contexts are places where Ada 2005 allows limited aggregates and calls to functions with limited results to appear, and in fact it’s necessary to enable the Ada 2005 compilation mode (-gnat05) to make use of this feature.

In a declaration of an object whose type is a class imported from C++, either the default C++ constructor is implicitly called by GNAT, or else the required C++ constructor must be explicitly called in the expression that initializes the object. For example:

 Obj1 : Root;
 Obj2 : Root := New_Root;
 Obj3 : Root := New_Root (v => 10);
 Obj4 : Root := New_Root (30, 40);

The first two declarations are equivalent: in both cases, the default C++ constructor is invoked (in the former case the call to the constructor is implicit, and in the latter case the call is explicit in the object declaration). Obj3 is initialized by the C++ nondefault constructor that takes an integer argument, and Obj4 is initialized by the nondefault C++ constructor that takes two integers.

It’s worth pointing out that normally it’s not permitted to call a class-wide function to initialize an object of a specific type, and it’s only in the case of these special imported constructor functions that the compiler allows this usage.

In the next Gem we will explore how to derive and extend imported C++ classes on the Ada side, and show uses of constructors in Ada 2005 extended return and limited aggregates.

Generating bindings for C++ headers is done using the same options as for C headers, again using the G++ driver. This is because the binding generation tool takes advantage of the full C and C++ front ends readily available with GCC, and then translates its internal representation into corresponding Ada code.

In this mode, C++ classes will be mapped to Ada tagged types, constructors will be mapped using the CPP_Constructor pragma, and, when possible, multiple inheritance of abstract classes will be mapped to Ada interfaces.

A complete example

For example, given the following C++ header file called animals.h:

class Carnivore {
public:
  virtual int Number_Of_Teeth () = 0;
};

class Domestic {
public:
  virtual void Set_Owner (char* Name) = 0;
};

class Animal {
public:
  int Age_Count;
  virtual void Set_Age (int New_Age);
};

class Dog : Animal, Carnivore, Domestic {
public:
  int Tooth_Count;
  char *Owner;

  virtual int  Number_Of_Teeth ();
  virtual void Set_Owner (char* Name);

  Dog();
};

We generate an Ada package with:

$ g++ -c -fdump-ada-spec animals.h

which generates a file animals_h.ads that has the following contents:

package animals_h is

   package Class_Carnivore is
     type Carnivore is limited interface;
     pragma Import (CPP, Carnivore);

     function Number_Of_Teeth (this : access Carnivore) return int is abstract;
   end;
   use Class_Carnivore;

   package Class_Domestic is
     type Domestic is limited interface;
     pragma Import (CPP, Domestic);

     procedure Set_Owner
       (this : access Domestic;
        Name : Interfaces.C.Strings.chars_ptr) is abstract;
   end;
   use Class_Domestic;

   package Class_Animal is
     type Animal is tagged limited record
       Age_Count : aliased int;
     end record;
     pragma Import (CPP, Animal);

     procedure Set_Age (this : access Animal; New_Age : int);
     pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
   end;
   use Class_Animal;

   package Class_Dog is
     type Dog is new Animal and Carnivore and Domestic with record
       Tooth_Count : aliased int;
       Owner : Interfaces.C.Strings.chars_ptr;
     end record;
     pragma Import (CPP, Dog);

     function Number_Of_Teeth (this : access Dog) return int;
     pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");

     procedure Set_Owner
       (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
     pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");

     function New_Dog return Dog'Class;
     pragma CPP_Constructor (New_Dog, "_ZN3DogC1Ev");
   end;
   use Class_Dog;

end animals_h;

As you can see, C++ classes are mapped to Ada tagged types and even interfaces when possible. Another advantage of directly using the C++ compiler to generate bindings is that the information about C++ mangling is readily available and can be generated easily, while writing it manually can be tedious and error prone.

The C++ mangling is the low-level name chosen by the C++ compiler for a given function, such as “_ZN3Dog9Set_OwnerEPc” in the case of procedure Class_Dog.Set_Owner in the example above.

In the next Gem, we will explore in more detail how the CPP_Constructor pragma works and how to combine it with Ada features.

GNAT now comes with a new experimental binding generator for C and C++ headers which is intended to do 95% of the tedious work of generating Ada specs from C or C++ header files. Note that this is still a work in progress, not designed to generate 100% correct Ada specs.

The code generated uses the Ada 2005 syntax, making it easier to interface with other languages than did previous versions of Ada, in particular via the generation of limited with clauses and anonymous access types.

In this Gem, we will focus on the generation of C bindings. Bindings to C++ will be addressed in a future Gem.

Running the binding generator

The binding generator is part of the GCC compiler that comes with recent versions of GNAT and can be invoked via the -fdump-ada-spec switch, which generates Ada spec files for the header files specified on the command line, and all header files needed by these files transitivitely. For example:

$ g++ -c -fdump-ada-spec -C /usr/include/time.h
$ gcc -c -gnat05 *.ads

generates, under GNU/Linux, the following files: time_h.ads, bits_time_h.ads, stddef_h.ads, bits_types_h.ads, which correspond to the files /usr/include/time.h, /usr/include/bits/time.h, etc…, and then compiles these Ada specs in Ada 2005 mode.

The -C switch tells GCC to extract comments from headers and attempt to generate corresponding Ada comments.

If you want to generate a single Ada file and not the transitive closure, you can use the -fdump-ada-spec-slim switch instead.

Note that we recommend, where possible, to use the G++ driver to generate bindings, even for most C headers, since this will in general generate better Ada specs. If G++ doesn’t work on your C headers because of incompatibilities between C and C++, then you can fall back on using GCC instead.

For an example of better bindings generated from the C++ front end, the name of the parameters (when available) are actually ignored by the C front end. Consider the following C header:

extern void foo (int variable);

With the C front end, “variable” is ignored, and the above is handled as:

extern void foo (int);

generating the following subprogram specification:

procedure foo (param1 : int);

With the C++ front end, the name is available, and we generate:

procedure foo (variable : int);

In some cases, the generated bindings will be more complete or more meaningful when defining macros, which you can do via the -D switch. This is for example the case with Xlib.h under GNU/Linux:

g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h

The above will generate more complete bindings than a straight call without the -DXLIB_ILLEGAL_ACCESS switch.

In other cases, it is not possible to parse a header file in a stand-alone manner, because other include files need to be included first. In this case, the solution is to create a small header file including the needed #include and possible #define directives. For example, to generate Ada bindings for readline/readline.h, you first need to include stdio.h, so you can create a file with the following two lines in, for example, readline1.h:

#include <stdio.h>
#include <readline/readline.h>

and then generate Ada bindings from this file:

$ g++ -c -fdump-ada-spec readline1.h

In a future Gem we will talk about generating similar Ada bindings for C++ headers.