]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: interface and implementation headers, C++, C++ interface and implementation headers, pragmas, interface and implementation | |
7 | ||
8 | .. _c++-interface: | |
9 | ||
10 | C++ Interface and Implementation Pragmas | |
11 | **************************************** | |
12 | ||
13 | ``#pragma interface`` and ``#pragma implementation`` provide the | |
14 | user with a way of explicitly directing the compiler to emit entities | |
15 | with vague linkage (and debugging information) in a particular | |
16 | translation unit. | |
17 | ||
18 | .. note:: | |
19 | ||
20 | These ``#pragma`` s have been superceded as of GCC 2.7.2 | |
21 | by COMDAT support and the 'key method' heuristic | |
22 | mentioned in :ref:`vague-linkage`. Using them can actually cause your | |
23 | program to grow due to unnecessary out-of-line copies of inline | |
24 | functions. | |
25 | ||
26 | ``#pragma interface`` :samp:`#pragma interface "{subdir}/{objects}.h"` | |
27 | ||
28 | .. index:: #pragma interface | |
29 | ||
30 | Use this directive in *header files* that define object classes, to save | |
31 | space in most of the object files that use those classes. Normally, | |
32 | local copies of certain information (backup copies of inline member | |
33 | functions, debugging information, and the internal tables that implement | |
34 | virtual functions) must be kept in each object file that includes class | |
35 | definitions. You can use this pragma to avoid such duplication. When a | |
36 | header file containing :samp:`#pragma interface` is included in a | |
37 | compilation, this auxiliary information is not generated (unless | |
38 | the main input source file itself uses :samp:`#pragma implementation`). | |
39 | Instead, the object files contain references to be resolved at link | |
40 | time. | |
41 | ||
42 | The second form of this directive is useful for the case where you have | |
43 | multiple headers with the same name in different directories. If you | |
44 | use this form, you must specify the same string to :samp:`#pragma | |
45 | implementation`. | |
46 | ||
47 | ``#pragma implementation`` :samp:`#pragma implementation "{objects}.h"` | |
48 | ||
49 | .. index:: #pragma implementation | |
50 | ||
51 | Use this pragma in a *main input file*, when you want full output from | |
52 | included header files to be generated (and made globally visible). The | |
53 | included header file, in turn, should use :samp:`#pragma interface`. | |
54 | Backup copies of inline member functions, debugging information, and the | |
55 | internal tables used to implement virtual functions are all generated in | |
56 | implementation files. | |
57 | ||
58 | .. index:: implied #pragma implementation, #pragma implementation, implied, naming convention, implementation headers | |
59 | ||
60 | If you use :samp:`#pragma implementation` with no argument, it applies to | |
61 | an include file with the same basenameA file's :dfn:`basename` | |
62 | is the name stripped of all leading path information and of trailing | |
63 | suffixes, such as :samp:`.h` or :samp:`.C` or :samp:`.cc`. | |
64 | as your source | |
65 | file. For example, in :samp:`allclass.cc`, giving just | |
66 | :samp:`#pragma implementation` | |
67 | by itself is equivalent to :samp:`#pragma implementation "allclass.h"`. | |
68 | ||
69 | Use the string argument if you want a single implementation file to | |
70 | include code from multiple header files. (You must also use | |
71 | :samp:`#include` to include the header file; :samp:`#pragma | |
72 | implementation` only specifies how to use the file---it doesn't actually | |
73 | include it.) | |
74 | ||
75 | There is no way to split up the contents of a single header file into | |
76 | multiple implementation files. | |
77 | ||
78 | .. index:: inlining and C++ pragmas, C++ pragmas, effect on inlining, pragmas in C++, effect on inlining | |
79 | ||
80 | :samp:`#pragma implementation` and :samp:`#pragma interface` also have an | |
81 | effect on function inlining. | |
82 | ||
83 | If you define a class in a header file marked with :samp:`#pragma | |
84 | interface`, the effect on an inline function defined in that class is | |
85 | similar to an explicit ``extern`` declaration---the compiler emits | |
86 | no code at all to define an independent version of the function. Its | |
87 | definition is used only for inlining with its callers. | |
88 | ||
89 | .. index:: fno-implement-inlines | |
90 | ||
91 | Conversely, when you include the same header file in a main source file | |
92 | that declares it as :samp:`#pragma implementation`, the compiler emits | |
93 | code for the function itself; this defines a version of the function | |
94 | that can be found via pointers (or by callers compiled without | |
95 | inlining). If all calls to the function can be inlined, you can avoid | |
96 | emitting the function by compiling with :option:`-fno-implement-inlines`. | |
3ed1b4ce | 97 | If any calls are not inlined, you will get linker errors. |