gcc/doc/compat.texi

   1 @c Copyright (C) 2002-2021 Free Software Foundation, Inc.
   2 @c This is part of the GCC manual.
   3 @c For copying conditions, see the file gcc.texi.
   4
   5 @node Compatibility
   6 @chapter Binary Compatibility
   7 @cindex binary compatibility
   8 @cindex ABI
   9 @cindex application binary interface
  10
  11 Binary compatibility encompasses several related concepts:
  12
  13 @table @dfn
  14 @item application binary interface (ABI)
  15 The set of runtime conventions followed by all of the tools that deal
  16 with binary representations of a program, including compilers, assemblers,
  17 linkers, and language runtime support.
  18 Some ABIs are formal with a written specification, possibly designed
  19 by multiple interested parties.  Others are simply the way things are
  20 actually done by a particular set of tools.
  21
  22 @item ABI conformance
  23 A compiler conforms to an ABI if it generates code that follows all of
  24 the specifications enumerated by that ABI@.
  25 A library conforms to an ABI if it is implemented according to that ABI@.
  26 An application conforms to an ABI if it is built using tools that conform
  27 to that ABI and does not contain source code that specifically changes
  28 behavior specified by the ABI@.
  29
  30 @item calling conventions
  31 Calling conventions are a subset of an ABI that specify of how arguments
  32 are passed and function results are returned.
  33
  34 @item interoperability
  35 Different sets of tools are interoperable if they generate files that
  36 can be used in the same program.  The set of tools includes compilers,
  37 assemblers, linkers, libraries, header files, startup files, and debuggers.
  38 Binaries produced by different sets of tools are not interoperable unless
  39 they implement the same ABI@.  This applies to different versions of the
  40 same tools as well as tools from different vendors.
  41
  42 @item intercallability
  43 Whether a function in a binary built by one set of tools can call a
  44 function in a binary built by a different set of tools is a subset
  45 of interoperability.
  46
  47 @item implementation-defined features
  48 Language standards include lists of implementation-defined features whose
  49 behavior can vary from one implementation to another.  Some of these
  50 features are normally covered by a platform's ABI and others are not.
  51 The features that are not covered by an ABI generally affect how a
  52 program behaves, but not intercallability.
  53
  54 @item compatibility
  55 Conformance to the same ABI and the same behavior of implementation-defined
  56 features are both relevant for compatibility.
  57 @end table
  58
  59 The application binary interface implemented by a C or C++ compiler
  60 affects code generation and runtime support for:
  61
  62 @itemize @bullet
  63 @item
  64 size and alignment of data types
  65 @item
  66 layout of structured types
  67 @item
  68 calling conventions
  69 @item
  70 register usage conventions
  71 @item
  72 interfaces for runtime arithmetic support
  73 @item
  74 object file formats
  75 @end itemize
  76
  77 In addition, the application binary interface implemented by a C++ compiler
  78 affects code generation and runtime support for:
  79 @itemize @bullet
  80 @item
  81 name mangling
  82 @item
  83 exception handling
  84 @item
  85 invoking constructors and destructors
  86 @item
  87 layout, alignment, and padding of classes
  88 @item
  89 layout and alignment of virtual tables
  90 @end itemize
  91
  92 Some GCC compilation options cause the compiler to generate code that
  93 does not conform to the platform's default ABI@.  Other options cause
  94 different program behavior for implementation-defined features that are
  95 not covered by an ABI@.  These options are provided for consistency with
  96 other compilers that do not follow the platform's default ABI or the
  97 usual behavior of implementation-defined features for the platform.
  98 Be very careful about using such options.
  99
 100 Most platforms have a well-defined ABI that covers C code, but ABIs
 101 that cover C++ functionality are not yet common.
 102
 103 Starting with GCC 3.2, GCC binary conventions for C++ are based on a
 104 written, vendor-neutral C++ ABI that was designed to be specific to
 105 64-bit Itanium but also includes generic specifications that apply to
 106 any platform.
 107 This C++ ABI is also implemented by other compiler vendors on some
 108 platforms, notably GNU/Linux and BSD systems.
 109 We have tried hard to provide a stable ABI that will be compatible with
 110 future GCC releases, but it is possible that we will encounter problems
 111 that make this difficult.  Such problems could include different
 112 interpretations of the C++ ABI by different vendors, bugs in the ABI, or
 113 bugs in the implementation of the ABI in different compilers.
 114 GCC's @option{-Wabi} switch warns when G++ generates code that is
 115 probably not compatible with the C++ ABI@.
 116
 117 The C++ library used with a C++ compiler includes the Standard C++
 118 Library, with functionality defined in the C++ Standard, plus language
 119 runtime support.  The runtime support is included in a C++ ABI, but there
 120 is no formal ABI for the Standard C++ Library.  Two implementations
 121 of that library are interoperable if one follows the de-facto ABI of the
 122 other and if they are both built with the same compiler, or with compilers
 123 that conform to the same ABI for C++ compiler and runtime support.
 124
 125 When G++ and another C++ compiler conform to the same C++ ABI, but the
 126 implementations of the Standard C++ Library that they normally use do not
 127 follow the same ABI for the Standard C++ Library, object files built with
 128 those compilers can be used in the same program only if they use the same
 129 C++ library.  This requires specifying the location of the C++ library
 130 header files when invoking the compiler whose usual library is not being
 131 used.  The location of GCC's C++ header files depends on how the GCC
 132 build was configured, but can be seen by using the G++ @option{-v} option.
 133 With default configuration options for G++ 3.3 the compile line for a
 134 different C++ compiler needs to include
 135
 136 @smallexample
 137     -I@var{gcc_install_directory}/include/c++/3.3
 138 @end smallexample
 139
 140 Similarly, compiling code with G++ that must use a C++ library other
 141 than the GNU C++ library requires specifying the location of the header
 142 files for that other library.
 143
 144 The most straightforward way to link a program to use a particular
 145 C++ library is to use a C++ driver that specifies that C++ library by
 146 default.  The @command{g++} driver, for example, tells the linker where
 147 to find GCC's C++ library (@file{libstdc++}) plus the other libraries
 148 and startup files it needs, in the proper order.
 149
 150 If a program must use a different C++ library and it's not possible
 151 to do the final link using a C++ driver that uses that library by default,
 152 it is necessary to tell @command{g++} the location and name of that
 153 library.  It might also be necessary to specify different startup files
 154 and other runtime support libraries, and to suppress the use of GCC's
 155 support libraries with one or more of the options @option{-nostdlib},
 156 @option{-nostartfiles}, and @option{-nodefaultlibs}.