3.11.4.1 Running the binding generator

The binding generator is part of the `gcc' compiler and can be invoked via the `-fdump-ada-spec' switch, which will generate Ada spec files for the header files specified on the command line, and all header files needed by these files transitively. For example:

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

will generate, 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 will then compile in Ada 2005 mode these Ada specs.

The -C switch tells `gcc' to extract comments from headers, and will attempt to generate corresponding Ada comments.

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

You can optionally specify a parent unit, of which all generated units will be children, using -fada-spec-parent=``unit.

Note that we recommend when possible to use the `g++' driver to generate bindings, even for most C headers, since this will in general generate better Ada specs. For generating bindings for C++ headers, it is mandatory to use the `g++' command, or `gcc -x c++' which is equivalent in this case. If `g++' cannot work on your C headers because of incompatibilities between C and C++, then you can fallback to `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 a generic:

    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 some 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 need to first include stdio.h, so you can create a file with the following two lines in e.g. readline1.h:

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

and then generate Ada bindings from this file:

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