1*ec02198aSmrg@c Copyright (C) 2002-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@node Compatibility 610d565efSmrg@chapter Binary Compatibility 710d565efSmrg@cindex binary compatibility 810d565efSmrg@cindex ABI 910d565efSmrg@cindex application binary interface 1010d565efSmrg 1110d565efSmrgBinary compatibility encompasses several related concepts: 1210d565efSmrg 1310d565efSmrg@table @dfn 1410d565efSmrg@item application binary interface (ABI) 1510d565efSmrgThe set of runtime conventions followed by all of the tools that deal 1610d565efSmrgwith binary representations of a program, including compilers, assemblers, 1710d565efSmrglinkers, and language runtime support. 1810d565efSmrgSome ABIs are formal with a written specification, possibly designed 1910d565efSmrgby multiple interested parties. Others are simply the way things are 2010d565efSmrgactually done by a particular set of tools. 2110d565efSmrg 2210d565efSmrg@item ABI conformance 2310d565efSmrgA compiler conforms to an ABI if it generates code that follows all of 2410d565efSmrgthe specifications enumerated by that ABI@. 2510d565efSmrgA library conforms to an ABI if it is implemented according to that ABI@. 2610d565efSmrgAn application conforms to an ABI if it is built using tools that conform 2710d565efSmrgto that ABI and does not contain source code that specifically changes 2810d565efSmrgbehavior specified by the ABI@. 2910d565efSmrg 3010d565efSmrg@item calling conventions 3110d565efSmrgCalling conventions are a subset of an ABI that specify of how arguments 3210d565efSmrgare passed and function results are returned. 3310d565efSmrg 3410d565efSmrg@item interoperability 3510d565efSmrgDifferent sets of tools are interoperable if they generate files that 3610d565efSmrgcan be used in the same program. The set of tools includes compilers, 3710d565efSmrgassemblers, linkers, libraries, header files, startup files, and debuggers. 3810d565efSmrgBinaries produced by different sets of tools are not interoperable unless 3910d565efSmrgthey implement the same ABI@. This applies to different versions of the 4010d565efSmrgsame tools as well as tools from different vendors. 4110d565efSmrg 4210d565efSmrg@item intercallability 4310d565efSmrgWhether a function in a binary built by one set of tools can call a 4410d565efSmrgfunction in a binary built by a different set of tools is a subset 4510d565efSmrgof interoperability. 4610d565efSmrg 4710d565efSmrg@item implementation-defined features 4810d565efSmrgLanguage standards include lists of implementation-defined features whose 4910d565efSmrgbehavior can vary from one implementation to another. Some of these 5010d565efSmrgfeatures are normally covered by a platform's ABI and others are not. 5110d565efSmrgThe features that are not covered by an ABI generally affect how a 5210d565efSmrgprogram behaves, but not intercallability. 5310d565efSmrg 5410d565efSmrg@item compatibility 5510d565efSmrgConformance to the same ABI and the same behavior of implementation-defined 5610d565efSmrgfeatures are both relevant for compatibility. 5710d565efSmrg@end table 5810d565efSmrg 5910d565efSmrgThe application binary interface implemented by a C or C++ compiler 6010d565efSmrgaffects code generation and runtime support for: 6110d565efSmrg 6210d565efSmrg@itemize @bullet 6310d565efSmrg@item 6410d565efSmrgsize and alignment of data types 6510d565efSmrg@item 6610d565efSmrglayout of structured types 6710d565efSmrg@item 6810d565efSmrgcalling conventions 6910d565efSmrg@item 7010d565efSmrgregister usage conventions 7110d565efSmrg@item 7210d565efSmrginterfaces for runtime arithmetic support 7310d565efSmrg@item 7410d565efSmrgobject file formats 7510d565efSmrg@end itemize 7610d565efSmrg 7710d565efSmrgIn addition, the application binary interface implemented by a C++ compiler 7810d565efSmrgaffects code generation and runtime support for: 7910d565efSmrg@itemize @bullet 8010d565efSmrg@item 8110d565efSmrgname mangling 8210d565efSmrg@item 8310d565efSmrgexception handling 8410d565efSmrg@item 8510d565efSmrginvoking constructors and destructors 8610d565efSmrg@item 8710d565efSmrglayout, alignment, and padding of classes 8810d565efSmrg@item 8910d565efSmrglayout and alignment of virtual tables 9010d565efSmrg@end itemize 9110d565efSmrg 9210d565efSmrgSome GCC compilation options cause the compiler to generate code that 9310d565efSmrgdoes not conform to the platform's default ABI@. Other options cause 9410d565efSmrgdifferent program behavior for implementation-defined features that are 9510d565efSmrgnot covered by an ABI@. These options are provided for consistency with 9610d565efSmrgother compilers that do not follow the platform's default ABI or the 9710d565efSmrgusual behavior of implementation-defined features for the platform. 9810d565efSmrgBe very careful about using such options. 9910d565efSmrg 10010d565efSmrgMost platforms have a well-defined ABI that covers C code, but ABIs 10110d565efSmrgthat cover C++ functionality are not yet common. 10210d565efSmrg 10310d565efSmrgStarting with GCC 3.2, GCC binary conventions for C++ are based on a 10410d565efSmrgwritten, vendor-neutral C++ ABI that was designed to be specific to 10510d565efSmrg64-bit Itanium but also includes generic specifications that apply to 10610d565efSmrgany platform. 10710d565efSmrgThis C++ ABI is also implemented by other compiler vendors on some 10810d565efSmrgplatforms, notably GNU/Linux and BSD systems. 10910d565efSmrgWe have tried hard to provide a stable ABI that will be compatible with 11010d565efSmrgfuture GCC releases, but it is possible that we will encounter problems 11110d565efSmrgthat make this difficult. Such problems could include different 11210d565efSmrginterpretations of the C++ ABI by different vendors, bugs in the ABI, or 11310d565efSmrgbugs in the implementation of the ABI in different compilers. 11410d565efSmrgGCC's @option{-Wabi} switch warns when G++ generates code that is 11510d565efSmrgprobably not compatible with the C++ ABI@. 11610d565efSmrg 11710d565efSmrgThe C++ library used with a C++ compiler includes the Standard C++ 11810d565efSmrgLibrary, with functionality defined in the C++ Standard, plus language 11910d565efSmrgruntime support. The runtime support is included in a C++ ABI, but there 12010d565efSmrgis no formal ABI for the Standard C++ Library. Two implementations 12110d565efSmrgof that library are interoperable if one follows the de-facto ABI of the 12210d565efSmrgother and if they are both built with the same compiler, or with compilers 12310d565efSmrgthat conform to the same ABI for C++ compiler and runtime support. 12410d565efSmrg 12510d565efSmrgWhen G++ and another C++ compiler conform to the same C++ ABI, but the 12610d565efSmrgimplementations of the Standard C++ Library that they normally use do not 12710d565efSmrgfollow the same ABI for the Standard C++ Library, object files built with 12810d565efSmrgthose compilers can be used in the same program only if they use the same 12910d565efSmrgC++ library. This requires specifying the location of the C++ library 13010d565efSmrgheader files when invoking the compiler whose usual library is not being 13110d565efSmrgused. The location of GCC's C++ header files depends on how the GCC 13210d565efSmrgbuild was configured, but can be seen by using the G++ @option{-v} option. 13310d565efSmrgWith default configuration options for G++ 3.3 the compile line for a 13410d565efSmrgdifferent C++ compiler needs to include 13510d565efSmrg 13610d565efSmrg@smallexample 13710d565efSmrg -I@var{gcc_install_directory}/include/c++/3.3 13810d565efSmrg@end smallexample 13910d565efSmrg 14010d565efSmrgSimilarly, compiling code with G++ that must use a C++ library other 14110d565efSmrgthan the GNU C++ library requires specifying the location of the header 14210d565efSmrgfiles for that other library. 14310d565efSmrg 14410d565efSmrgThe most straightforward way to link a program to use a particular 14510d565efSmrgC++ library is to use a C++ driver that specifies that C++ library by 14610d565efSmrgdefault. The @command{g++} driver, for example, tells the linker where 14710d565efSmrgto find GCC's C++ library (@file{libstdc++}) plus the other libraries 14810d565efSmrgand startup files it needs, in the proper order. 14910d565efSmrg 15010d565efSmrgIf a program must use a different C++ library and it's not possible 15110d565efSmrgto do the final link using a C++ driver that uses that library by default, 15210d565efSmrgit is necessary to tell @command{g++} the location and name of that 15310d565efSmrglibrary. It might also be necessary to specify different startup files 15410d565efSmrgand other runtime support libraries, and to suppress the use of GCC's 15510d565efSmrgsupport libraries with one or more of the options @option{-nostdlib}, 15610d565efSmrg@option{-nostartfiles}, and @option{-nodefaultlibs}. 157