Debian Codegraph @

gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst

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