1.. _Interfacing_to_Other_Languages:
2
3******************************
4Interfacing to Other Languages
5******************************
6
7The facilities in Annex B of the Ada Reference Manual are fully
8implemented in GNAT, and in addition, a full interface to C++ is
9provided.
10
11.. _Interfacing_to_C:
12
13Interfacing to C
14================
15
16Interfacing to C with GNAT can use one of two approaches:
17
18*
19  The types in the package ``Interfaces.C`` may be used.
20*
21  Standard Ada types may be used directly.  This may be less portable to
22  other compilers, but will work on all GNAT compilers, which guarantee
23  correspondence between the C and Ada types.
24
25Pragma ``Convention C`` may be applied to Ada types, but mostly has no
26effect, since this is the default.  The following table shows the
27correspondence between Ada scalar types and the corresponding C types.
28
29
30======================== ==================================================================
31Ada Type                 C Type
32======================== ==================================================================
33``Integer``              ``int``
34``Short_Integer``        ``short``
35``Short_Short_Integer``  ``signed char``
36``Long_Integer``         ``long``
37``Long_Long_Integer``    ``long long``
38``Short_Float``          ``float``
39``Float``                ``float``
40``Long_Float``           ``double``
41``Long_Long_Float``      This is the longest floating-point type supported by the hardware.
42======================== ==================================================================
43
44Additionally, there are the following general correspondences between Ada
45and C types:
46
47*
48  Ada enumeration types map to C enumeration types directly if pragma
49  ``Convention C`` is specified, which causes them to have int
50  length.  Without pragma ``Convention C``, Ada enumeration types map to
51  8, 16, or 32 bits (i.e., C types ``signed char``, ``short``,
52  ``int``, respectively) depending on the number of values passed.
53  This is the only case in which pragma ``Convention C`` affects the
54  representation of an Ada type.
55
56*
57  Ada access types map to C pointers, except for the case of pointers to
58  unconstrained types in Ada, which have no direct C equivalent.
59
60*
61  Ada arrays map directly to C arrays.
62
63*
64  Ada records map directly to C structures.
65
66*
67  Packed Ada records map to C structures where all members are bit fields
68  of the length corresponding to the ``type'Size`` value in Ada.
69
70.. _Interfacing_to_C++:
71
72Interfacing to C++
73==================
74
75The interface to C++ makes use of the following pragmas, which are
76primarily intended to be constructed automatically using a binding generator
77tool, although it is possible to construct them by hand.
78
79Using these pragmas it is possible to achieve complete
80inter-operability between Ada tagged types and C++ class definitions.
81See :ref:`Implementation_Defined_Pragmas`, for more details.
82
83:samp:`pragma CPP_Class ([Entity =>] {LOCAL_NAME})`
84  The argument denotes an entity in the current declarative region that is
85  declared as a tagged or untagged record type. It indicates that the type
86  corresponds to an externally declared C++ class type, and is to be laid
87  out the same way that C++ would lay out the type.
88
89  Note: Pragma ``CPP_Class`` is currently obsolete. It is supported
90  for backward compatibility but its functionality is available
91  using pragma ``Import`` with ``Convention`` = ``CPP``.
92
93
94:samp:`pragma CPP_Constructor ([Entity =>] {LOCAL_NAME})`
95  This pragma identifies an imported function (imported in the usual way
96  with pragma ``Import``) as corresponding to a C++ constructor.
97
98A few restrictions are placed on the use of the ``Access`` attribute
99in conjunction with subprograms subject to convention ``CPP``: the
100attribute may be used neither on primitive operations of a tagged
101record type with convention ``CPP``, imported or not, nor on
102subprograms imported with pragma ``CPP_Constructor``.
103
104In addition, C++ exceptions are propagated and can be handled in an
105``others`` choice of an exception handler. The corresponding Ada
106occurrence has no message, and the simple name of the exception identity
107contains ``Foreign_Exception``. Finalization and awaiting dependent
108tasks works properly when such foreign exceptions are propagated.
109
110It is also possible to import a C++ exception using the following syntax:
111
112
113::
114
115  LOCAL_NAME : exception;
116  pragma Import (Cpp,
117    [Entity =>] LOCAL_NAME,
118    [External_Name =>] static_string_EXPRESSION);
119
120
121The ``External_Name`` is the name of the C++ RTTI symbol. You can then
122cover a specific C++ exception in an exception handler.
123
124.. _Interfacing_to_COBOL:
125
126Interfacing to COBOL
127====================
128
129Interfacing to COBOL is achieved as described in section B.4 of
130the Ada Reference Manual.
131
132.. _Interfacing_to_Fortran:
133
134Interfacing to Fortran
135======================
136
137Interfacing to Fortran is achieved as described in section B.5 of the
138Ada Reference Manual.  The pragma ``Convention Fortran``, applied to a
139multi-dimensional array causes the array to be stored in column-major
140order as required for convenient interface to Fortran.
141
142.. _Interfacing_to_non-GNAT_Ada_code:
143
144Interfacing to non-GNAT Ada code
145================================
146
147It is possible to specify the convention ``Ada`` in a pragma
148``Import`` or pragma ``Export``.  However this refers to
149the calling conventions used by GNAT, which may or may not be
150similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
151compiler to allow interoperation.
152
153If arguments types are kept simple, and if the foreign compiler generally
154follows system calling conventions, then it may be possible to integrate
155files compiled by other Ada compilers, provided that the elaboration
156issues are adequately addressed (for example by eliminating the
157need for any load time elaboration).
158
159In particular, GNAT running on VMS is designed to
160be highly compatible with the DEC Ada 83 compiler, so this is one
161case in which it is possible to import foreign units of this type,
162provided that the data items passed are restricted to simple scalar
163values or simple record types without variants, or simple array
164types with fixed bounds.
165