Makefile.in (doc): Depend on $(GENERATED_MANPAGES).
gcc: * Makefile.in (doc): Depend on $(GENERATED_MANPAGES). * doc/.cvsignore: Add gcc.1, cpp.1, gcov.1. * doc/gcc.1, doc/cpp.1, doc/gcov.1: Removed. contrib: * gcc_update: Remove entries for gcc.1, cpp.1, gcov.1. From-SVN: r43698
This commit is contained in:
Zack Weinberg
Zack Weinberg
parent
eea81d3e5d
commit
51817b107a
@ -1,3 +1,7 @@
|
||||
2001-07-02 Zack Weinberg <zackw@stanford.edu>
|
||||
|
||||
* gcc_update: Remove entries for gcc.1, cpp.1, gcov.1.
|
||||
|
||||
2001-07-01 Zoltan Felleg <zfelleg@telnet.hu>
|
||||
|
||||
* warn_summary: Fix typo in a comment.
|
||||
|
||||
@ -69,9 +69,6 @@ gcc/configure: gcc/configure.in
|
||||
gcc/cstamp-h.in: gcc/configure.in gcc/acconfig.h
|
||||
gcc/config.in: gcc/cstamp-h.in
|
||||
gcc/fixinc/fixincl.x: gcc/fixinc/fixincl.tpl gcc/fixinc/inclhack.def
|
||||
gcc/doc/gcov.1: gcc/doc/gcov.texi
|
||||
gcc/doc/cpp.1: gcc/doc/cpp.texi
|
||||
gcc/doc/gcc.1: gcc/doc/invoke.texi
|
||||
# And then, language-specific files
|
||||
gcc/f/intdoc.texi: gcc/f/intdoc.in gcc/f/intdoc.c gcc/f/intrin.h gcc/f/intrin.def
|
||||
# And libraries, at last
|
||||
|
||||
@ -1,3 +1,9 @@
|
||||
2001-07-02 Zack Weinberg <zackw@stanford.edu>
|
||||
|
||||
* Makefile.in (doc): Depend on $(GENERATED_MANPAGES).
|
||||
* doc/.cvsignore: Add gcc.1, cpp.1, gcov.1.
|
||||
* doc/gcc.1, doc/cpp.1, doc/gcov.1: Removed.
|
||||
|
||||
2001-07-02 Rainer Orth <ro@TechFak.Uni-Bielefeld.DE>
|
||||
|
||||
* doc/install.texi: Various spelling and markup fixes.
|
||||
|
||||
@ -2208,7 +2208,7 @@ stmp-fixproto: fixhdr.ready fixproto stmp-int-hdrs
|
||||
|
||||
docdir = $(srcdir)/doc
|
||||
|
||||
doc: $(BUILD_INFO) gccbug
|
||||
doc: $(BUILD_INFO) $(GENERATED_MANPAGES) gccbug
|
||||
info: $(docdir)/cpp.info $(docdir)/gcc.info lang.info $(docdir)/cppinternals.info
|
||||
|
||||
$(docdir)/cpp.info: $(docdir)/cpp.texi
|
||||
|
||||
@ -1,3 +1,6 @@
|
||||
gcc.info*
|
||||
cpp.info*
|
||||
cppinternals.info*
|
||||
gcc.1
|
||||
cpp.1
|
||||
gcov.1
|
||||
|
||||
716
gcc/doc/cpp.1
716
gcc/doc/cpp.1
@ -1,716 +0,0 @@
|
||||
.\" Automatically generated by Pod::Man version 1.16
|
||||
.\" Sat Jun 16 11:46:14 2001
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ======================================================================
|
||||
.de Sh \" Subsection heading
|
||||
.br
|
||||
.if t .Sp
|
||||
.ne 5
|
||||
.PP
|
||||
\fB\\$1\fR
|
||||
.PP
|
||||
..
|
||||
.de Sp \" Vertical space (when we can't use .PP)
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Ip \" List item
|
||||
.br
|
||||
.ie \\n(.$>=3 .ne \\$3
|
||||
.el .ne 3
|
||||
.IP "\\$1" \\$2
|
||||
..
|
||||
.de Vb \" Begin verbatim text
|
||||
.ft CW
|
||||
.nf
|
||||
.ne \\$1
|
||||
..
|
||||
.de Ve \" End verbatim text
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.\" Set up some character translations and predefined strings. \*(-- will
|
||||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||||
.\" double quote, and \*(R" will give a right double quote. | will give a
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
||||
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
||||
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
||||
.tr \(*W-|\(bv\*(Tr
|
||||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||||
.ie n \{\
|
||||
. ds -- \(*W-
|
||||
. ds PI pi
|
||||
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||||
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||||
. ds L" ""
|
||||
. ds R" ""
|
||||
. ds C` ""
|
||||
. ds C' ""
|
||||
'br\}
|
||||
.el\{\
|
||||
. ds -- \|\(em\|
|
||||
. ds PI \(*p
|
||||
. ds L" ``
|
||||
. ds R" ''
|
||||
'br\}
|
||||
.\"
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr
|
||||
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
||||
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
||||
.\" the output yourself in some meaningful fashion.
|
||||
.if \nF \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
..
|
||||
. nr % 0
|
||||
. rr F
|
||||
.\}
|
||||
.\"
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
||||
.\" makes way too many mistakes in technical documents.
|
||||
.hy 0
|
||||
.if n .na
|
||||
.\"
|
||||
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||||
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||||
.bd B 3
|
||||
. \" fudge factors for nroff and troff
|
||||
.if n \{\
|
||||
. ds #H 0
|
||||
. ds #V .8m
|
||||
. ds #F .3m
|
||||
. ds #[ \f1
|
||||
. ds #] \fP
|
||||
.\}
|
||||
.if t \{\
|
||||
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||||
. ds #V .6m
|
||||
. ds #F 0
|
||||
. ds #[ \&
|
||||
. ds #] \&
|
||||
.\}
|
||||
. \" simple accents for nroff and troff
|
||||
.if n \{\
|
||||
. ds ' \&
|
||||
. ds ` \&
|
||||
. ds ^ \&
|
||||
. ds , \&
|
||||
. ds ~ ~
|
||||
. ds /
|
||||
.\}
|
||||
.if t \{\
|
||||
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||||
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||||
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||||
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||||
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||||
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||||
.\}
|
||||
. \" troff and (daisy-wheel) nroff accents
|
||||
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||||
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||||
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||||
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||||
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||||
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||||
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||||
.ds ae a\h'-(\w'a'u*4/10)'e
|
||||
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||||
. \" corrections for vroff
|
||||
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||||
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||||
. \" for low resolution devices (crt and lpr)
|
||||
.if \n(.H>23 .if \n(.V>19 \
|
||||
\{\
|
||||
. ds : e
|
||||
. ds 8 ss
|
||||
. ds o a
|
||||
. ds d- d\h'-1'\(ga
|
||||
. ds D- D\h'-1'\(hy
|
||||
. ds th \o'bp'
|
||||
. ds Th \o'LP'
|
||||
. ds ae ae
|
||||
. ds Ae AE
|
||||
.\}
|
||||
.rm #[ #] #H #V #F C
|
||||
.\" ======================================================================
|
||||
.\"
|
||||
.IX Title "CPP 1"
|
||||
.TH CPP 1 "gcc-3.1" "2001-06-16" "GNU"
|
||||
.UC
|
||||
.SH "NAME"
|
||||
cpp \- The C Preprocessor
|
||||
.SH "SYNOPSIS"
|
||||
.IX Header "SYNOPSIS"
|
||||
cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR]
|
||||
[\fB\-I\fR\fIdir\fR...] [\fB\-W\fR\fIwarn\fR...]
|
||||
[\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR]
|
||||
[\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...] [\fB\-MT\fR \fItarget\fR...]
|
||||
[\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR]
|
||||
\fIinfile\fR \fIoutfile\fR
|
||||
.PP
|
||||
Only the most useful options are listed here; see below for the remainder.
|
||||
.SH "DESCRIPTION"
|
||||
.IX Header "DESCRIPTION"
|
||||
The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR
|
||||
that is used automatically by the C compiler to transform your program
|
||||
before compilation. It is called a macro processor because it allows
|
||||
you to define \fImacros\fR, which are brief abbreviations for longer
|
||||
constructs.
|
||||
.PP
|
||||
The C preprocessor is intended to be used only with C, \*(C+, and
|
||||
Objective C source code. In the past, it has been abused as a general
|
||||
text processor. It will choke on input which does not obey C's lexical
|
||||
rules. For example, apostrophes will be interpreted as the beginning of
|
||||
character constants, and cause errors. Also, you cannot rely on it
|
||||
preserving characteristics of the input which are not significant to
|
||||
C-family languages. If a Makefile is preprocessed, all the hard tabs
|
||||
will be removed, and the Makefile will not work.
|
||||
.PP
|
||||
Having said that, you can often get away with using cpp on things which
|
||||
are not C. Other Algol-ish programming languages are often safe
|
||||
(Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\fR
|
||||
mode preserves more white space, and is otherwise more permissive. Many
|
||||
of the problems can be avoided by writing C or \*(C+ style comments
|
||||
instead of native language comments, and keeping macros simple.
|
||||
.PP
|
||||
Wherever possible, you should use a preprocessor geared to the language
|
||||
you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro
|
||||
facilities. Most high level programming languages have their own
|
||||
conditional compilation and inclusion mechanism. If all else fails,
|
||||
try a true general text processor, such as \s-1GNU\s0 M4.
|
||||
.PP
|
||||
C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C
|
||||
preprocessor, which provides a small superset of the features of \s-1ISO\s0
|
||||
Standard C. In its default mode, the \s-1GNU\s0 C preprocessor does not do a
|
||||
few things required by the standard. These are features which are
|
||||
rarely, if ever, used, and may cause surprising changes to the meaning
|
||||
of a program which does not expect them. To get strict \s-1ISO\s0 Standard C,
|
||||
you should use the \fB\-std=c89\fR or \fB\-std=c99\fR options, depending
|
||||
on which version of the standard you want. To get all the mandatory
|
||||
diagnostics, you must also use \fB\-pedantic\fR.
|
||||
.SH "OPTIONS"
|
||||
.IX Header "OPTIONS"
|
||||
The C preprocessor expects two file names as arguments, \fIinfile\fR and
|
||||
\&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any
|
||||
other files it specifies with \fB#include\fR. All the output generated
|
||||
by the combined input files is written in \fIoutfile\fR.
|
||||
.PP
|
||||
Either \fIinfile\fR or \fIoutfile\fR may be \fB-\fR, which as
|
||||
\&\fIinfile\fR means to read from standard input and as \fIoutfile\fR
|
||||
means to write to standard output. Also, if either file is omitted, it
|
||||
means the same as if \fB-\fR had been specified for that file.
|
||||
.PP
|
||||
Unless otherwise noted, or the option ends in \fB=\fR, all options
|
||||
which take an argument may have that argument appear either immediately
|
||||
after the option, or with a space between option and argument:
|
||||
\&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect.
|
||||
.PP
|
||||
Many options have multi-letter names; therefore multiple single-letter
|
||||
options may \fInot\fR be grouped: \fB\-dM\fR is very different from
|
||||
\&\fB\-d\ \-M\fR.
|
||||
.Ip "\fB\-D\fR \fIname\fR" 4
|
||||
.IX Item "-D name"
|
||||
Predefine \fIname\fR as a macro, with definition \f(CW\*(C`1\*(C'\fR.
|
||||
.Ip "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
|
||||
.IX Item "-D name=definition"
|
||||
Predefine \fIname\fR as a macro, with definition \fIdefinition\fR.
|
||||
There are no restrictions on the contents of \fIdefinition\fR, but if
|
||||
you are invoking the preprocessor from a shell or shell-like program you
|
||||
may need to use the shell's quoting syntax to protect characters such as
|
||||
spaces that have a meaning in the shell syntax. If you use more than
|
||||
one \fB\-D\fR for the same \fIname\fR, the rightmost definition takes
|
||||
effect.
|
||||
.Sp
|
||||
If you wish to define a function-like macro on the command line, write
|
||||
its argument list with surrounding parentheses before the equals sign
|
||||
(if any). Parentheses are meaningful to most shells, so you will need
|
||||
to quote the option. With \fBsh\fR and \fBcsh\fR,
|
||||
\&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works.
|
||||
.Ip "\fB\-U\fR \fIname\fR" 4
|
||||
.IX Item "-U name"
|
||||
Cancel any previous definition of \fIname\fR, either built in or
|
||||
provided with a \fB\-D\fR option.
|
||||
.Sp
|
||||
All \fB\-imacros\fR \fIfile\fR and \fB\-include\fR \fIfile\fR options
|
||||
are processed after all \fB\-D\fR and \fB\-U\fR options.
|
||||
.Ip "\fB\-undef\fR" 4
|
||||
.IX Item "-undef"
|
||||
Do not predefine any system-specific macros. The common predefined
|
||||
macros remain defined.
|
||||
.Ip "\fB\-I\fR \fIdir\fR" 4
|
||||
.IX Item "-I dir"
|
||||
Add the directory \fIdir\fR to the list of directories to be searched
|
||||
for header files. Directories named by \fB\-I\fR
|
||||
are searched before the standard system include directories.
|
||||
.Sp
|
||||
It is dangerous to specify a standard system include directory in an
|
||||
\&\fB\-I\fR option. This defeats the special treatment of system
|
||||
headers. It can also defeat the repairs to
|
||||
buggy system headers which \s-1GCC\s0 makes when it is installed.
|
||||
.Ip "\fB\-o\fR \fIfile\fR" 4
|
||||
.IX Item "-o file"
|
||||
Write output to \fIfile\fR. This is the same as specifying \fIfile\fR
|
||||
as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a
|
||||
different interpretation of a second non-option argument, so you must
|
||||
use \fB\-o\fR to specify the output file.
|
||||
.Ip "\fB\-Wall\fR" 4
|
||||
.IX Item "-Wall"
|
||||
Turns on all optional warnings which are desirable for normal code. At
|
||||
present this is \fB\-Wcomment\fR and \fB\-Wtrigraphs\fR. Note that
|
||||
many of the preprocessor's warnings are on by default and have no
|
||||
options to control them.
|
||||
.Ip "\fB\-Wcomment\fR" 4
|
||||
.IX Item "-Wcomment"
|
||||
.PD 0
|
||||
.Ip "\fB\-Wcomments\fR" 4
|
||||
.IX Item "-Wcomments"
|
||||
.PD
|
||||
Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR
|
||||
comment, or whenever a backslash-newline appears in a \fB//\fR comment.
|
||||
(Both forms have the same effect.)
|
||||
.Ip "\fB\-Wtrigraphs\fR" 4
|
||||
.IX Item "-Wtrigraphs"
|
||||
Warn if any trigraphs are encountered. This option used to take effect
|
||||
only if \fB\-trigraphs\fR was also specified, but now works
|
||||
independently. Warnings are not given for trigraphs within comments, as
|
||||
they do not affect the meaning of the program.
|
||||
.Ip "\fB\-Wtraditional\fR" 4
|
||||
.IX Item "-Wtraditional"
|
||||
Warn about certain constructs that behave differently in traditional and
|
||||
\&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C
|
||||
equivalent, and problematic constructs which should be avoided.
|
||||
.Ip "\fB\-Wimport\fR" 4
|
||||
.IX Item "-Wimport"
|
||||
Warn the first time \fB#import\fR is used.
|
||||
.Ip "\fB\-Wundef\fR" 4
|
||||
.IX Item "-Wundef"
|
||||
Warn whenever an identifier which is not a macro is encountered in an
|
||||
\&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are
|
||||
replaced with zero.
|
||||
.Ip "\fB\-Werror\fR" 4
|
||||
.IX Item "-Werror"
|
||||
Make all warnings into hard errors. Source code which triggers warnings
|
||||
will be rejected.
|
||||
.Ip "\fB\-Wsystem-headers\fR" 4
|
||||
.IX Item "-Wsystem-headers"
|
||||
Issue warnings for code in system headers. These are normally unhelpful
|
||||
in finding bugs in your own code, therefore suppressed. If you are
|
||||
responsible for the system library, you may want to see them.
|
||||
.Ip "\fB\-w\fR" 4
|
||||
.IX Item "-w"
|
||||
Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default.
|
||||
.Ip "\fB\-pedantic\fR" 4
|
||||
.IX Item "-pedantic"
|
||||
Issue all the mandatory diagnostics listed in the C standard. Some of
|
||||
them are left out by default, since they trigger frequently on harmless
|
||||
code.
|
||||
.Ip "\fB\-pedantic-errors\fR" 4
|
||||
.IX Item "-pedantic-errors"
|
||||
Issue all the mandatory diagnostics, and make all mandatory diagnostics
|
||||
into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues
|
||||
without \fB\-pedantic\fR but treats as warnings.
|
||||
.Ip "\fB\-M\fR" 4
|
||||
.IX Item "-M"
|
||||
Instead of outputting the result of preprocessing, output a rule
|
||||
suitable for \fBmake\fR describing the dependencies of the main
|
||||
source file. The preprocessor outputs one \fBmake\fR rule containing
|
||||
the object file name for that source file, a colon, and the names of all
|
||||
the included files, including those coming from \fB\-include\fR or
|
||||
\&\fB\-imacros\fR command line options.
|
||||
.Sp
|
||||
Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the
|
||||
object file name consists of the basename of the source file with any
|
||||
suffix replaced with object file suffix. If there are many included
|
||||
files then the rule is split into several lines using \fB\e\fR\-newline.
|
||||
The rule has no commands.
|
||||
.Ip "\fB\-MM\fR" 4
|
||||
.IX Item "-MM"
|
||||
Like \fB\-M\fR, but mention only the files included with \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR or with \fB\-include\fR or \fB\-imacros\fR command line
|
||||
options. System header files included with \f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR
|
||||
are omitted.
|
||||
.Ip "\fB\-MF\fR \fIfile\fR" 4
|
||||
.IX Item "-MF file"
|
||||
When used with \fB\-M\fR or \fB\-MM\fR, specifies a file to write the
|
||||
dependencies to. This allows the preprocessor to write the preprocessed
|
||||
file to stdout normally. If no \fB\-MF\fR switch is given, \s-1CPP\s0 sends
|
||||
the rules to stdout and suppresses normal preprocessed output.
|
||||
.Ip "\fB\-MG\fR" 4
|
||||
.IX Item "-MG"
|
||||
When used with \fB\-M\fR or \fB\-MM\fR, \fB\-MG\fR says to treat missing
|
||||
header files as generated files and assume they live in the same
|
||||
directory as the source file. It suppresses preprocessed output, as a
|
||||
missing header file is ordinarily an error.
|
||||
.Sp
|
||||
This feature is used in automatic updating of makefiles.
|
||||
.Ip "\fB\-MP\fR" 4
|
||||
.IX Item "-MP"
|
||||
This option instructs \s-1CPP\s0 to add a phony target for each dependency
|
||||
other than the main file, causing each to depend on nothing. These
|
||||
dummy rules work around errors \fBmake\fR gives if you remove header
|
||||
files without updating the \fIMakefile\fR to match.
|
||||
.Sp
|
||||
This is typical output:
|
||||
.Sp
|
||||
.Vb 1
|
||||
\& test.o: test.c test.h
|
||||
.Ve
|
||||
.Vb 1
|
||||
\& test.h:
|
||||
.Ve
|
||||
.Ip "\fB\-MT\fR \fItarget\fR" 4
|
||||
.IX Item "-MT target"
|
||||
Change the target of the rule emitted by dependency generation. By
|
||||
default \s-1CPP\s0 takes the name of the main input file, including any path,
|
||||
deletes any file suffix such as \fB.c\fR, and appends the platform's
|
||||
usual object suffix. The result is the target.
|
||||
.Sp
|
||||
An \fB\-MT\fR option will set the target to be exactly the string you
|
||||
specify. If you want multiple targets, you can specify them as a single
|
||||
argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options.
|
||||
.Sp
|
||||
For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give
|
||||
.Sp
|
||||
.Vb 1
|
||||
\& $(objpfx)foo.o: foo.c
|
||||
.Ve
|
||||
.Ip "\fB\-MQ\fR \fItarget\fR" 4
|
||||
.IX Item "-MQ target"
|
||||
Same as \fB\-MT\fR, but it quotes any characters which are special to
|
||||
Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives
|
||||
.Sp
|
||||
.Vb 1
|
||||
\& $$(objpfx)foo.o: foo.c
|
||||
.Ve
|
||||
The default target is automatically quoted, as if it were given with
|
||||
\&\fB\-MQ\fR.
|
||||
.Ip "\fB\-MD\fR \fIfile\fR" 4
|
||||
.IX Item "-MD file"
|
||||
.PD 0
|
||||
.Ip "\fB\-MMD\fR \fIfile\fR" 4
|
||||
.IX Item "-MMD file"
|
||||
.PD
|
||||
\&\fB\-MD\fR \fIfile\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, and
|
||||
\&\fB\-MMD\fR \fIfile\fR is equivalent to \fB\-MM \-MF\fR \fIfile\fR.
|
||||
.Sp
|
||||
Due to limitations in the compiler driver, you must use these switches
|
||||
when you want to generate a dependency file as a side-effect of normal
|
||||
compilation.
|
||||
.Ip "\fB\-x c\fR" 4
|
||||
.IX Item "-x c"
|
||||
.PD 0
|
||||
.Ip "\fB\-x c++\fR" 4
|
||||
.IX Item "-x c++"
|
||||
.Ip "\fB\-x objective-c\fR" 4
|
||||
.IX Item "-x objective-c"
|
||||
.Ip "\fB\-x assembler-with-cpp\fR" 4
|
||||
.IX Item "-x assembler-with-cpp"
|
||||
.PD
|
||||
Specify the source language: C, \*(C+, Objective-C, or assembly. This has
|
||||
nothing to do with standards conformance or extensions; it merely
|
||||
selects which base syntax to expect. If you give none of these options,
|
||||
cpp will deduce the language from the extension of the source file:
|
||||
\&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common
|
||||
extensions for \*(C+ and assembly are also recognized. If cpp does not
|
||||
recognize the extension, it will treat the file as C; this is the most
|
||||
generic mode.
|
||||
.Sp
|
||||
\&\fBNote:\fR Previous versions of cpp accepted a \fB\-lang\fR option
|
||||
which selected both the language and the standards conformance level.
|
||||
This option has been removed, because it conflicts with the \fB\-l\fR
|
||||
option.
|
||||
.Ip "\fB\-std=\fR\fIstandard\fR" 4
|
||||
.IX Item "-std=standard"
|
||||
.PD 0
|
||||
.Ip "\fB\-ansi\fR" 4
|
||||
.IX Item "-ansi"
|
||||
.PD
|
||||
Specify the standard to which the code should conform. Currently cpp
|
||||
only knows about the standards for C; other language standards will be
|
||||
added in the future.
|
||||
.Sp
|
||||
\&\fIstandard\fR
|
||||
may be one of:
|
||||
.RS 4
|
||||
.if n .Ip "\f(CW""""iso9899:1990""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:1990\fR" 4
|
||||
.IX Item "iso9899:1990"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""c89""""\fR" 4
|
||||
.el .Ip "\f(CWc89\fR" 4
|
||||
.IX Item "c89"
|
||||
.PD
|
||||
The \s-1ISO\s0 C standard from 1990. \fBc89\fR is the customary shorthand for
|
||||
this version of the standard.
|
||||
.Sp
|
||||
The \fB\-ansi\fR option is equivalent to \fB\-std=c89\fR.
|
||||
.if n .Ip "\f(CW""""iso9899:199409""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:199409\fR" 4
|
||||
.IX Item "iso9899:199409"
|
||||
The 1990 C standard, as amended in 1994.
|
||||
.if n .Ip "\f(CW""""iso9899:1999""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:1999\fR" 4
|
||||
.IX Item "iso9899:1999"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""c99""""\fR" 4
|
||||
.el .Ip "\f(CWc99\fR" 4
|
||||
.IX Item "c99"
|
||||
.if n .Ip "\f(CW""""iso9899:199x""""\fR" 4
|
||||
.el .Ip "\f(CWiso9899:199x\fR" 4
|
||||
.IX Item "iso9899:199x"
|
||||
.if n .Ip "\f(CW""""c9x""""\fR" 4
|
||||
.el .Ip "\f(CWc9x\fR" 4
|
||||
.IX Item "c9x"
|
||||
.PD
|
||||
The revised \s-1ISO\s0 C standard, published in December 1999. Before
|
||||
publication, this was known as C9X.
|
||||
.if n .Ip "\f(CW""""gnu89""""\fR" 4
|
||||
.el .Ip "\f(CWgnu89\fR" 4
|
||||
.IX Item "gnu89"
|
||||
The 1990 C standard plus \s-1GNU\s0 extensions. This is the default.
|
||||
.if n .Ip "\f(CW""""gnu99""""\fR" 4
|
||||
.el .Ip "\f(CWgnu99\fR" 4
|
||||
.IX Item "gnu99"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""gnu9x""""\fR" 4
|
||||
.el .Ip "\f(CWgnu9x\fR" 4
|
||||
.IX Item "gnu9x"
|
||||
.PD
|
||||
The 1999 C standard plus \s-1GNU\s0 extensions.
|
||||
.RE
|
||||
.RS 4
|
||||
.RE
|
||||
.Ip "\fB\-I-\fR" 4
|
||||
.IX Item "-I-"
|
||||
Split the include path. Any directories specified with \fB\-I\fR
|
||||
options before \fB\-I-\fR are searched only for headers requested with
|
||||
\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for
|
||||
\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are
|
||||
specified with \fB\-I\fR options after the \fB\-I-\fR, those
|
||||
directories are searched for all \fB#include\fR directives.
|
||||
.Sp
|
||||
In addition, \fB\-I-\fR inhibits the use of the directory of the current
|
||||
file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR.
|
||||
.Ip "\fB\-nostdinc\fR" 4
|
||||
.IX Item "-nostdinc"
|
||||
Do not search the standard system directories for header files.
|
||||
Only the directories you have specified with \fB\-I\fR options
|
||||
(and the directory of the current file, if appropriate) are searched.
|
||||
.Ip "\fB\-nostdinc++\fR" 4
|
||||
.IX Item "-nostdinc++"
|
||||
Do not search for header files in the \*(C+\-specific standard directories,
|
||||
but do still search the other standard directories. (This option is
|
||||
used when building the \*(C+ library.)
|
||||
.Ip "\fB\-include\fR \fIfile\fR" 4
|
||||
.IX Item "-include file"
|
||||
Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first
|
||||
line of the primary source file. However, the first directory searched
|
||||
for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR
|
||||
the directory containing the main source file. If not found there, it
|
||||
is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search
|
||||
chain as normal.
|
||||
.Sp
|
||||
If multiple \fB\-include\fR options are given, the files are included
|
||||
in the order they appear on the command line.
|
||||
.Ip "\fB\-imacros\fR \fIfile\fR" 4
|
||||
.IX Item "-imacros file"
|
||||
Exactly like \fB\-include\fR, except that any output produced by
|
||||
scanning \fIfile\fR is thrown away. Macros it defines remain defined.
|
||||
This allows you to acquire all the macros from a header without also
|
||||
processing its declarations.
|
||||
.Sp
|
||||
All files specified by \fB\-imacros\fR are processed before all files
|
||||
specified by \fB\-include\fR.
|
||||
.Ip "\fB\-idirafter\fR \fIdir\fR" 4
|
||||
.IX Item "-idirafter dir"
|
||||
Search \fIdir\fR for header files, but do it \fIafter\fR all
|
||||
directories specified with \fB\-I\fR and the standard system directories
|
||||
have been exhausted. \fIdir\fR is treated as a system include directory.
|
||||
.Ip "\fB\-iprefix\fR \fIprefix\fR" 4
|
||||
.IX Item "-iprefix prefix"
|
||||
Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR
|
||||
options. If the prefix represents a directory, you should include the
|
||||
final \fB/\fR.
|
||||
.Ip "\fB\-iwithprefix\fR \fIdir\fR" 4
|
||||
.IX Item "-iwithprefix dir"
|
||||
.PD 0
|
||||
.Ip "\fB\-iwithprefixbefore\fR \fIdir\fR" 4
|
||||
.IX Item "-iwithprefixbefore dir"
|
||||
.PD
|
||||
Append \fIdir\fR to the prefix specified previously with
|
||||
\&\fB\-iprefix\fR, and add the resulting directory to the include search
|
||||
path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR
|
||||
would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would.
|
||||
.Sp
|
||||
Use of these options is discouraged.
|
||||
.Ip "\fB\-isystem\fR \fIdir\fR" 4
|
||||
.IX Item "-isystem dir"
|
||||
Search \fIdir\fR for header files, after all directories specified by
|
||||
\&\fB\-I\fR but before the standard system directories. Mark it
|
||||
as a system directory, so that it gets the same special treatment as
|
||||
is applied to the standard system directories.
|
||||
.Ip "\fB\-fpreprocessed\fR" 4
|
||||
.IX Item "-fpreprocessed"
|
||||
Indicate to the preprocessor that the input file has already been
|
||||
preprocessed. This suppresses things like macro expansion, trigraph
|
||||
conversion, escaped newline splicing, and processing of most directives.
|
||||
The preprocessor still recognizes and removes comments, so that you can
|
||||
pass a file preprocessed with \fB\-C\fR to the compiler without
|
||||
problems. In this mode the integrated preprocessor is little more than
|
||||
a tokenizer for the front ends.
|
||||
.Sp
|
||||
\&\fB\-fpreprocessed\fR is implicit if the input file has one of the
|
||||
extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the
|
||||
extensions that \s-1GCC\s0 uses for preprocessed files created by
|
||||
\&\fB\-save-temps\fR.
|
||||
.Ip "\fB\-ftabstop=\fR\fIwidth\fR" 4
|
||||
.IX Item "-ftabstop=width"
|
||||
Set the distance between tab stops. This helps the preprocessor report
|
||||
correct column numbers in warnings or errors, even if tabs appear on the
|
||||
line. If the value is less than 1 or greater than 100, the option is
|
||||
ignored. The default is 8.
|
||||
.Ip "\fB\-fno-show-column\fR" 4
|
||||
.IX Item "-fno-show-column"
|
||||
Do not print column numbers in diagnostics. This may be necessary if
|
||||
diagnostics are being scanned by a program that does not understand the
|
||||
column numbers, such as \fBdejagnu\fR.
|
||||
.Ip "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IX Item "-A predicate=answer"
|
||||
Make an assertion with the predicate \fIpredicate\fR and answer
|
||||
\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR
|
||||
\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because
|
||||
it does not use shell special characters.
|
||||
.Ip "\fB\-A -\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4
|
||||
.IX Item "-A -predicate=answer"
|
||||
Cancel an assertion with the predicate \fIpredicate\fR and answer
|
||||
\&\fIanswer\fR.
|
||||
.Ip "\fB\-A-\fR" 4
|
||||
.IX Item "-A-"
|
||||
Cancel all predefined assertions and all assertions preceding it on
|
||||
the command line. Also, undefine all predefined macros and all
|
||||
macros preceding it on the command line. (This is a historical wart and
|
||||
may change in the future.)
|
||||
.Ip "\fB\-dCHARS\fR" 4
|
||||
.IX Item "-dCHARS"
|
||||
\&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters,
|
||||
and must not be preceded by a space. Other characters are reserved for
|
||||
future versions of \s-1GCC\s0, and silently ignored. If you specify characters
|
||||
whose behavior conflicts, the result is undefined.
|
||||
.RS 4
|
||||
.Ip "\fBM\fR" 4
|
||||
.IX Item "M"
|
||||
Instead of the normal output, generate a list of \fB#define\fR
|
||||
directives for all the macros defined during the execution of the
|
||||
preprocessor, including predefined macros. This gives you a way of
|
||||
finding out what is predefined in your version of the preprocessor.
|
||||
Assuming you have no file \fIfoo.h\fR, the command
|
||||
.Sp
|
||||
.Vb 1
|
||||
\& touch foo.h; cpp -dM foo.h
|
||||
.Ve
|
||||
will show all the predefined macros.
|
||||
.Ip "\fBD\fR" 4
|
||||
.IX Item "D"
|
||||
Like \fBM\fR except in two respects: it does \fInot\fR include the
|
||||
predefined macros, and it outputs \fIboth\fR the \fB#define\fR
|
||||
directives and the result of preprocessing. Both kinds of output go to
|
||||
the standard output file.
|
||||
.Ip "\fBN\fR" 4
|
||||
.IX Item "N"
|
||||
Like \fBD\fR, but emit only the macro names, not their expansions.
|
||||
.Ip "\fBI\fR" 4
|
||||
.IX Item "I"
|
||||
Output \fB#include\fR directives in addition to the result of
|
||||
preprocessing.
|
||||
.RE
|
||||
.RS 4
|
||||
.RE
|
||||
.Ip "\fB\-P\fR" 4
|
||||
.IX Item "-P"
|
||||
Inhibit generation of linemarkers in the output from the preprocessor.
|
||||
This might be useful when running the preprocessor on something that is
|
||||
not C code, and will be sent to a program which might be confused by the
|
||||
linemarkers.
|
||||
.Ip "\fB\-C\fR" 4
|
||||
.IX Item "-C"
|
||||
Do not discard comments. All comments are passed through to the output
|
||||
file, except for comments in processed directives, which are deleted
|
||||
along with the directive. Comments appearing in the expansion list of a
|
||||
macro will be preserved, and appear in place wherever the macro is
|
||||
invoked.
|
||||
.Sp
|
||||
You should be prepared for side effects when using \fB\-C\fR; it causes
|
||||
the preprocessor to treat comments as tokens in their own right. For
|
||||
example, macro redefinitions that were trivial when comments were
|
||||
replaced by a single space might become significant when comments are
|
||||
retained. Also, comments appearing at the start of what would be a
|
||||
directive line have the effect of turning that line into an ordinary
|
||||
source line, since the first token on the line is no longer a \fB#\fR.
|
||||
.Ip "\fB\-gcc\fR" 4
|
||||
.IX Item "-gcc"
|
||||
Define the macros _\|_GNUC_\|_, _\|_GNUC_MINOR_\|_ and
|
||||
_\|_GNUC_PATCHLEVEL_\|_. These are defined automatically when you use
|
||||
\&\fBgcc \-E\fR; you can turn them off in that case with
|
||||
\&\fB\-no-gcc\fR.
|
||||
.Ip "\fB\-traditional\fR" 4
|
||||
.IX Item "-traditional"
|
||||
Try to imitate the behavior of old-fashioned C, as opposed to \s-1ISO\s0
|
||||
C.
|
||||
.Ip "\fB\-trigraphs\fR" 4
|
||||
.IX Item "-trigraphs"
|
||||
Process trigraph sequences.
|
||||
.Ip "\fB\-remap\fR" 4
|
||||
.IX Item "-remap"
|
||||
Enable special code to work around file systems which only permit very
|
||||
short file names, such as \s-1MS-DOS\s0.
|
||||
.Ip "\fB\-$\fR" 4
|
||||
.IX Item "-$"
|
||||
Forbid the use of \fB$\fR in identifiers. The C standard allows
|
||||
implementations to define extra characters that can appear in
|
||||
identifiers. By default \s-1GNU\s0 \s-1CPP\s0 permits \fB$\fR, a common extension.
|
||||
.Ip "\fB\-h\fR" 4
|
||||
.IX Item "-h"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--help\fR" 4
|
||||
.IX Item "help"
|
||||
.Ip "\fB\*(--target-help\fR" 4
|
||||
.IX Item "target-help"
|
||||
.PD
|
||||
Print text describing all the command line options instead of
|
||||
preprocessing anything.
|
||||
.Ip "\fB\-v\fR" 4
|
||||
.IX Item "-v"
|
||||
Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of
|
||||
execution, and report the final form of the include path.
|
||||
.Ip "\fB\-H\fR" 4
|
||||
.IX Item "-H"
|
||||
Print the name of each header file used, in addition to other normal
|
||||
activities. Each name is indented to show how deep in the
|
||||
\&\fB#include\fR stack it is.
|
||||
.Ip "\fB\-version\fR" 4
|
||||
.IX Item "-version"
|
||||
.PD 0
|
||||
.Ip "\fB\*(--version\fR" 4
|
||||
.IX Item "version"
|
||||
.PD
|
||||
Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to
|
||||
preprocess as normal. With two dashes, exit immediately.
|
||||
.SH "SEE ALSO"
|
||||
.IX Header "SEE ALSO"
|
||||
\&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and
|
||||
\&\fIbinutils\fR.
|
||||
.SH "COPYRIGHT"
|
||||
.IX Header "COPYRIGHT"
|
||||
Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
|
||||
1997, 1998, 1999, 2000, 2001
|
||||
Free Software Foundation, Inc.
|
||||
.PP
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or
|
||||
any later version published by the Free Software Foundation. A copy of
|
||||
the license is included in the accompanying manual for \s-1GCC\s0, in the
|
||||
section ``\s-1GNU\s0 Free Documentation License''.
|
||||
This manual contains no Invariant Sections, and has no Front-Cover Texts
|
||||
or Back-Cover Texts.
|
||||
8092
gcc/doc/gcc.1
8092
gcc/doc/gcc.1
File diff suppressed because it is too large
Load Diff
406
gcc/doc/gcov.1
406
gcc/doc/gcov.1
@ -1,406 +0,0 @@
|
||||
.\" Automatically generated by Pod::Man version 1.16
|
||||
.\" Mon Jun 25 00:14:36 2001
|
||||
.\"
|
||||
.\" Standard preamble:
|
||||
.\" ======================================================================
|
||||
.de Sh \" Subsection heading
|
||||
.br
|
||||
.if t .Sp
|
||||
.ne 5
|
||||
.PP
|
||||
\fB\\$1\fR
|
||||
.PP
|
||||
..
|
||||
.de Sp \" Vertical space (when we can't use .PP)
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Ip \" List item
|
||||
.br
|
||||
.ie \\n(.$>=3 .ne \\$3
|
||||
.el .ne 3
|
||||
.IP "\\$1" \\$2
|
||||
..
|
||||
.de Vb \" Begin verbatim text
|
||||
.ft CW
|
||||
.nf
|
||||
.ne \\$1
|
||||
..
|
||||
.de Ve \" End verbatim text
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.\" Set up some character translations and predefined strings. \*(-- will
|
||||
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||||
.\" double quote, and \*(R" will give a right double quote. | will give a
|
||||
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
||||
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
||||
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
||||
.tr \(*W-|\(bv\*(Tr
|
||||
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||||
.ie n \{\
|
||||
. ds -- \(*W-
|
||||
. ds PI pi
|
||||
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||||
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||||
. ds L" ""
|
||||
. ds R" ""
|
||||
. ds C` ""
|
||||
. ds C' ""
|
||||
'br\}
|
||||
.el\{\
|
||||
. ds -- \|\(em\|
|
||||
. ds PI \(*p
|
||||
. ds L" ``
|
||||
. ds R" ''
|
||||
'br\}
|
||||
.\"
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr
|
||||
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
||||
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
||||
.\" the output yourself in some meaningful fashion.
|
||||
.if \nF \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
..
|
||||
. nr % 0
|
||||
. rr F
|
||||
.\}
|
||||
.\"
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
||||
.\" makes way too many mistakes in technical documents.
|
||||
.hy 0
|
||||
.if n .na
|
||||
.\"
|
||||
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||||
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||||
.bd B 3
|
||||
. \" fudge factors for nroff and troff
|
||||
.if n \{\
|
||||
. ds #H 0
|
||||
. ds #V .8m
|
||||
. ds #F .3m
|
||||
. ds #[ \f1
|
||||
. ds #] \fP
|
||||
.\}
|
||||
.if t \{\
|
||||
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||||
. ds #V .6m
|
||||
. ds #F 0
|
||||
. ds #[ \&
|
||||
. ds #] \&
|
||||
.\}
|
||||
. \" simple accents for nroff and troff
|
||||
.if n \{\
|
||||
. ds ' \&
|
||||
. ds ` \&
|
||||
. ds ^ \&
|
||||
. ds , \&
|
||||
. ds ~ ~
|
||||
. ds /
|
||||
.\}
|
||||
.if t \{\
|
||||
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||||
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||||
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||||
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||||
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||||
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||||
.\}
|
||||
. \" troff and (daisy-wheel) nroff accents
|
||||
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||||
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||||
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||||
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||||
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||||
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||||
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||||
.ds ae a\h'-(\w'a'u*4/10)'e
|
||||
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||||
. \" corrections for vroff
|
||||
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||||
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||||
. \" for low resolution devices (crt and lpr)
|
||||
.if \n(.H>23 .if \n(.V>19 \
|
||||
\{\
|
||||
. ds : e
|
||||
. ds 8 ss
|
||||
. ds o a
|
||||
. ds d- d\h'-1'\(ga
|
||||
. ds D- D\h'-1'\(hy
|
||||
. ds th \o'bp'
|
||||
. ds Th \o'LP'
|
||||
. ds ae ae
|
||||
. ds Ae AE
|
||||
.\}
|
||||
.rm #[ #] #H #V #F C
|
||||
.\" ======================================================================
|
||||
.\"
|
||||
.IX Title "GCOV 1"
|
||||
.TH GCOV 1 "gcc-3.1" "2001-06-25" "GNU"
|
||||
.UC
|
||||
.SH "NAME"
|
||||
gcov \- coverage testing tool
|
||||
.SH "SYNOPSIS"
|
||||
.IX Header "SYNOPSIS"
|
||||
gcov [\fB\-b\fR] [\fB\-c\fR] [\fB\-v\fR] [\fB\-n\fR] [\fB\-l\fR] [\fB\-f\fR] [\fB\-o\fR \fIdirectory\fR] \fIsourcefile\fR
|
||||
.SH "DESCRIPTION"
|
||||
.IX Header "DESCRIPTION"
|
||||
\&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0
|
||||
to analyze your programs to help create more efficient, faster
|
||||
running code. You can use \fBgcov\fR as a profiling tool to help
|
||||
discover where your optimization efforts will best affect your code. You
|
||||
can also use \fBgcov\fR along with the other profiling tool,
|
||||
\&\fBgprof\fR, to assess which parts of your code use the greatest amount
|
||||
of computing time.
|
||||
.PP
|
||||
Profiling tools help you analyze your code's performance. Using a
|
||||
profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some
|
||||
basic performance statistics, such as:
|
||||
.Ip "\(bu" 4
|
||||
how often each line of code executes
|
||||
.Ip "\(bu" 4
|
||||
what lines of code are actually executed
|
||||
.Ip "\(bu" 4
|
||||
how much computing time each section of code uses
|
||||
.PP
|
||||
Once you know these things about how your code works when compiled, you
|
||||
can look at each module to see which modules should be optimized.
|
||||
\&\fBgcov\fR helps you determine where to work on optimization.
|
||||
.PP
|
||||
Software developers also use coverage testing in concert with
|
||||
testsuites, to make sure software is actually good enough for a release.
|
||||
Testsuites can verify that a program works as expected; a coverage
|
||||
program tests to see how much of the program is exercised by the
|
||||
testsuite. Developers can then determine what kinds of test cases need
|
||||
to be added to the testsuites to create both better testing and a better
|
||||
final product.
|
||||
.PP
|
||||
You should compile your code without optimization if you plan to use
|
||||
\&\fBgcov\fR because the optimization, by combining some lines of code
|
||||
into one function, may not give you as much information as you need to
|
||||
look for `hot spots' where the code is using a great deal of computer
|
||||
time. Likewise, because \fBgcov\fR accumulates statistics by line (at
|
||||
the lowest resolution), it works best with a programming style that
|
||||
places only one statement on each line. If you use complicated macros
|
||||
that expand to loops or to other control structures, the statistics are
|
||||
less helpful\-\-\-they only report on the line where the macro call
|
||||
appears. If your complex macros behave like functions, you can replace
|
||||
them with inline functions to solve this problem.
|
||||
.PP
|
||||
\&\fBgcov\fR creates a logfile called \fI\fIsourcefile\fI.gcov\fR which
|
||||
indicates how many times each line of a source file \fI\fIsourcefile\fI.c\fR
|
||||
has executed. You can use these logfiles along with \fBgprof\fR to aid
|
||||
in fine-tuning the performance of your programs. \fBgprof\fR gives
|
||||
timing information you can use along with the information you get from
|
||||
\&\fBgcov\fR.
|
||||
.PP
|
||||
\&\fBgcov\fR works only on code compiled with \s-1GCC\s0. It is not
|
||||
compatible with any other profiling or test coverage mechanism.
|
||||
.SH "OPTIONS"
|
||||
.IX Header "OPTIONS"
|
||||
.Ip "\fB\-b\fR" 4
|
||||
.IX Item "-b"
|
||||
Write branch frequencies to the output file, and write branch summary
|
||||
info to the standard output. This option allows you to see how often
|
||||
each branch in your program was taken.
|
||||
.Ip "\fB\-c\fR" 4
|
||||
.IX Item "-c"
|
||||
Write branch frequencies as the number of branches taken, rather than
|
||||
the percentage of branches taken.
|
||||
.Ip "\fB\-v\fR" 4
|
||||
.IX Item "-v"
|
||||
Display the \fBgcov\fR version number (on the standard error stream).
|
||||
.Ip "\fB\-n\fR" 4
|
||||
.IX Item "-n"
|
||||
Do not create the \fBgcov\fR output file.
|
||||
.Ip "\fB\-l\fR" 4
|
||||
.IX Item "-l"
|
||||
Create long file names for included source files. For example, if the
|
||||
header file \fIx.h\fR contains code, and was included in the file
|
||||
\&\fIa.c\fR, then running \fBgcov\fR on the file \fIa.c\fR will produce
|
||||
an output file called \fIa.c.x.h.gcov\fR instead of \fIx.h.gcov\fR.
|
||||
This can be useful if \fIx.h\fR is included in multiple source files.
|
||||
.Ip "\fB\-f\fR" 4
|
||||
.IX Item "-f"
|
||||
Output summaries for each function in addition to the file level summary.
|
||||
.Ip "\fB\-o\fR" 4
|
||||
.IX Item "-o"
|
||||
The directory where the object files live. Gcov will search for \fI.bb\fR,
|
||||
\&\fI.bbg\fR, and \fI.da\fR files in this directory.
|
||||
.PP
|
||||
When using \fBgcov\fR, you must first compile your program with two
|
||||
special \s-1GCC\s0 options: \fB\-fprofile-arcs \-ftest-coverage\fR.
|
||||
This tells the compiler to generate additional information needed by
|
||||
gcov (basically a flow graph of the program) and also includes
|
||||
additional code in the object files for generating the extra profiling
|
||||
information needed by gcov. These additional files are placed in the
|
||||
directory where the source code is located.
|
||||
.PP
|
||||
Running the program will cause profile output to be generated. For each
|
||||
source file compiled with \fB\-fprofile-arcs\fR, an accompanying \fI.da\fR
|
||||
file will be placed in the source directory.
|
||||
.PP
|
||||
Running \fBgcov\fR with your program's source file names as arguments
|
||||
will now produce a listing of the code along with frequency of execution
|
||||
for each line. For example, if your program is called \fItmp.c\fR, this
|
||||
is what you see when you use the basic \fBgcov\fR facility:
|
||||
.PP
|
||||
.Vb 5
|
||||
\& $ gcc -fprofile-arcs -ftest-coverage tmp.c
|
||||
\& $ a.out
|
||||
\& $ gcov tmp.c
|
||||
\& 87.50% of 8 source lines executed in file tmp.c
|
||||
\& Creating tmp.c.gcov.
|
||||
.Ve
|
||||
The file \fItmp.c.gcov\fR contains output from \fBgcov\fR.
|
||||
Here is a sample:
|
||||
.PP
|
||||
.Vb 3
|
||||
\& main()
|
||||
\& {
|
||||
\& 1 int i, total;
|
||||
.Ve
|
||||
.Vb 1
|
||||
\& 1 total = 0;
|
||||
.Ve
|
||||
.Vb 2
|
||||
\& 11 for (i = 0; i < 10; i++)
|
||||
\& 10 total += i;
|
||||
.Ve
|
||||
.Vb 5
|
||||
\& 1 if (total != 45)
|
||||
\& ###### printf ("Failure\en");
|
||||
\& else
|
||||
\& 1 printf ("Success\en");
|
||||
\& 1 }
|
||||
.Ve
|
||||
When you use the \fB\-b\fR option, your output looks like this:
|
||||
.PP
|
||||
.Vb 6
|
||||
\& $ gcov -b tmp.c
|
||||
\& 87.50% of 8 source lines executed in file tmp.c
|
||||
\& 80.00% of 5 branches executed in file tmp.c
|
||||
\& 80.00% of 5 branches taken at least once in file tmp.c
|
||||
\& 50.00% of 2 calls executed in file tmp.c
|
||||
\& Creating tmp.c.gcov.
|
||||
.Ve
|
||||
Here is a sample of a resulting \fItmp.c.gcov\fR file:
|
||||
.PP
|
||||
.Vb 3
|
||||
\& main()
|
||||
\& {
|
||||
\& 1 int i, total;
|
||||
.Ve
|
||||
.Vb 1
|
||||
\& 1 total = 0;
|
||||
.Ve
|
||||
.Vb 5
|
||||
\& 11 for (i = 0; i < 10; i++)
|
||||
\& branch 0 taken = 91%
|
||||
\& branch 1 taken = 100%
|
||||
\& branch 2 taken = 100%
|
||||
\& 10 total += i;
|
||||
.Ve
|
||||
.Vb 9
|
||||
\& 1 if (total != 45)
|
||||
\& branch 0 taken = 100%
|
||||
\& ###### printf ("Failure\en");
|
||||
\& call 0 never executed
|
||||
\& branch 1 never executed
|
||||
\& else
|
||||
\& 1 printf ("Success\en");
|
||||
\& call 0 returns = 100%
|
||||
\& 1 }
|
||||
.Ve
|
||||
For each basic block, a line is printed after the last line of the basic
|
||||
block describing the branch or call that ends the basic block. There can
|
||||
be multiple branches and calls listed for a single source line if there
|
||||
are multiple basic blocks that end on that line. In this case, the
|
||||
branches and calls are each given a number. There is no simple way to map
|
||||
these branches and calls back to source constructs. In general, though,
|
||||
the lowest numbered branch or call will correspond to the leftmost construct
|
||||
on the source line.
|
||||
.PP
|
||||
For a branch, if it was executed at least once, then a percentage
|
||||
indicating the number of times the branch was taken divided by the
|
||||
number of times the branch was executed will be printed. Otherwise, the
|
||||
message ``never executed'' is printed.
|
||||
.PP
|
||||
For a call, if it was executed at least once, then a percentage
|
||||
indicating the number of times the call returned divided by the number
|
||||
of times the call was executed will be printed. This will usually be
|
||||
100%, but may be less for functions call \f(CW\*(C`exit\*(C'\fR or \f(CW\*(C`longjmp\*(C'\fR,
|
||||
and thus may not return every time they are called.
|
||||
.PP
|
||||
The execution counts are cumulative. If the example program were
|
||||
executed again without removing the \fI.da\fR file, the count for the
|
||||
number of times each line in the source was executed would be added to
|
||||
the results of the previous run(s). This is potentially useful in
|
||||
several ways. For example, it could be used to accumulate data over a
|
||||
number of program runs as part of a test verification suite, or to
|
||||
provide more accurate long-term information over a large number of
|
||||
program runs.
|
||||
.PP
|
||||
The data in the \fI.da\fR files is saved immediately before the program
|
||||
exits. For each source file compiled with \fB\-fprofile-arcs\fR, the profiling
|
||||
code first attempts to read in an existing \fI.da\fR file; if the file
|
||||
doesn't match the executable (differing number of basic block counts) it
|
||||
will ignore the contents of the file. It then adds in the new execution
|
||||
counts and finally writes the data to the file.
|
||||
.Sh "Using \fBgcov\fP with \s-1GCC\s0 Optimization"
|
||||
.IX Subsection "Using gcov with GCC Optimization"
|
||||
If you plan to use \fBgcov\fR to help optimize your code, you must
|
||||
first compile your program with two special \s-1GCC\s0 options:
|
||||
\&\fB\-fprofile-arcs \-ftest-coverage\fR. Aside from that, you can use any
|
||||
other \s-1GCC\s0 options; but if you want to prove that every single line
|
||||
in your program was executed, you should not compile with optimization
|
||||
at the same time. On some machines the optimizer can eliminate some
|
||||
simple code lines by combining them with other lines. For example, code
|
||||
like this:
|
||||
.PP
|
||||
.Vb 4
|
||||
\& if (a != b)
|
||||
\& c = 1;
|
||||
\& else
|
||||
\& c = 0;
|
||||
.Ve
|
||||
can be compiled into one instruction on some machines. In this case,
|
||||
there is no way for \fBgcov\fR to calculate separate execution counts
|
||||
for each line because there isn't separate code for each line. Hence
|
||||
the \fBgcov\fR output looks like this if you compiled the program with
|
||||
optimization:
|
||||
.PP
|
||||
.Vb 4
|
||||
\& 100 if (a != b)
|
||||
\& 100 c = 1;
|
||||
\& 100 else
|
||||
\& 100 c = 0;
|
||||
.Ve
|
||||
The output shows that this block of code, combined by optimization,
|
||||
executed 100 times. In one sense this result is correct, because there
|
||||
was only one instruction representing all four of these lines. However,
|
||||
the output does not indicate how many times the result was 0 and how
|
||||
many times the result was 1.
|
||||
.SH "SEE ALSO"
|
||||
.IX Header "SEE ALSO"
|
||||
\&\fIgcc\fR\|(1) and the Info entry for \fIgcc\fR.
|
||||
.SH "COPYRIGHT"
|
||||
.IX Header "COPYRIGHT"
|
||||
Copyright (c) 1996, 1997, 1999, 2000 Free Software Foundation, Inc.
|
||||
.PP
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice are
|
||||
preserved on all copies.
|
||||
.PP
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
.PP
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions,
|
||||
except that this permission notice may be included in translations
|
||||
approved by the Free Software Foundation instead of in the original
|
||||
English.
|
||||
Loading…
Reference in New Issue
Block a user