]>
Commit | Line | Data |
---|---|---|
23a5b65a | 1 | @c Copyright (C) 2002-2014 Free Software Foundation, Inc. |
7c19f816 JJ |
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. | |
4ec7afd7 | 114 | GCC's @option{-Wabi} switch warns when G++ generates code that is |
7c19f816 | 115 | probably not compatible with the C++ ABI@. |
8eb32f94 JJ |
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 | ||
3ab51846 | 136 | @smallexample |
8eb32f94 | 137 | -I@var{gcc_install_directory}/include/c++/3.3 |
3ab51846 | 138 | @end smallexample |
8eb32f94 JJ |
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}. |