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