+2016-12-25 Sandra Loosemore <sandra@codesourcery.com>
+
+ * doc/cpp.texi (Invocation): Revise to indicate that GCC driver
+ options are only documented in the GCC manual.
+ * doc/cppopts.texi: Delete documentation of GCC driver options
+ -o, -Wall, -Wtraditional, -Werror, -Wsystem-headers, -w,
+ -pedantic, -pedantic-errors, -std=, -ansi, --help, --target-help,
+ -v, -version. Update -Wcomment, -Wtrigraphs, -Wundef,
+ -Wexpansion-to-defined, -Wno-endif-labels, -traditional,
+ -traditional-cpp, -trigraphs to merge text previously in GCC manual.
+ * doc/invoke.texi (Option Summary): Move -trigraphs, -traditional,
+ and -traditional-cpp from C dialect options to preprocessor options.
+ (C Dialect Options): Likewise.
+ (Warning Options): Delete documentation of -Wcomment, -Wtrigraphs,
+ -Wexpansion-to-defined, -Wundef, and -Wno-endif-labels.
+
2016-12-24 Richard Sandiford <richard.sandiford@arm.com>
* tree-core.h (tree_base): Document the meaning of public_flag
@cindex invocation
@cindex command line
-Most often when you use the C preprocessor you will not have to invoke it
-explicitly: the C compiler will do so automatically. However, the
-preprocessor is sometimes useful on its own. All the options listed
-here are also acceptable to the C compiler and have the same meaning,
-except that the C compiler has different rules for specifying the output
-file.
-
-@emph{Note:} Whether you use the preprocessor by way of @command{gcc}
-or @command{cpp}, the @dfn{compiler driver} is run first. This
-program's purpose is to translate your command into invocations of the
-programs that do the actual work. Their command-line interfaces are
-similar but not identical to the documented interface, and may change
-without notice.
+Most often when you use the C preprocessor you do not have to invoke it
+explicitly: the C compiler does so automatically. However, the
+preprocessor is sometimes useful on its own. You can invoke the
+preprocessor either with the @command{cpp} command, or via @command{gcc -E}.
+In GCC, the preprocessor is actually integrated with the compiler
+rather than a separate program, and both of these commands invoke
+GCC and tell it to stop after the preprocessing phase.
+
+The @command {cpp} options listed here are also accepted by
+@command{gcc} and have the same meaning. Likewise the @command{cpp}
+command accepts all the usual @command{gcc} driver options, although those
+pertaining to compilation phases after preprocessing are ignored.
+
+Only options specific to preprocessing behavior are documented here.
+Refer to the GCC manual for full documentation of other driver options.
@ignore
@c man begin SYNOPSIS
cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
[@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}]
- [@option{-W}@var{warn}@dots{}]
[@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
[@option{-MP}] [@option{-MQ} @var{target}@dots{}]
[@option{-MT} @var{target}@dots{}]
- [@option{-P}] [@option{-fno-working-directory}]
- [@option{-x} @var{language}] [@option{-std=}@var{standard}]
- @var{infile} @var{outfile}
+ @var{infile} [[@option{-o}] @var{outfile}]
-Only the most useful options are listed here; see below for the remainder.
+Only the most useful options are given above; see below for a more
+complete list of preprocessor-specific options.
+In addition, @command{cpp} accepts most @command{gcc} driver options, which
+are not listed here. Refer to the GCC documentation for details.
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7),
-gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and
-@file{binutils}.
+gcc(1), and the Info entries for @file{cpp} and @file{gcc}.
@c man end
@end ignore
@c man begin OPTIONS
-The C preprocessor expects two file names as arguments, @var{infile} and
+The @command{cpp} command expects two file names as arguments, @var{infile} and
@var{outfile}. The preprocessor reads @var{infile} together with any
other files it specifies with @samp{#include}. All the output generated
by the combined input files is written in @var{outfile}.
Either @var{infile} or @var{outfile} may be @option{-}, which as
@var{infile} means to read from standard input and as @var{outfile}
-means to write to standard output. Also, if either file is omitted, it
+means to write to standard output. If either file is omitted, it
means the same as if @option{-} had been specified for that file.
+You can also use the @option{-o @var{outfile}} option to specify the
+output file.
Unless otherwise noted, or the option ends in @samp{=}, all options
which take an argument may have that argument appear either immediately
@w{@samp{-d -M}}.
@cindex options
+
+@table @gcctabopt
@include cppopts.texi
+@end table
@c man end
@node Environment Variables
@c If this file is included with the flag ``cppmanual'' set, it is
@c formatted for inclusion in the CPP manual; otherwise the main GCC manual.
-@table @gcctabopt
@item -D @var{name}
@opindex D
Predefine @var{name} as a macro, with definition @code{1}.
If @var{dir} begins with @code{=}, then the @code{=} will be replaced
by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-@item -o @var{file}
-@opindex o
-Write output to @var{file}. This is the same as specifying @var{file}
-as the second non-option argument to @command{cpp}. @command{gcc} has a
-different interpretation of a second non-option argument, so you must
-use @option{-o} to specify the output file.
-
-@item -Wall
-@opindex Wall
-Turns on all optional warnings which are desirable for normal code.
-At present this is @option{-Wcomment}, @option{-Wtrigraphs},
-@option{-Wmultichar} and a warning about integer promotion causing a
-change of sign in @code{#if} expressions. Note that many of the
-preprocessor's warnings are on by default and have no options to
-control them.
-
@item -Wcomment
@itemx -Wcomments
@opindex Wcomment
@opindex Wcomments
Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
comment, or whenever a backslash-newline appears in a @samp{//} comment.
-(Both forms have the same effect.)
+This warning is enabled by @option{-Wall}.
@item -Wtrigraphs
@opindex Wtrigraphs
@anchor{Wtrigraphs}
-Most trigraphs in comments cannot affect the meaning of the program.
-However, a trigraph that would form an escaped newline (@samp{??/} at
-the end of a line) can, by changing where the comment begins or ends.
-Therefore, only trigraphs that would form escaped newlines produce
-warnings inside a comment.
+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.
This option is implied by @option{-Wall}. If @option{-Wall} is not
given, this option is still enabled unless trigraphs are enabled. To
get trigraph conversion without warnings, but get the other
@option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}.
-@item -Wtraditional
-@opindex Wtraditional
-Warn about certain constructs that behave differently in traditional and
-ISO C@. Also warn about ISO C constructs that have no traditional C
-equivalent, and problematic constructs which should be avoided.
-@ifset cppmanual
-@xref{Traditional Mode}.
-@end ifset
-
@item -Wundef
@opindex Wundef
-Warn whenever an identifier which is not a macro is encountered in an
-@samp{#if} directive, outside of @samp{defined}. Such identifiers are
-replaced with zero.
+@opindex Wno-undef
+Warn if an undefined identifier is evaluated in an @code{#if} directive.
+Such identifiers are replaced with zero.
@item -Wexpansion-to-defined
@opindex Wexpansion-to-defined
Warn whenever @samp{defined} is encountered in the expansion of a macro
(including the case where the macro is expanded by an @samp{#if} directive).
Such usage is not portable.
+This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
@item -Wunused-macros
@opindex Wunused-macros
#endif
@end smallexample
-@item -Wendif-labels
+@item -Wno-endif-labels
+@opindex Wno-endif-labels
@opindex Wendif-labels
-Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
+Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
This usually happens in code of the form
@smallexample
The second and third @code{FOO} should be in comments, but often are not
in older programs. This warning is on by default.
-@item -Werror
-@opindex Werror
-Make all warnings into hard errors. Source code which triggers warnings
-will be rejected.
-
-@item -Wsystem-headers
-@opindex 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.
-
-@item -w
-@opindex w
-Suppress all warnings, including those which GNU CPP issues by default.
-
-@item -pedantic
-@opindex 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.
-
-@item -pedantic-errors
-@opindex pedantic-errors
-Issue all the mandatory diagnostics, and make all mandatory diagnostics
-into errors. This includes mandatory diagnostics that GCC issues
-without @samp{-pedantic} but treats as warnings.
-
@item -M
@opindex M
@cindex @command{make}
This option has been removed, because it conflicts with the @option{-l}
option.
-@item -std=@var{standard}
-@itemx -ansi
-@opindex ansi
-@opindex std=
-Specify the standard to which the code should conform. Currently CPP
-knows about C and C++ standards; others may be added in the future.
-
-@var{standard}
-may be one of:
-@table @code
-@item c90
-@itemx c89
-@itemx iso9899:1990
-The ISO C standard from 1990. @samp{c90} is the customary shorthand for
-this version of the standard.
-
-The @option{-ansi} option is equivalent to @option{-std=c90}.
-
-@item iso9899:199409
-The 1990 C standard, as amended in 1994.
-
-@item iso9899:1999
-@itemx c99
-@itemx iso9899:199x
-@itemx c9x
-The revised ISO C standard, published in December 1999. Before
-publication, this was known as C9X@.
-
-@item iso9899:2011
-@itemx c11
-@itemx c1x
-The revised ISO C standard, published in December 2011. Before
-publication, this was known as C1X@.
-
-@item gnu90
-@itemx gnu89
-The 1990 C standard plus GNU extensions. This is the default.
-
-@item gnu99
-@itemx gnu9x
-The 1999 C standard plus GNU extensions.
-
-@item gnu11
-@itemx gnu1x
-The 2011 C standard plus GNU extensions.
-
-@item c++98
-The 1998 ISO C++ standard plus amendments.
-
-@item gnu++98
-The same as @option{-std=c++98} plus GNU extensions. This is the
-default for C++ code.
-@end table
-
@item -I-
@opindex I-
Split the include path. Any directories specified with @option{-I}
@noindent
will show all the predefined macros.
+@ifclear cppmanual
If you use @option{-dM} without the @option{-E} option, @option{-dM} is
interpreted as a synonym for @option{-fdump-rtl-mach}.
@xref{Developer Options, , ,gcc}.
+@end ifclear
@item D
@opindex dD
The @option{-CC} option is generally used to support lint comments.
-@item -traditional-cpp
+@cindex traditional C language
+@cindex C language, traditional
+@item -traditional
+@itemx -traditional-cpp
@opindex traditional-cpp
-Try to imitate the behavior of old-fashioned C preprocessors, as
+@opindex traditional
+
+Try to imitate the behavior of pre-standard C preprocessors, as
opposed to ISO C preprocessors.
@ifset cppmanual
@xref{Traditional Mode}.
@end ifset
+@ifclear cppmanual
+See the GNU CPP manual for details.
+@end ifclear
+
+Note that GCC does not otherwise attempt to emulate a pre-standard
+C compiler, and these options are only supported with the @option{-E}
+switch, or when invoking CPP explicitly.
@item -trigraphs
@opindex trigraphs
-Process trigraph sequences.
-@ifset cppmanual
-@xref{Initial processing}.
-@end ifset
-@ifclear cppmanual
+Support ISO C trigraphs.
These are three-character sequences, all starting with @samp{??}, that
are defined by ISO C to stand for single characters. For example,
@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character
-constant for a newline. By default, GCC ignores trigraphs, but in
-standard-conforming modes it converts them. See the @option{-std} and
-@option{-ansi} options.
+constant for a newline.
+@ifset cppmanual
+@xref{Initial processing}.
+@end ifset
+@ifclear cppmanual
The nine trigraphs and their replacements are
@smallexample
@end smallexample
@end ifclear
+By default, GCC ignores trigraphs, but in
+standard-conforming modes it converts them. See the @option{-std} and
+@option{-ansi} options.
+
@item -remap
@opindex remap
Enable special code to work around file systems which only permit very
short file names, such as MS-DOS@.
-@item --help
-@itemx --target-help
-@opindex help
-@opindex target-help
-Print text describing all the command-line options instead of
-preprocessing anything.
-
-@item -v
-@opindex v
-Verbose mode. Print out GNU CPP's version number at the beginning of
-execution, and report the final form of the include path.
-
@item -H
@opindex H
Print the name of each header file used, in addition to other normal
printed, even if they are found to be invalid; an invalid precompiled
header file is printed with @samp{...x} and a valid one with @samp{...!} .
-@item -version
-@itemx --version
-@opindex version
-Print out GNU CPP's version number. With one dash, proceed to
-preprocess as normal. With two dashes, exit immediately.
-@end table
-fms-extensions -fplan9-extensions -fsso-struct=@var{endianness}
-fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol
-fsigned-bitfields -fsigned-char @gol
--funsigned-bitfields -funsigned-char @gol
--trigraphs -traditional -traditional-cpp}
+-funsigned-bitfields -funsigned-char}
@item C++ Language Options
@xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
-imultilib @var{dir} -isysroot @var{dir} @gol
-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
-P -fdebug-cpp -ftrack-macro-expansion -fworking-directory @gol
--remap -trigraphs -undef -U@var{macro} @gol
+-remap -traditional -traditional-cpp -trigraphs @gol
+-undef -U@var{macro} @gol
-Wp,@var{option} -Xpreprocessor @var{option} -no-integrated-cpp}
@item Assembler Option
struct/union fields within structs/unions}, for details. This is only
supported for C, not C++.
-@item -trigraphs
-@opindex trigraphs
-Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
-options for strict ISO C conformance) implies @option{-trigraphs}.
-
-@cindex traditional C language
-@cindex C language, traditional
-@item -traditional
-@itemx -traditional-cpp
-@opindex traditional-cpp
-@opindex traditional
-Formerly, these options caused GCC to attempt to emulate a pre-standard
-C compiler. They are now only supported with the @option{-E} switch.
-The preprocessor continues to support a pre-standard mode. See the GNU
-CPP manual for details.
-
@item -fcond-mismatch
@opindex fcond-mismatch
Allow conditional expressions with mismatched types in the second and
machines.
This warning is enabled by @option{-Wall}.
-@item -Wcomment
-@opindex Wcomment
-@opindex Wno-comment
-Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
-comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
-This warning is enabled by @option{-Wall}.
-
@item -Wno-coverage-mismatch
@opindex Wno-coverage-mismatch
Warn if feedback profiles do not match when using the
Warn when @code{__sync_fetch_and_nand} and @code{__sync_nand_and_fetch}
built-in functions are used. These functions changed semantics in GCC 4.4.
-@item -Wtrigraphs
-@opindex Wtrigraphs
-@opindex Wno-trigraphs
-Warn if any trigraphs are encountered that might change the meaning of
-the program (trigraphs within comments are not warned about).
-This warning is enabled by @option{-Wall}.
-
@item -Wunused-but-set-parameter
@opindex Wunused-but-set-parameter
@opindex Wno-unused-but-set-parameter
construct, known from C++, was introduced with ISO C99 and is by default
allowed in GCC@. It is not supported by ISO C90. @xref{Mixed Declarations}.
-@item -Wexpansion-to-defined
-@opindex Wexpansion-to-defined
-Warn whenever @samp{defined} is encountered in the expansion of a macro.
-This warning is also enabled by @option{-Wpedantic} and @option{-Wextra}.
-
-@item -Wundef
-@opindex Wundef
-@opindex Wno-undef
-Warn if an undefined identifier is evaluated in an @code{#if} directive.
-
-@item -Wno-endif-labels
-@opindex Wno-endif-labels
-@opindex Wendif-labels
-Do not warn whenever an @code{#else} or an @code{#endif} are followed by text.
-
@item -Wshadow
@opindex Wshadow
@opindex Wno-shadow
@option{-wrapper} options to specify an alternate preprocessor or
perform additional processing of the program source between
normal preprocessing and compilation.
-@end table
@include cppopts.texi
+@end table
@node Assembler Options
@section Passing Options to the Assembler
projects / gcc.git / commitdiff