* Stack Related Facilities::
* Verifying Properties Using gnatcheck::
* Creating Sample Bodies Using gnatstub::
+* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
* Running and Debugging Ada Programs::
@ifclear vms
a utility that generates empty but compilable bodies for library units.
@item
+@ref{Generating Ada Bindings for C and C++ headers}, describes how to
+generate automatically Ada bindings from C and C++ headers.
+
+@item
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
@item -fno-inline-functions
@cindex @option{-fno-inline-functions} (@command{gcc})
-Suppresses automatic inlining of small subprograms, which is enabled
+Suppresses automatic inlining of simple subprograms, which is enabled
if @option{-O3} is used.
+@item -fno-inline-small-functions
+@cindex @option{-fno-inline-small-functions} (@command{gcc})
+Suppresses automatic inlining of small subprograms, which is enabled
+if @option{-O2} is used.
+
@item -fno-inline-functions-called-once
@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
Suppresses inlining of subprograms local to the unit and called once
time you compile, regarding the source files that it writes as temporary
files that you throw away.
+Note that if your file containing multiple units starts with a byte order
+mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
+will each start with a copy of this BOM, meaning that they can be compiled
+automatically in UTF-8 mode without needing to specify an explicit encoding.
+
@node Operating gnatchop in Compilation Mode
@section Operating gnatchop in Compilation Mode
The @code{gnatmem} utility monitors dynamic allocation and
deallocation activity in a program, and displays information about
incorrect deallocations and possible sources of memory leaks.
-It provides three type of information:
+It is designed to work in association with a static runtime library
+only and in this context provides three types of information:
@itemize @bullet
@item
General information concerning memory management, such as the total
the source search path when calling @command{gnatstub}, see the description
of @command{gnatstub} switches below.
+By default, all the program unit body stubs generated by @code{gnatstub}
+raise the predefined @code{Program_Error} exception, which will catch
+accidental calls of generated stubs. This behavior can be changed with
+option @option{^--no-exception^/NO_EXCEPTION^} (see below).
+
@menu
* Running gnatstub::
* Switches for gnatstub::
@cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub})
Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}}
-@item ^-o^/BODY=^@var{body-name}
+@item ^--no-exception^/NO_EXCEPTION^
+@cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub})
+Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
+This is not always possible for function stubs.
+
+@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
follow
@end table
+@c *********************************
+@node Generating Ada Bindings for C and C++ headers
+@chapter Generating Ada Bindings for C and C++ headers
+@findex binding
+
+@noindent
+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 still is a work in
+progress, not designed to generate 100% correct Ada specs.
+
+The code generated is using the Ada 2005 syntax, which makes it
+easier to interface with other languages than previous versions of Ada.
+
+@menu
+* Running the binding generator::
+* Generating bindings for C++ headers::
+* Switches::
+@end menu
+
+@node Running the binding generator
+@section Running the binding generator
+
+@noindent
+The binding generator is part of the @command{gcc} compiler and can be
+invoked via the @option{-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 transitivitely. For example:
+
+@smallexample
+$ g++ -c -fdump-ada-spec -C /usr/include/time.h
+$ gcc -c -gnat05 *.ads
+@end smallexample
+
+will generate, under GNU/Linux, the following files: @file{time_h.ads},
+@file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which
+correspond to the files @file{/usr/include/time.h},
+@file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005
+mode these Ada specs.
+
+The @code{-C} switch tells @command{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 @option{-fdump-ada-spec-slim} switch.
+
+Note that we recommend when possible to use the @command{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 @command{g++} command, or @command{gcc -x c++} which
+is equivalent in this case. If @command{g++} cannot work on your C headers
+because of incompatibilities between C and C++, then you can fallback to
+@command{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:
+
+@smallexample
+extern void foo (int variable);
+@end smallexample
+
+with the C front-end, @code{variable} is ignored, and the above is handled as:
+
+@smallexample
+extern void foo (int);
+@end smallexample
+
+generating a generic:
+
+@smallexample
+procedure foo (param1 : int);
+@end smallexample
+
+with the C++ front-end, the name is available, and we generate:
+
+@smallexample
+procedure foo (variable : int);
+@end smallexample
+
+In some cases, the generated bindings will be more complete or more meaningful
+when defining some macros, which you can do via the @option{-D} switch. This
+is for example the case with @file{Xlib.h} under GNU/Linux:
+
+@smallexample
+g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
+@end smallexample
+
+The above will generate more complete bindings than a straight call without
+the @option{-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
+@code{#include} and possible @code{#define} directives. For example, to
+generate Ada bindings for @file{readline/readline.h}, you need to first
+include @file{stdio.h}, so you can create a file with the following two
+lines in e.g. @file{readline1.h}:
+
+@smallexample
+#include <stdio.h>
+#include <readline/readline.h>
+@end smallexample
+
+and then generate Ada bindings from this file:
+
+@smallexample
+$ g++ -c -fdump-ada-spec readline1.h
+@end smallexample
+
+@node Generating bindings for C++ headers
+@section Generating bindings for C++ headers
+
+@noindent
+Generating bindings for C++ headers is done using the same options, always
+with the @command{g++} compiler.
+
+In this mode, C++ classes will be mapped to Ada tagged types, constructors
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
+multiple inheritance of abstract classes will be mapped to Ada interfaces
+(@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional
+information on interfacing to C++).
+
+For example, given the following C++ header file:
+
+@smallexample
+@group
+@cartouche
+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();
+@};
+@end cartouche
+@end group
+@end smallexample
+
+The corresponding Ada code is generated:
+
+@smallexample @c ada
+@group
+@cartouche
+ 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);
+ pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
+ end;
+ use Class_Dog;
+@end cartouche
+@end group
+@end smallexample
+
+@node Switches
+@section Switches
+
+@table @option
+@item -fdump-ada-spec
+@cindex @option{-fdump-ada-spec} (@command{gcc})
+Generate Ada spec files for the given header files transitively (including
+all header files that these headers depend upon).
+
+@item -fdump-ada-spec-slim
+@cindex @option{-fdump-ada-spec-slim} (@command{gcc})
+Generate Ada spec files for the header files specified on the command line
+only.
+
+@item -C
+@cindex @option{-C} (@command{gcc})
+Extract comments from headers and generate Ada comments in the Ada spec files.
+@end table
+
@node Other Utility Programs
@chapter Other Utility Programs
OSDN Git Service
