gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst

   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 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
  72 Interfacing to C++
  73 ==================
  74
  75 The interface to C++ makes use of the following pragmas, which are
  76 primarily intended to be constructed automatically using a binding generator
  77 tool, although it is possible to construct them by hand.
  78
  79 Using these pragmas it is possible to achieve complete
  80 inter-operability between Ada tagged types and C++ class definitions.
  81 See :ref:`Implementation_Defined_Pragmas`, for more details.
  82
  83 *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 *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
  98 A few restrictions are placed on the use of the `Access` attribute
  99 in conjunction with subprograms subject to convention `CPP`: the
 100 attribute may be used neither on primitive operations of a tagged
 101 record type with convention `CPP`, imported or not, nor on
 102 subprograms imported with pragma `CPP_Constructor`.
 103
 104 In addition, C++ exceptions are propagated and can be handled in an
 105 `others` choice of an exception handler. The corresponding Ada
 106 occurrence has no message, and the simple name of the exception identity
 107 contains ``Foreign_Exception``. Finalization and awaiting dependent
 108 tasks works properly when such foreign exceptions are propagated.
 109
 110 It 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
 121 The `External_Name` is the name of the C++ RTTI symbol. You can then
 122 cover a specific C++ exception in an exception handler.
 123
 124 .. _Interfacing_to_COBOL:
 125
 126 Interfacing to COBOL
 127 ====================
 128
 129 Interfacing to COBOL is achieved as described in section B.4 of
 130 the Ada Reference Manual.
 131
 132 .. _Interfacing_to_Fortran:
 133
 134 Interfacing to Fortran
 135 ======================
 136
 137 Interfacing to Fortran is achieved as described in section B.5 of the
 138 Ada Reference Manual.  The pragma `Convention Fortran`, applied to a
 139 multi-dimensional array causes the array to be stored in column-major
 140 order as required for convenient interface to Fortran.
 141
 142 .. _Interfacing_to_non-GNAT_Ada_code:
 143
 144 Interfacing to non-GNAT Ada code
 145 ================================
 146
 147 It is possible to specify the convention `Ada` in a pragma
 148 `Import` or pragma `Export`.  However this refers to
 149 the calling conventions used by GNAT, which may or may not be
 150 similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
 151 compiler to allow interoperation.
 152
 153 If arguments types are kept simple, and if the foreign compiler generally
 154 follows system calling conventions, then it may be possible to integrate
 155 files compiled by other Ada compilers, provided that the elaboration
 156 issues are adequately addressed (for example by eliminating the
 157 need for any load time elaboration).
 158
 159 In particular, GNAT running on VMS is designed to
 160 be highly compatible with the DEC Ada 83 compiler, so this is one
 161 case in which it is possible to import foreign units of this type,
 162 provided that the data items passed are restricted to simple scalar
 163 values or simple record types without variants, or simple array
 164 types with fixed bounds.
 165