1 .\" Copyright (c) 1991, 1992 Free Software Foundation -*-Text-*-
2 .\" See section COPYING for conditions for redistribution
3 .\" FIXME: no info here on predefines. Should there be? extra for C++...
4 .TH G++ 1 "30apr1993" "GNU Tools" "GNU Tools"
11 g++ \- GNU project C++ Compiler (v2.4)
14 .IR option " | " filename " ].\|.\|.
16 The C and C++ compilers are integrated;
19 .B gcc with options to recognize C++.
22 through one or more of four stages: preprocessing, compilation,
23 assembly, and linking. This man page contains full descriptions for
25 C++ specific aspects of the compiler, though it also contains
26 summaries of some general-purpose options. For a fuller explanation
30 C++ source files use one of the suffixes `\|\c
36 \&\|'; preprocessed C++ files use the suffix `\|\c
40 There are many command-line options, including options to control
41 details of optimization, warnings, and code generation, which are
46 \&. For full information on all options, see
49 Options must be separate: `\|\c
51 \&\|' is quite different from `\|\c
59 \&\|' options have two contrary forms:
67 \&). Only the non-default forms are shown here.
71 Compile or assemble the source files, but do not link. The compiler
72 output is an object file corresponding to each source file.
77 \& with the string `\|\c
79 \&\|' as its definition.
89 Stop after the preprocessing stage; do not run the compiler proper. The
90 output is preprocessed source code, which is sent to the
94 Treat all possible member functions as virtual, implicitly. All
95 member functions (except for constructor functions and
99 member operators) are treated as virtual functions of the class where
102 This does not mean that all calls to these member functions will be
103 made through the internal table of virtual functions. Under some
104 circumstances, the compiler can determine that a call to a given
105 virtual function can be made directly; in these cases the calls are
108 .B \-fdollars\-in\-identifiers
109 Permit the use of `\|\c
111 \&\|' in identifiers.
112 Traditional C allowed the character `\|\c
114 \&\|' to form part of identifiers; by default, GNU C also
115 allows this. However, ANSI C forbids `\|\c
117 \&\|' in identifiers, and GNU C++ also forbids it by default on most
118 platforms (though on some platforms it's enabled by default for GNU
121 .B \-felide\-constructors
122 Use this option to instruct the compiler to be smarter about when it can
123 elide constructors. Without this flag, GNU C++ and cfront both
124 generate effectively the same code for:
129 A\ x\ (foo\ ());\ \ \ //\ x\ initialized\ by\ `foo\ ()',\ no\ ctor\ called
131 A\ y\ =\ foo\ ();\ \ \ //\ call\ to\ `foo\ ()'\ heads\ to\ temporary,
133 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ //\ y\ is\ initialized\ from\ the\ temporary.
136 Note the difference! With this flag, GNU C++ initializes `\|\c
141 without going through a temporary.
143 .B \-fenum\-int\-equiv
144 Normally GNU C++ allows conversion of
148 \&, but not the other way around. Use this option if you want GNU C++
149 to allow conversion of
155 .B \-fexternal\-templates
156 Produce smaller code for template declarations, by generating only a
157 single copy of each template function where it is defined.
158 To use this option successfully, you must also mark all files that
159 use templates with either `\|\c
160 .B #pragma implementation\c
161 \&\|' (the definition) or
163 .B #pragma interface\c
164 \&\|' (declarations).
166 When your code is compiled with `\|\c
167 .B \-fexternal\-templates\c
169 template instantiations are external. You must arrange for all
170 necessary instantiations to appear in the implementation file; you can
173 \& that references each instantiation needed.
174 Conversely, when you compile using the default option
176 .B \-fno\-external\-templates\c
177 \&\|', all template instantiations are
180 .B \-fno\-gnu\-linker
181 Do not output global initializations (such as C++ constructors and
182 destructors) in the form used by the GNU linker (on systems where the GNU
183 linker is the standard method of handling them). Use this option when
184 you want to use a non-GNU linker, which also requires using the
186 program to make sure the system linker includes
187 constructors and destructors. (\c
189 is included in the GNU CC distribution.) For systems which
193 \&, the compiler driver
195 is configured to do this automatically.
197 .B \-fmemoize\-lookups
200 These flags are used to get the compiler to compile programs faster
201 using heuristics. They are not on by default since they are only effective
202 about half the time. The other half of the time programs compile more
203 slowly (and take more memory).
205 The first time the compiler must build a call to a member function (or
206 reference to a data member), it must (1) determine whether the class
207 implements member functions of that name; (2) resolve which member
208 function to call (which involves figuring out what sorts of type
209 conversions need to be made); and (3) check the visibility of the member
210 function to the caller. All of this adds up to slower compilation.
211 Normally, the second time a call is made to that member function (or
212 reference to that data member), it must go through the same lengthy
213 process again. This means that code like this
216 \ \ cout\ <<\ "This\ "\ <<\ p\ <<\ "\ has\ "\ <<\ n\ <<\ "\ legs.\en";
219 makes six passes through all three steps. By using a software cache,
220 a ``hit'' significantly reduces this cost. Unfortunately, using the
221 cache introduces another layer of mechanisms which must be implemented,
222 and so incurs its own overhead. `\|\c
223 .B \-fmemoize\-lookups\c
227 Because access privileges (visibility) to members and member functions
228 may differ from one function context to the next,
230 may need to flush the cache. With the `\|\c
231 .B \-fmemoize\-lookups\c
232 \&\|' flag, the cache is flushed after every
233 function that is compiled. The `\|\c
235 \&\|' flag enables the same software cache, but when the compiler
236 determines that the context of the last function compiled would yield
237 the same access privileges of the next function to compile, it
239 This is most helpful when defining many member functions for the same
240 class: with the exception of member functions which are friends of
241 other classes, each member function has exactly the same access
242 privileges as every other, and the cache need not be flushed.
244 .B \-fno\-default\-inline
245 Do not make member functions inline by default merely because they are
246 defined inside the class scope. Otherwise, when you specify
248 \&, member functions defined inside class scope are compiled
249 inline by default; i.e., you don't need to add `\|\c
252 the member function name.
254 .B \-fno\-strict\-prototype
255 Consider the declaration \c
257 \&. In C++, this means that the
260 \& takes no arguments. In ANSI C, this is declared
262 \&. With the flag `\|\c
263 .B \-fno\-strict\-prototype\c
265 declaring functions with no arguments is equivalent to declaring its
266 argument list to be untyped, i.e., \c
273 .B \-fnonnull\-objects
274 Normally, GNU C++ makes conservative assumptions about objects reached
275 through references. For example, the compiler must check that `\|\c
277 \&\|' is not null in code like the following:
279 \ \ \ \ obj\ &a\ =\ g\ ();
283 Checking that references of this sort have non-null values requires
284 extra code, however, and it is unnecessary for many programs. You can
286 .B \-fnonnull\-objects\c
287 \&\|' to omit the checks for null, if your program doesn't require the
290 .B \-fhandle\-signatures
292 .B \-fno\-handle\-signatures
293 These options control the recognition of the \c
297 \& constructs for specifying abstract types. By default, these
298 constructs are not recognized.
300 .B \-fthis\-is\-variable
301 The incorporation of user-defined free store management into C++ has
302 made assignment to \c
304 \& an anachronism. Therefore, by default GNU
305 C++ treats the type of \c
307 \& in a member function of \c
312 \&. In other words, it is illegal to assign to
315 \& within a class member function. However, for backwards
316 compatibility, you can invoke the old behavior by using
318 .B \-fthis\-is\-variable\c
322 Produce debugging information in the operating system's native format
323 (for DBX or SDB or DWARF). GDB also can work with this debugging
324 information. On most systems that use DBX format, `\|\c
327 of extra debugging information that only GDB can use.
329 Unlike most other C compilers, GNU CC allows you to use `\|\c
334 \&\|'. The shortcuts taken by optimized code may occasionally
335 produce surprising results: some variables you declared may not exist
336 at all; flow of control may briefly move where you did not expect it;
337 some statements may not be executed because they compute constant
338 results or their values were already at hand; some statements may
339 execute in different places because they were moved out of loops.
341 Nevertheless it proves possible to debug optimized output. This makes
342 it reasonable to use the optimizer for programs that might have bugs.
348 \& to the list of directories searched for include files.
354 \& to the list of directories to be searched
361 Use the library named \c
363 \& when linking. (C++ programs often require `\|\c
365 \&\|' for successful linking.)
368 Do not search the standard system directories for header files. Only
369 the directories you have specified with
371 options (and the current directory, if appropriate) are searched.
374 Do not search for header files in the standard directories specific to
375 C++, but do still search the other standard directories. (This option
376 is used when building libg++.)
379 Optimize. Optimizing compilation takes somewhat more time, and a lot
380 more memory for a large function.
384 Place output in file \c
389 Stop after the stage of compilation proper; do not assemble. The output
390 is an assembler code file for each non-assembler input
394 Attempt to support some aspects of traditional C compilers.
396 Specifically, for both C and C++ programs:
399 In the preprocessor, comments convert to nothing at all, rather than
400 to a space. This allows traditional token concatenation.
403 In the preprocessor, macro arguments are recognized within string
404 constants in a macro definition (and their values are stringified,
405 though without additional quote marks, when they appear in such a
406 context). The preprocessor always considers a string constant to end
410 The preprocessor does not predefine the macro \c
415 \&\|', but still predefines\c
417 \& (since the GNU extensions indicated by
419 \& are not affected by
422 \&\|'). If you need to write header files that work
423 differently depending on whether `\|\c
426 testing both of these predefined macros you can distinguish four
427 situations: GNU C, traditional GNU C, other ANSI C compilers, and
428 other old C compilers.
431 In the preprocessor, comments convert to nothing at all, rather than
432 to a space. This allows traditional token concatenation.
435 In the preprocessor, macro arguments are recognized within string
436 constants in a macro definition (and their values are stringified,
437 though without additional quote marks, when they appear in such a
438 context). The preprocessor always considers a string constant to end
442 The preprocessor does not predefine the macro \c
447 \&\|', but still predefines\c
449 \& (since the GNU extensions indicated by
451 \& are not affected by
454 \&\|'). If you need to write header files that work
455 differently depending on whether `\|\c
458 testing both of these predefined macros you can distinguish four
459 situations: GNU C, traditional GNU C, other ANSI C compilers, and
460 other old C compilers.
464 String ``constants'' are not necessarily constant; they are stored in
465 writable space, and identical looking constants are allocated
468 For C++ programs only (not C), `\|\c
470 \&\|' has one additional effect: assignment to
472 is permitted. This is the same as the effect of `\|\c
473 .B \-fthis\-is\-variable\c
482 Issue warnings for conditions which pertain to usage that we recommend
483 avoiding and that we believe is easy to avoid, even in conjunction
487 Warn when converting between different enumeration types.
489 .B \-Woverloaded\-virtual
490 In a derived class, the definitions of virtual functions must match
491 the type signature of a virtual function declared in the base class.
492 Use this option to request warnings when a derived class declares a
493 function that may be an erroneous attempt to define a virtual
494 function: that is, warn when a function with the same name as a
495 virtual function in the base class, but with a type signature that
496 doesn't match any virtual functions from the base class.
498 .B \-Wtemplate\-debugging
499 When using templates in a C++ program, warn if debugging is not yet
503 Inhibit all warning messages.
506 Control how virtual function definitions are used, in a fashion
515 \&\|' directives are supported for GNU C++, to permit using the same
516 header file for two purposes: as a definition of interfaces to a given
517 object class, and as the full definition of the contents of that object class.
520 Use this directive in header files that define object classes, to save
521 space in most of the object files that use those classes. Normally,
522 local copies of certain information (backup copies of inline member
523 functions, debugging information, and the internal tables that
524 implement virtual functions) must be kept in each object file that
525 includes class definitions. You can use this pragma to avoid such
526 duplication. When a header file containing `\|\c
527 .B #pragma interface\c
528 \&\|' is included in a compilation, this auxiliary information
529 will not be generated (unless the main input source file itself uses
531 .B #pragma implementation\c
532 \&\|'). Instead, the object files will contain references to be
533 resolved at link time.
536 .B #pragma implementation
538 .BI "#pragma implementation !" objects .h!
539 Use this pragma in a main input file, when you want full output from
540 included header files to be generated (and made globally visible).
541 The included header file, in turn, should use `\|\c
542 .B #pragma interface\c
544 Backup copies of inline member functions, debugging information, and
545 the internal tables used to implement virtual functions are all
546 generated in implementation files.
549 .B #pragma implementation\c
550 \&\|' with no argument, it applies to an include file with the same
551 basename as your source file; for example, in `\|\c
554 .B #pragma implementation\c
555 \&\|' by itself is equivalent to `\|\c
557 #pragma implementation "allclass.h"\c
558 \&\|'. Use the string argument if you want a single implementation
559 file to include code from multiple header files.
561 There is no way to split up the contents of a single header file into
562 multiple implementation files.
564 .ta \w'LIBDIR/g++\-include 'u
565 file.h C header (preprocessor) file
567 file.i preprocessed C source file
569 file.C C++ source file
571 file.cc C++ source file
573 file.cxx C++ source file
575 file.s assembly language file
579 a.out link edited output
581 \fITMPDIR\fR/cc\(** temporary files
583 \fILIBDIR\fR/cpp preprocessor
585 \fILIBDIR\fR/cc1plus compiler
587 \fILIBDIR\fR/collect linker front end needed on some machines
589 \fILIBDIR\fR/libgcc.a GCC subroutine library
591 /lib/crt[01n].o start-up routine
593 \fILIBDIR\fR/ccrt0 additional start-up routine for C++
595 /lib/libc.a standard C library, see
598 /usr/include standard directory for
602 \fILIBDIR\fR/include standard gcc directory for
606 \fILIBDIR\fR/g++\-include additional g++ directory for
612 .IR machine / version .
615 comes from the environment variable
623 gcc(1), cpp(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1).
625 .RB "`\|" gcc "\|', `\|" cpp \|',
626 .RB `\| as \|', `\| ld \|',
634 Using and Porting GNU CC (for version 2.0)\c
635 , Richard M. Stallman;
638 , Richard M. Stallman;
640 Debugging with GDB: the GNU Source-Level Debugger\c
641 , Richard M. Stallman and Roland H. Pesch;
643 Using as: the GNU Assembler\c
644 , Dean Elsner, Jay Fenlason & friends;
646 gld: the GNU linker\c
647 , Steve Chamberlain and Roland Pesch.
650 For instructions on how to report bugs, see the GCC manual.
653 Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
655 Permission is granted to make and distribute verbatim copies of
656 this manual provided the copyright notice and this permission notice
657 are preserved on all copies.
659 Permission is granted to copy and distribute modified versions of this
660 manual under the conditions for verbatim copying, provided that the
661 entire resulting derived work is distributed under the terms of a
662 permission notice identical to this one.
664 Permission is granted to copy and distribute translations of this
665 manual into another language, under the above conditions for modified
666 versions, except that this permission notice may be included in
667 translations approved by the Free Software Foundation instead of in
668 the original English.
670 See the GNU CC Manual for the contributors to GNU CC.