gcc/doc/compat.texi - gcc - Git at Google

 @c Copyright (C) 2002-2021 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.

 @node Compatibility
 @chapter Binary Compatibility
 @cindex binary compatibility
 @cindex ABI
 @cindex application binary interface

 Binary compatibility encompasses several related concepts:

 @table @dfn
 @item application binary interface (ABI)
 The set of runtime conventions followed by all of the tools that deal
 with binary representations of a program, including compilers, assemblers,
 linkers, and language runtime support.
 Some ABIs are formal with a written specification, possibly designed
 by multiple interested parties.  Others are simply the way things are
 actually done by a particular set of tools.

 @item ABI conformance
 A compiler conforms to an ABI if it generates code that follows all of
 the specifications enumerated by that ABI@.
 A library conforms to an ABI if it is implemented according to that ABI@.
 An application conforms to an ABI if it is built using tools that conform
 to that ABI and does not contain source code that specifically changes
 behavior specified by the ABI@.

 @item calling conventions
 Calling conventions are a subset of an ABI that specify of how arguments
 are passed and function results are returned.

 @item interoperability
 Different sets of tools are interoperable if they generate files that
 can be used in the same program.  The set of tools includes compilers,
 assemblers, linkers, libraries, header files, startup files, and debuggers.
 Binaries produced by different sets of tools are not interoperable unless
 they implement the same ABI@.  This applies to different versions of the
 same tools as well as tools from different vendors.

 @item intercallability
 Whether a function in a binary built by one set of tools can call a
 function in a binary built by a different set of tools is a subset
 of interoperability.

 @item implementation-defined features
 Language standards include lists of implementation-defined features whose
 behavior can vary from one implementation to another.  Some of these
 features are normally covered by a platform's ABI and others are not.
 The features that are not covered by an ABI generally affect how a
 program behaves, but not intercallability.

 @item compatibility
 Conformance to the same ABI and the same behavior of implementation-defined
 features are both relevant for compatibility.
 @end table

 The application binary interface implemented by a C or C++ compiler
 affects code generation and runtime support for:

 @itemize @bullet
 @item
 size and alignment of data types
 @item
 layout of structured types
 @item
 calling conventions
 @item
 register usage conventions
 @item
 interfaces for runtime arithmetic support
 @item
 object file formats
 @end itemize

 In addition, the application binary interface implemented by a C++ compiler
 affects code generation and runtime support for:
 @itemize @bullet
 @item
 name mangling
 @item
 exception handling
 @item
 invoking constructors and destructors
 @item
 layout, alignment, and padding of classes
 @item
 layout and alignment of virtual tables
 @end itemize

 Some GCC compilation options cause the compiler to generate code that
 does not conform to the platform's default ABI@.  Other options cause
 different program behavior for implementation-defined features that are
 not covered by an ABI@.  These options are provided for consistency with
 other compilers that do not follow the platform's default ABI or the
 usual behavior of implementation-defined features for the platform.
 Be very careful about using such options.

 Most platforms have a well-defined ABI that covers C code, but ABIs
 that cover C++ functionality are not yet common.

 Starting with GCC 3.2, GCC binary conventions for C++ are based on a
 written, vendor-neutral C++ ABI that was designed to be specific to
 64-bit Itanium but also includes generic specifications that apply to
 any platform.
 This C++ ABI is also implemented by other compiler vendors on some
 platforms, notably GNU/Linux and BSD systems.
 We have tried hard to provide a stable ABI that will be compatible with
 future GCC releases, but it is possible that we will encounter problems
 that make this difficult.  Such problems could include different
 interpretations of the C++ ABI by different vendors, bugs in the ABI, or
 bugs in the implementation of the ABI in different compilers.
 GCC's @option{-Wabi} switch warns when G++ generates code that is
 probably not compatible with the C++ ABI@.

 The C++ library used with a C++ compiler includes the Standard C++
 Library, with functionality defined in the C++ Standard, plus language
 runtime support.  The runtime support is included in a C++ ABI, but there
 is no formal ABI for the Standard C++ Library.  Two implementations
 of that library are interoperable if one follows the de-facto ABI of the
 other and if they are both built with the same compiler, or with compilers
 that conform to the same ABI for C++ compiler and runtime support.

 When G++ and another C++ compiler conform to the same C++ ABI, but the
 implementations of the Standard C++ Library that they normally use do not
 follow the same ABI for the Standard C++ Library, object files built with
 those compilers can be used in the same program only if they use the same
 C++ library.  This requires specifying the location of the C++ library
 header files when invoking the compiler whose usual library is not being
 used.  The location of GCC's C++ header files depends on how the GCC
 build was configured, but can be seen by using the G++ @option{-v} option.
 With default configuration options for G++ 3.3 the compile line for a
 different C++ compiler needs to include

 @smallexample
     -I@var{gcc_install_directory}/include/c++/3.3
 @end smallexample

 Similarly, compiling code with G++ that must use a C++ library other
 than the GNU C++ library requires specifying the location of the header
 files for that other library.

 The most straightforward way to link a program to use a particular
 C++ library is to use a C++ driver that specifies that C++ library by
 default.  The @command{g++} driver, for example, tells the linker where
 to find GCC's C++ library (@file{libstdc++}) plus the other libraries
 and startup files it needs, in the proper order.

 If a program must use a different C++ library and it's not possible
 to do the final link using a C++ driver that uses that library by default,
 it is necessary to tell @command{g++} the location and name of that
 library.  It might also be necessary to specify different startup files
 and other runtime support libraries, and to suppress the use of GCC's
 support libraries with one or more of the options @option{-nostdlib},
 @option{-nostartfiles}, and @option{-nodefaultlibs}.
	@c Copyright (C) 2002-2021 Free Software Foundation, Inc.
	@c This is part of the GCC manual.
	@c For copying conditions, see the file gcc.texi.

	@node Compatibility
	@chapter Binary Compatibility
	@cindex binary compatibility
	@cindex ABI
	@cindex application binary interface

	Binary compatibility encompasses several related concepts:

	@table @dfn
	@item application binary interface (ABI)
	The set of runtime conventions followed by all of the tools that deal
	with binary representations of a program, including compilers, assemblers,
	linkers, and language runtime support.
	Some ABIs are formal with a written specification, possibly designed
	by multiple interested parties. Others are simply the way things are
	actually done by a particular set of tools.

	@item ABI conformance
	A compiler conforms to an ABI if it generates code that follows all of
	the specifications enumerated by that ABI@.
	A library conforms to an ABI if it is implemented according to that ABI@.
	An application conforms to an ABI if it is built using tools that conform
	to that ABI and does not contain source code that specifically changes
	behavior specified by the ABI@.

	@item calling conventions
	Calling conventions are a subset of an ABI that specify of how arguments
	are passed and function results are returned.

	@item interoperability
	Different sets of tools are interoperable if they generate files that
	can be used in the same program. The set of tools includes compilers,
	assemblers, linkers, libraries, header files, startup files, and debuggers.
	Binaries produced by different sets of tools are not interoperable unless
	they implement the same ABI@. This applies to different versions of the
	same tools as well as tools from different vendors.

	@item intercallability
	Whether a function in a binary built by one set of tools can call a
	function in a binary built by a different set of tools is a subset
	of interoperability.

	@item implementation-defined features
	Language standards include lists of implementation-defined features whose
	behavior can vary from one implementation to another. Some of these
	features are normally covered by a platform's ABI and others are not.
	The features that are not covered by an ABI generally affect how a
	program behaves, but not intercallability.

	@item compatibility
	Conformance to the same ABI and the same behavior of implementation-defined
	features are both relevant for compatibility.
	@end table

	The application binary interface implemented by a C or C++ compiler
	affects code generation and runtime support for:

	@itemize @bullet
	@item
	size and alignment of data types
	@item
	layout of structured types
	@item
	calling conventions
	@item
	register usage conventions
	@item
	interfaces for runtime arithmetic support
	@item
	object file formats
	@end itemize

	In addition, the application binary interface implemented by a C++ compiler
	affects code generation and runtime support for:
	@itemize @bullet
	@item
	name mangling
	@item
	exception handling
	@item
	invoking constructors and destructors
	@item
	layout, alignment, and padding of classes
	@item
	layout and alignment of virtual tables
	@end itemize

	Some GCC compilation options cause the compiler to generate code that
	does not conform to the platform's default ABI@. Other options cause
	different program behavior for implementation-defined features that are
	not covered by an ABI@. These options are provided for consistency with
	other compilers that do not follow the platform's default ABI or the
	usual behavior of implementation-defined features for the platform.
	Be very careful about using such options.

	Most platforms have a well-defined ABI that covers C code, but ABIs
	that cover C++ functionality are not yet common.

	Starting with GCC 3.2, GCC binary conventions for C++ are based on a
	written, vendor-neutral C++ ABI that was designed to be specific to
	64-bit Itanium but also includes generic specifications that apply to
	any platform.
	This C++ ABI is also implemented by other compiler vendors on some
	platforms, notably GNU/Linux and BSD systems.
	We have tried hard to provide a stable ABI that will be compatible with
	future GCC releases, but it is possible that we will encounter problems
	that make this difficult. Such problems could include different
	interpretations of the C++ ABI by different vendors, bugs in the ABI, or
	bugs in the implementation of the ABI in different compilers.
	GCC's @option{-Wabi} switch warns when G++ generates code that is
	probably not compatible with the C++ ABI@.

	The C++ library used with a C++ compiler includes the Standard C++
	Library, with functionality defined in the C++ Standard, plus language
	runtime support. The runtime support is included in a C++ ABI, but there
	is no formal ABI for the Standard C++ Library. Two implementations
	of that library are interoperable if one follows the de-facto ABI of the
	other and if they are both built with the same compiler, or with compilers
	that conform to the same ABI for C++ compiler and runtime support.

	When G++ and another C++ compiler conform to the same C++ ABI, but the
	implementations of the Standard C++ Library that they normally use do not
	follow the same ABI for the Standard C++ Library, object files built with
	those compilers can be used in the same program only if they use the same
	C++ library. This requires specifying the location of the C++ library
	header files when invoking the compiler whose usual library is not being
	used. The location of GCC's C++ header files depends on how the GCC
	build was configured, but can be seen by using the G++ @option{-v} option.
	With default configuration options for G++ 3.3 the compile line for a
	different C++ compiler needs to include

	@smallexample
	-I@var{gcc_install_directory}/include/c++/3.3
	@end smallexample

	Similarly, compiling code with G++ that must use a C++ library other
	than the GNU C++ library requires specifying the location of the header
	files for that other library.

	The most straightforward way to link a program to use a particular
	C++ library is to use a C++ driver that specifies that C++ library by
	default. The @command{g++} driver, for example, tells the linker where
	to find GCC's C++ library (@file{libstdc++}) plus the other libraries
	and startup files it needs, in the proper order.

	If a program must use a different C++ library and it's not possible
	to do the final link using a C++ driver that uses that library by default,
	it is necessary to tell @command{g++} the location and name of that
	library. It might also be necessary to specify different startup files
	and other runtime support libraries, and to suppress the use of GCC's
	support libraries with one or more of the options @option{-nostdlib},
	@option{-nostartfiles}, and @option{-nodefaultlibs}.