937 lines
40 KiB
Groff
937 lines
40 KiB
Groff
|
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.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. \*(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-
|
||
|
|
.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\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.ie \nF \{\
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. nr % 0
|
||
|
|
. rr F
|
||
|
|
.\}
|
||
|
|
.el \{\
|
||
|
|
. de IX
|
||
|
|
..
|
||
|
|
.\}
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" 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 "2019-10-25" "gcc-9.2.1" "GNU"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.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\-iquote\fR\fIdir\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...]
|
||
|
|
\fIinfile\fR [[\fB\-o\fR] \fIoutfile\fR]
|
||
|
|
.PP
|
||
|
|
Only the most useful options are given above; see below for a more
|
||
|
|
complete list of preprocessor-specific options.
|
||
|
|
In addition, \fBcpp\fR accepts most \fBgcc\fR driver options, which
|
||
|
|
are not listed here. Refer to the \s-1GCC\s0 documentation for details.
|
||
|
|
.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
|
||
|
|
(Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\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=c90\fR, \fB\-std=c99\fR,
|
||
|
|
\&\fB\-std=c11\fR or \fB\-std=c17\fR options, depending
|
||
|
|
on which version of the standard you want. To get all the mandatory
|
||
|
|
diagnostics, you must also use \fB\-pedantic\fR.
|
||
|
|
.PP
|
||
|
|
This manual describes the behavior of the \s-1ISO\s0 preprocessor. To
|
||
|
|
minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's
|
||
|
|
behavior does not conflict with traditional semantics, the
|
||
|
|
traditional preprocessor should behave the same way. The various
|
||
|
|
differences that do exist are detailed in the section \fBTraditional
|
||
|
|
Mode\fR.
|
||
|
|
.PP
|
||
|
|
For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this
|
||
|
|
manual refer to \s-1GNU\s0 \s-1CPP\s0.
|
||
|
|
.SH "OPTIONS"
|
||
|
|
.IX Header "OPTIONS"
|
||
|
|
The \fBcpp\fR command 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. If either file is omitted, it
|
||
|
|
means the same as if \fB\-\fR had been specified for that file.
|
||
|
|
You can also use the \fB\-o\fR \fIoutfile\fR option to specify the
|
||
|
|
output 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(CW1\fR.
|
||
|
|
.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4
|
||
|
|
.IX Item "-D name=definition"
|
||
|
|
The contents of \fIdefinition\fR are tokenized and processed as if
|
||
|
|
they appeared during translation phase three in a \fB#define\fR
|
||
|
|
directive. In particular, the definition is truncated by
|
||
|
|
embedded newline characters.
|
||
|
|
.Sp
|
||
|
|
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.
|
||
|
|
.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 should
|
||
|
|
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.
|
||
|
|
.Sp
|
||
|
|
\&\fB\-D\fR and \fB\-U\fR options are processed in the order they
|
||
|
|
are given on the command line. 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\-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.
|
||
|
|
.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\-undef\fR" 4
|
||
|
|
.IX Item "-undef"
|
||
|
|
Do not predefine any system-specific or GCC-specific macros. The
|
||
|
|
standard predefined macros remain defined.
|
||
|
|
.IP "\fB\-pthread\fR" 4
|
||
|
|
.IX Item "-pthread"
|
||
|
|
Define additional macros required for using the \s-1POSIX\s0 threads library.
|
||
|
|
You should use this option consistently for both compilation and linking.
|
||
|
|
This option is supported on GNU/Linux targets, most other Unix derivatives,
|
||
|
|
and also on x86 Cygwin and MinGW targets.
|
||
|
|
.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 name of the source file with any
|
||
|
|
suffix replaced with object file suffix and with any leading directory
|
||
|
|
parts removed. If there are many included files then the rule is
|
||
|
|
split into several lines using \fB\e\fR\-newline. The rule has no
|
||
|
|
commands.
|
||
|
|
.Sp
|
||
|
|
This option does not suppress the preprocessor's debug output, such as
|
||
|
|
\&\fB\-dM\fR. To avoid mixing such debug output with the dependency
|
||
|
|
rules you should explicitly specify the dependency output file with
|
||
|
|
\&\fB\-MF\fR, or use an environment variable like
|
||
|
|
\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output
|
||
|
|
is still sent to the regular output stream as normal.
|
||
|
|
.Sp
|
||
|
|
Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses
|
||
|
|
warnings with an implicit \fB\-w\fR.
|
||
|
|
.IP "\fB\-MM\fR" 4
|
||
|
|
.IX Item "-MM"
|
||
|
|
Like \fB\-M\fR but do not mention header files that are found in
|
||
|
|
system header directories, nor header files that are included,
|
||
|
|
directly or indirectly, from such a header.
|
||
|
|
.Sp
|
||
|
|
This implies that the choice of angle brackets or double quotes in an
|
||
|
|
\&\fB#include\fR directive does not in itself determine whether that
|
||
|
|
header appears in \fB\-MM\fR dependency output.
|
||
|
|
.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. If no \fB\-MF\fR switch is given
|
||
|
|
the preprocessor sends the rules to the same place it would send
|
||
|
|
preprocessed output.
|
||
|
|
.Sp
|
||
|
|
When used with the driver options \fB\-MD\fR or \fB\-MMD\fR,
|
||
|
|
\&\fB\-MF\fR overrides the default dependency output file.
|
||
|
|
.Sp
|
||
|
|
If \fIfile\fR is \fI\-\fR, then the dependencies are written to \fIstdout\fR.
|
||
|
|
.IP "\fB\-MG\fR" 4
|
||
|
|
.IX Item "-MG"
|
||
|
|
In conjunction with an option such as \fB\-M\fR requesting
|
||
|
|
dependency generation, \fB\-MG\fR assumes missing header files are
|
||
|
|
generated files and adds them to the dependency list without raising
|
||
|
|
an error. The dependency filename is taken directly from the
|
||
|
|
\&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR
|
||
|
|
also suppresses preprocessed output, as a missing header file renders
|
||
|
|
this useless.
|
||
|
|
.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
|
||
|
|
\&
|
||
|
|
\& 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, deletes any
|
||
|
|
directory components and 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 sets 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
|
||
|
|
.Sp
|
||
|
|
The default target is automatically quoted, as if it were given with
|
||
|
|
\&\fB\-MQ\fR.
|
||
|
|
.IP "\fB\-MD\fR" 4
|
||
|
|
.IX Item "-MD"
|
||
|
|
\&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that
|
||
|
|
\&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on
|
||
|
|
whether an \fB\-o\fR option is given. If it is, the driver uses its
|
||
|
|
argument but with a suffix of \fI.d\fR, otherwise it takes the name
|
||
|
|
of the input file, removes any directory components and suffix, and
|
||
|
|
applies a \fI.d\fR suffix.
|
||
|
|
.Sp
|
||
|
|
If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any
|
||
|
|
\&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR
|
||
|
|
is understood to specify a target object file.
|
||
|
|
.Sp
|
||
|
|
Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate
|
||
|
|
a dependency output file as a side effect of the compilation process.
|
||
|
|
.IP "\fB\-MMD\fR" 4
|
||
|
|
.IX Item "-MMD"
|
||
|
|
Like \fB\-MD\fR except mention only user header files, not system
|
||
|
|
header files.
|
||
|
|
.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\-fdirectives\-only\fR" 4
|
||
|
|
.IX Item "-fdirectives-only"
|
||
|
|
When preprocessing, handle directives, but do not expand macros.
|
||
|
|
.Sp
|
||
|
|
The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR
|
||
|
|
options.
|
||
|
|
.Sp
|
||
|
|
With \fB\-E\fR, preprocessing is limited to the handling of directives
|
||
|
|
such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other
|
||
|
|
preprocessor operations, such as macro expansion and trigraph
|
||
|
|
conversion are not performed. In addition, the \fB\-dD\fR option is
|
||
|
|
implicitly enabled.
|
||
|
|
.Sp
|
||
|
|
With \fB\-fpreprocessed\fR, predefinition of command line and most
|
||
|
|
builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are
|
||
|
|
contextually dependent, are handled normally. This enables compilation of
|
||
|
|
files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
|
||
|
|
.Sp
|
||
|
|
With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for
|
||
|
|
\&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of
|
||
|
|
files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR.
|
||
|
|
.IP "\fB\-fdollars\-in\-identifiers\fR" 4
|
||
|
|
.IX Item "-fdollars-in-identifiers"
|
||
|
|
Accept \fB$\fR in identifiers.
|
||
|
|
.IP "\fB\-fextended\-identifiers\fR" 4
|
||
|
|
.IX Item "-fextended-identifiers"
|
||
|
|
Accept universal character names in identifiers. This option is
|
||
|
|
enabled by default for C99 (and later C standard versions) and \*(C+.
|
||
|
|
.IP "\fB\-fno\-canonical\-system\-headers\fR" 4
|
||
|
|
.IX Item "-fno-canonical-system-headers"
|
||
|
|
When preprocessing, do not shorten system header paths with canonicalization.
|
||
|
|
.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\-ftrack\-macro\-expansion\fR[\fB=\fR\fIlevel\fR]" 4
|
||
|
|
.IX Item "-ftrack-macro-expansion[=level]"
|
||
|
|
Track locations of tokens across macro expansions. This allows the
|
||
|
|
compiler to emit diagnostic about the current macro expansion stack
|
||
|
|
when a compilation error occurs in a macro expansion. Using this
|
||
|
|
option makes the preprocessor and the compiler consume more
|
||
|
|
memory. The \fIlevel\fR parameter can be used to choose the level of
|
||
|
|
precision of token location tracking thus decreasing the memory
|
||
|
|
consumption if necessary. Value \fB0\fR of \fIlevel\fR de-activates
|
||
|
|
this option. Value \fB1\fR tracks tokens locations in a
|
||
|
|
degraded mode for the sake of minimal memory overhead. In this mode
|
||
|
|
all tokens resulting from the expansion of an argument of a
|
||
|
|
function-like macro have the same location. Value \fB2\fR tracks
|
||
|
|
tokens locations completely. This value is the most memory hungry.
|
||
|
|
When this option is given no argument, the default parameter value is
|
||
|
|
\&\fB2\fR.
|
||
|
|
.Sp
|
||
|
|
Note that \f(CW\*(C`\-ftrack\-macro\-expansion=2\*(C'\fR is activated by default.
|
||
|
|
.IP "\fB\-fmacro\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR" 4
|
||
|
|
.IX Item "-fmacro-prefix-map=old=new"
|
||
|
|
When preprocessing files residing in directory \fI\fIold\fI\fR,
|
||
|
|
expand the \f(CW\*(C`_\|_FILE_\|_\*(C'\fR and \f(CW\*(C`_\|_BASE_FILE_\|_\*(C'\fR macros as if the
|
||
|
|
files resided in directory \fI\fInew\fI\fR instead. This can be used
|
||
|
|
to change an absolute path to a relative path by using \fI.\fR for
|
||
|
|
\&\fInew\fR which can result in more reproducible builds that are
|
||
|
|
location independent. This option also affects
|
||
|
|
\&\f(CW\*(C`_\|_builtin_FILE()\*(C'\fR during compilation. See also
|
||
|
|
\&\fB\-ffile\-prefix\-map\fR.
|
||
|
|
.IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4
|
||
|
|
.IX Item "-fexec-charset=charset"
|
||
|
|
Set the execution character set, used for string and character
|
||
|
|
constants. The default is \s-1UTF\-8\s0. \fIcharset\fR can be any encoding
|
||
|
|
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
|
||
|
|
.IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4
|
||
|
|
.IX Item "-fwide-exec-charset=charset"
|
||
|
|
Set the wide execution character set, used for wide string and
|
||
|
|
character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16\s0, whichever
|
||
|
|
corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with
|
||
|
|
\&\fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported
|
||
|
|
by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have
|
||
|
|
problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR.
|
||
|
|
.IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4
|
||
|
|
.IX Item "-finput-charset=charset"
|
||
|
|
Set the input character set, used for translation from the character
|
||
|
|
set of the input file to the source character set used by \s-1GCC\s0. If the
|
||
|
|
locale does not specify, or \s-1GCC\s0 cannot get this information from the
|
||
|
|
locale, the default is \s-1UTF\-8\s0. This can be overridden by either the locale
|
||
|
|
or this command-line option. Currently the command-line option takes
|
||
|
|
precedence if there's a conflict. \fIcharset\fR can be any encoding
|
||
|
|
supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine.
|
||
|
|
.IP "\fB\-fworking\-directory\fR" 4
|
||
|
|
.IX Item "-fworking-directory"
|
||
|
|
Enable generation of linemarkers in the preprocessor output that
|
||
|
|
let the compiler know the current working directory at the time of
|
||
|
|
preprocessing. When this option is enabled, the preprocessor
|
||
|
|
emits, after the initial linemarker, a second linemarker with the
|
||
|
|
current working directory followed by two slashes. \s-1GCC\s0 uses this
|
||
|
|
directory, when it's present in the preprocessed input, as the
|
||
|
|
directory emitted as the current working directory in some debugging
|
||
|
|
information formats. This option is implicitly enabled if debugging
|
||
|
|
information is enabled, but this can be inhibited with the negated
|
||
|
|
form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is
|
||
|
|
present in the command line, this option has no effect, since no
|
||
|
|
\&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever.
|
||
|
|
.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\-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.
|
||
|
|
.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, 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\-CC\fR" 4
|
||
|
|
.IX Item "-CC"
|
||
|
|
Do not discard comments, including during macro expansion. This is
|
||
|
|
like \fB\-C\fR, except that comments contained within macros are
|
||
|
|
also passed through to the output file where the macro is expanded.
|
||
|
|
.Sp
|
||
|
|
In addition to the side effects of the \fB\-C\fR option, the
|
||
|
|
\&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro
|
||
|
|
to be converted to C\-style comments. This is to prevent later use
|
||
|
|
of that macro from inadvertently commenting out the remainder of
|
||
|
|
the source line.
|
||
|
|
.Sp
|
||
|
|
The \fB\-CC\fR option is generally used to support lint comments.
|
||
|
|
.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\-traditional\fR" 4
|
||
|
|
.IX Item "-traditional"
|
||
|
|
.PD 0
|
||
|
|
.IP "\fB\-traditional\-cpp\fR" 4
|
||
|
|
.IX Item "-traditional-cpp"
|
||
|
|
.PD
|
||
|
|
Try to imitate the behavior of pre-standard C preprocessors, as
|
||
|
|
opposed to \s-1ISO\s0 C preprocessors.
|
||
|
|
.Sp
|
||
|
|
Note that \s-1GCC\s0 does not otherwise attempt to emulate a pre-standard
|
||
|
|
C compiler, and these options are only supported with the \fB\-E\fR
|
||
|
|
switch, or when invoking \s-1CPP\s0 explicitly.
|
||
|
|
.IP "\fB\-trigraphs\fR" 4
|
||
|
|
.IX Item "-trigraphs"
|
||
|
|
Support \s-1ISO\s0 C trigraphs.
|
||
|
|
These are three-character sequences, all starting with \fB??\fR, that
|
||
|
|
are defined by \s-1ISO\s0 C to stand for single characters. For example,
|
||
|
|
\&\fB??/\fR stands for \fB\e\fR, so \fB'??/n'\fR is a character
|
||
|
|
constant for a newline.
|
||
|
|
.Sp
|
||
|
|
By default, \s-1GCC\s0 ignores trigraphs, but in
|
||
|
|
standard-conforming modes it converts them. See the \fB\-std\fR and
|
||
|
|
\&\fB\-ansi\fR options.
|
||
|
|
.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 MS-DOS.
|
||
|
|
.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. Precompiled header files are also
|
||
|
|
printed, even if they are found to be invalid; an invalid precompiled
|
||
|
|
header file is printed with \fB...x\fR and a valid one with \fB...!\fR .
|
||
|
|
.IP "\fB\-d\fR\fIletters\fR" 4
|
||
|
|
.IX Item "-dletters"
|
||
|
|
Says to make debugging dumps during compilation as specified by
|
||
|
|
\&\fIletters\fR. The flags documented here are those relevant to the
|
||
|
|
preprocessor. Other \fIletters\fR are interpreted
|
||
|
|
by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so
|
||
|
|
are silently ignored. If you specify \fIletters\fR whose behavior
|
||
|
|
conflicts, the result is undefined.
|
||
|
|
.RS 4
|
||
|
|
.IP "\fB\-dM\fR" 4
|
||
|
|
.IX Item "-dM"
|
||
|
|
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
|
||
|
|
.Sp
|
||
|
|
shows all the predefined macros.
|
||
|
|
.IP "\fB\-dD\fR" 4
|
||
|
|
.IX Item "-dD"
|
||
|
|
Like \fB\-dM\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 "\fB\-dN\fR" 4
|
||
|
|
.IX Item "-dN"
|
||
|
|
Like \fB\-dD\fR, but emit only the macro names, not their expansions.
|
||
|
|
.IP "\fB\-dI\fR" 4
|
||
|
|
.IX Item "-dI"
|
||
|
|
Output \fB#include\fR directives in addition to the result of
|
||
|
|
preprocessing.
|
||
|
|
.IP "\fB\-dU\fR" 4
|
||
|
|
.IX Item "-dU"
|
||
|
|
Like \fB\-dD\fR except that only macros that are expanded, or whose
|
||
|
|
definedness is tested in preprocessor directives, are output; the
|
||
|
|
output is delayed until the use or test of the macro; and
|
||
|
|
\&\fB#undef\fR directives are also output for macros tested but
|
||
|
|
undefined at the time.
|
||
|
|
.RE
|
||
|
|
.RS 4
|
||
|
|
.RE
|
||
|
|
.IP "\fB\-fdebug\-cpp\fR" 4
|
||
|
|
.IX Item "-fdebug-cpp"
|
||
|
|
This option is only useful for debugging \s-1GCC\s0. When used from \s-1CPP\s0 or with
|
||
|
|
\&\fB\-E\fR, it dumps debugging information about location maps. Every
|
||
|
|
token in the output is preceded by the dump of the map its location
|
||
|
|
belongs to.
|
||
|
|
.Sp
|
||
|
|
When used from \s-1GCC\s0 without \fB\-E\fR, this option has no effect.
|
||
|
|
.IP "\fB\-I\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-I dir"
|
||
|
|
.PD 0
|
||
|
|
.IP "\fB\-iquote\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-iquote dir"
|
||
|
|
.IP "\fB\-isystem\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-isystem dir"
|
||
|
|
.IP "\fB\-idirafter\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-idirafter dir"
|
||
|
|
.PD
|
||
|
|
Add the directory \fIdir\fR to the list of directories to be searched
|
||
|
|
for header files during preprocessing.
|
||
|
|
.Sp
|
||
|
|
If \fIdir\fR begins with \fB=\fR or \f(CW$SYSROOT\fR, then the \fB=\fR
|
||
|
|
or \f(CW$SYSROOT\fR is replaced by the sysroot prefix; see
|
||
|
|
\&\fB\-\-sysroot\fR and \fB\-isysroot\fR.
|
||
|
|
.Sp
|
||
|
|
Directories specified with \fB\-iquote\fR apply only to the quote
|
||
|
|
form of the directive, \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR.
|
||
|
|
Directories specified with \fB\-I\fR, \fB\-isystem\fR,
|
||
|
|
or \fB\-idirafter\fR apply to lookup for both the
|
||
|
|
\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR and
|
||
|
|
\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR directives.
|
||
|
|
.Sp
|
||
|
|
You can specify any number or combination of these options on the
|
||
|
|
command line to search for header files in several directories.
|
||
|
|
The lookup order is as follows:
|
||
|
|
.RS 4
|
||
|
|
.IP "1." 4
|
||
|
|
.IX Item "1."
|
||
|
|
For the quote form of the include directive, the directory of the current
|
||
|
|
file is searched first.
|
||
|
|
.IP "2." 4
|
||
|
|
.IX Item "2."
|
||
|
|
For the quote form of the include directive, the directories specified
|
||
|
|
by \fB\-iquote\fR options are searched in left-to-right order,
|
||
|
|
as they appear on the command line.
|
||
|
|
.IP "3." 4
|
||
|
|
.IX Item "3."
|
||
|
|
Directories specified with \fB\-I\fR options are scanned in
|
||
|
|
left-to-right order.
|
||
|
|
.IP "4." 4
|
||
|
|
.IX Item "4."
|
||
|
|
Directories specified with \fB\-isystem\fR options are scanned in
|
||
|
|
left-to-right order.
|
||
|
|
.IP "5." 4
|
||
|
|
.IX Item "5."
|
||
|
|
Standard system directories are scanned.
|
||
|
|
.IP "6." 4
|
||
|
|
.IX Item "6."
|
||
|
|
Directories specified with \fB\-idirafter\fR options are scanned in
|
||
|
|
left-to-right order.
|
||
|
|
.RE
|
||
|
|
.RS 4
|
||
|
|
.Sp
|
||
|
|
You can use \fB\-I\fR to override a system header
|
||
|
|
file, substituting your own version, since these directories are
|
||
|
|
searched before the standard system header file directories.
|
||
|
|
However, you should
|
||
|
|
not use this option to add directories that contain vendor-supplied
|
||
|
|
system header files; use \fB\-isystem\fR for that.
|
||
|
|
.Sp
|
||
|
|
The \fB\-isystem\fR and \fB\-idirafter\fR options also mark the directory
|
||
|
|
as a system directory, so that it gets the same special treatment that
|
||
|
|
is applied to the standard system directories.
|
||
|
|
.Sp
|
||
|
|
If a standard system include directory, or a directory specified with
|
||
|
|
\&\fB\-isystem\fR, is also specified with \fB\-I\fR, the \fB\-I\fR
|
||
|
|
option is ignored. The directory is still searched but as a
|
||
|
|
system directory at its normal position in the system include chain.
|
||
|
|
This is to ensure that \s-1GCC\s0's procedure to fix buggy system headers and
|
||
|
|
the ordering for the \f(CW\*(C`#include_next\*(C'\fR directive are not inadvertently
|
||
|
|
changed.
|
||
|
|
If you really need to change the search order for system directories,
|
||
|
|
use the \fB\-nostdinc\fR and/or \fB\-isystem\fR options.
|
||
|
|
.RE
|
||
|
|
.IP "\fB\-I\-\fR" 4
|
||
|
|
.IX Item "-I-"
|
||
|
|
Split the include path.
|
||
|
|
This option has been deprecated. Please use \fB\-iquote\fR instead for
|
||
|
|
\&\fB\-I\fR directories before the \fB\-I\-\fR and remove the \fB\-I\-\fR
|
||
|
|
option.
|
||
|
|
.Sp
|
||
|
|
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. There is no way to override this effect of \fB\-I\-\fR.
|
||
|
|
.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.
|
||
|
|
.IP "\fB\-isysroot\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-isysroot dir"
|
||
|
|
This option is like the \fB\-\-sysroot\fR option, but applies only to
|
||
|
|
header files (except for Darwin targets, where it applies to both header
|
||
|
|
files and libraries). See the \fB\-\-sysroot\fR option for more
|
||
|
|
information.
|
||
|
|
.IP "\fB\-imultilib\fR \fIdir\fR" 4
|
||
|
|
.IX Item "-imultilib dir"
|
||
|
|
Use \fIdir\fR as a subdirectory of the directory containing
|
||
|
|
target-specific \*(C+ headers.
|
||
|
|
.IP "\fB\-nostdinc\fR" 4
|
||
|
|
.IX Item "-nostdinc"
|
||
|
|
Do not search the standard system directories for header files.
|
||
|
|
Only the directories explicitly specified with \fB\-I\fR,
|
||
|
|
\&\fB\-iquote\fR, \fB\-isystem\fR, and/or \fB\-idirafter\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\-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.
|
||
|
|
This warning is enabled by \fB\-Wall\fR.
|
||
|
|
.IP "\fB\-Wtrigraphs\fR" 4
|
||
|
|
.IX Item "-Wtrigraphs"
|
||
|
|
Warn if any trigraphs are encountered that might change the meaning of
|
||
|
|
the program. Trigraphs within comments are not warned about,
|
||
|
|
except those that would form escaped newlines.
|
||
|
|
.Sp
|
||
|
|
This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not
|
||
|
|
given, this option is still enabled unless trigraphs are enabled. To
|
||
|
|
get trigraph conversion without warnings, but get the other
|
||
|
|
\&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR.
|
||
|
|
.IP "\fB\-Wundef\fR" 4
|
||
|
|
.IX Item "-Wundef"
|
||
|
|
Warn if an undefined identifier is evaluated in an \f(CW\*(C`#if\*(C'\fR directive.
|
||
|
|
Such identifiers are replaced with zero.
|
||
|
|
.IP "\fB\-Wexpansion\-to\-defined\fR" 4
|
||
|
|
.IX Item "-Wexpansion-to-defined"
|
||
|
|
Warn whenever \fBdefined\fR is encountered in the expansion of a macro
|
||
|
|
(including the case where the macro is expanded by an \fB#if\fR directive).
|
||
|
|
Such usage is not portable.
|
||
|
|
This warning is also enabled by \fB\-Wpedantic\fR and \fB\-Wextra\fR.
|
||
|
|
.IP "\fB\-Wunused\-macros\fR" 4
|
||
|
|
.IX Item "-Wunused-macros"
|
||
|
|
Warn about macros defined in the main file that are unused. A macro
|
||
|
|
is \fIused\fR if it is expanded or tested for existence at least once.
|
||
|
|
The preprocessor also warns if the macro has not been used at the
|
||
|
|
time it is redefined or undefined.
|
||
|
|
.Sp
|
||
|
|
Built-in macros, macros defined on the command line, and macros
|
||
|
|
defined in include files are not warned about.
|
||
|
|
.Sp
|
||
|
|
\&\fINote:\fR If a macro is actually used, but only used in skipped
|
||
|
|
conditional blocks, then the preprocessor reports it as unused. To avoid the
|
||
|
|
warning in such a case, you might improve the scope of the macro's
|
||
|
|
definition by, for example, moving it into the first skipped block.
|
||
|
|
Alternatively, you could provide a dummy use with something like:
|
||
|
|
.Sp
|
||
|
|
.Vb 2
|
||
|
|
\& #if defined the_macro_causing_the_warning
|
||
|
|
\& #endif
|
||
|
|
.Ve
|
||
|
|
.IP "\fB\-Wno\-endif\-labels\fR" 4
|
||
|
|
.IX Item "-Wno-endif-labels"
|
||
|
|
Do not warn whenever an \f(CW\*(C`#else\*(C'\fR or an \f(CW\*(C`#endif\*(C'\fR are followed by text.
|
||
|
|
This sometimes happens in older programs with code of the form
|
||
|
|
.Sp
|
||
|
|
.Vb 5
|
||
|
|
\& #if FOO
|
||
|
|
\& ...
|
||
|
|
\& #else FOO
|
||
|
|
\& ...
|
||
|
|
\& #endif FOO
|
||
|
|
.Ve
|
||
|
|
.Sp
|
||
|
|
The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments.
|
||
|
|
This warning is on by default.
|
||
|
|
.SH "ENVIRONMENT"
|
||
|
|
.IX Header "ENVIRONMENT"
|
||
|
|
This section describes the environment variables that affect how \s-1CPP\s0
|
||
|
|
operates. You can use them to specify directories or prefixes to use
|
||
|
|
when searching for include files, or to control dependency output.
|
||
|
|
.PP
|
||
|
|
Note that you can also specify places to search using options such as
|
||
|
|
\&\fB\-I\fR, and control dependency output with options like
|
||
|
|
\&\fB\-M\fR. These take precedence over
|
||
|
|
environment variables, which in turn take precedence over the
|
||
|
|
configuration of \s-1GCC\s0.
|
||
|
|
.IP "\fB\s-1CPATH\s0\fR" 4
|
||
|
|
.IX Item "CPATH"
|
||
|
|
.PD 0
|
||
|
|
.IP "\fBC_INCLUDE_PATH\fR" 4
|
||
|
|
.IX Item "C_INCLUDE_PATH"
|
||
|
|
.IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4
|
||
|
|
.IX Item "CPLUS_INCLUDE_PATH"
|
||
|
|
.IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4
|
||
|
|
.IX Item "OBJC_INCLUDE_PATH"
|
||
|
|
.PD
|
||
|
|
Each variable's value is a list of directories separated by a special
|
||
|
|
character, much like \fB\s-1PATH\s0\fR, in which to look for header files.
|
||
|
|
The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and
|
||
|
|
determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a
|
||
|
|
semicolon, and for almost all other targets it is a colon.
|
||
|
|
.Sp
|
||
|
|
\&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if
|
||
|
|
specified with \fB\-I\fR, but after any paths given with \fB\-I\fR
|
||
|
|
options on the command line. This environment variable is used
|
||
|
|
regardless of which language is being preprocessed.
|
||
|
|
.Sp
|
||
|
|
The remaining environment variables apply only when preprocessing the
|
||
|
|
particular language indicated. Each specifies a list of directories
|
||
|
|
to be searched as if specified with \fB\-isystem\fR, but after any
|
||
|
|
paths given with \fB\-isystem\fR options on the command line.
|
||
|
|
.Sp
|
||
|
|
In all these variables, an empty element instructs the compiler to
|
||
|
|
search its current working directory. Empty elements can appear at the
|
||
|
|
beginning or end of a path. For instance, if the value of
|
||
|
|
\&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same
|
||
|
|
effect as \fB\-I.\ \-I/special/include\fR.
|
||
|
|
.IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4
|
||
|
|
.IX Item "DEPENDENCIES_OUTPUT"
|
||
|
|
If this variable is set, its value specifies how to output
|
||
|
|
dependencies for Make based on the non-system header files processed
|
||
|
|
by the compiler. System header files are ignored in the dependency
|
||
|
|
output.
|
||
|
|
.Sp
|
||
|
|
The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in
|
||
|
|
which case the Make rules are written to that file, guessing the target
|
||
|
|
name from the source file name. Or the value can have the form
|
||
|
|
\&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to
|
||
|
|
file \fIfile\fR using \fItarget\fR as the target name.
|
||
|
|
.Sp
|
||
|
|
In other words, this environment variable is equivalent to combining
|
||
|
|
the options \fB\-MM\fR and \fB\-MF\fR,
|
||
|
|
with an optional \fB\-MT\fR switch too.
|
||
|
|
.IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4
|
||
|
|
.IX Item "SUNPRO_DEPENDENCIES"
|
||
|
|
This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above),
|
||
|
|
except that system header files are not ignored, so it implies
|
||
|
|
\&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the
|
||
|
|
main input file is omitted.
|
||
|
|
.IP "\fB\s-1SOURCE_DATE_EPOCH\s0\fR" 4
|
||
|
|
.IX Item "SOURCE_DATE_EPOCH"
|
||
|
|
If this variable is set, its value specifies a \s-1UNIX\s0 timestamp to be
|
||
|
|
used in replacement of the current date and time in the \f(CW\*(C`_\|_DATE_\|_\*(C'\fR
|
||
|
|
and \f(CW\*(C`_\|_TIME_\|_\*(C'\fR macros, so that the embedded timestamps become
|
||
|
|
reproducible.
|
||
|
|
.Sp
|
||
|
|
The value of \fB\s-1SOURCE_DATE_EPOCH\s0\fR must be a \s-1UNIX\s0 timestamp,
|
||
|
|
defined as the number of seconds (excluding leap seconds) since
|
||
|
|
01 Jan 1970 00:00:00 represented in \s-1ASCII\s0; identical to the output of
|
||
|
|
\&\fB\f(CB@command\fB{date +%s\fR} on GNU/Linux and other systems that support the
|
||
|
|
\&\f(CW%s\fR extension in the \f(CW\*(C`date\*(C'\fR command.
|
||
|
|
.Sp
|
||
|
|
The value should be a known timestamp such as the last modification
|
||
|
|
time of the source or package and it should be set by the build
|
||
|
|
process.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7),
|
||
|
|
\&\fIgcc\fR\|(1), and the Info entries for \fIcpp\fR and \fIgcc\fR.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright (c) 1987\-2019 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.3 or
|
||
|
|
any later version published by the Free Software Foundation. A copy of
|
||
|
|
the license is included in the
|
||
|
|
man page \fIgfdl\fR\|(7).
|
||
|
|
This manual contains no Invariant Sections. The Front-Cover Texts are
|
||
|
|
(a) (see below), and the Back-Cover Texts are (b) (see below).
|
||
|
|
.PP
|
||
|
|
(a) The \s-1FSF\s0's Front-Cover Text is:
|
||
|
|
.PP
|
||
|
|
.Vb 1
|
||
|
|
\& A GNU Manual
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
(b) The \s-1FSF\s0's Back-Cover Text is:
|
||
|
|
.PP
|
||
|
|
.Vb 3
|
||
|
|
\& You have freedom to copy and modify this GNU Manual, like GNU
|
||
|
|
\& software. Copies published by the Free Software Foundation raise
|
||
|
|
\& funds for GNU development.
|
||
|
|
.Ve
|