+2016-12-27 Sandra Loosemore <sandra@codesourcery.com>
+
+ * doc/cppdiropts.texi, doc/cppwarnopts.texi: New files, split from...
+ * doc/cppopts.texi: .... here.
+ * doc/cpp.texi (Invocation): Adjust includes.
+ * doc/invoke.texi (Option Summary): Add missing preprocesor-related
+ options. Adjust sorting and formatting.
+ (Warning Options): Include cppwarnopts.texi.
+ (Preprocessor Options): Add pointers and list the specific
+ preprocessor options from cppopts.texi first instead of last.
+ (Directory Options): Move/merge documentation of -I, -iquote, and
+ -I- to cppdiropts.texi. Include that file here.
+
2016-12-27 Michael Meissner <meissner@linux.vnet.ibm.com>
* config/rs6000/predicates.md (const_0_to_12_operand): Rename
@table @gcctabopt
@include cppopts.texi
+@include cppdiropts.texi
+@include cppwarnopts.texi
@end table
@c man end
--- /dev/null
+@c Copyright (C) 1999-2016 Free Software Foundation, Inc.
+@c This is part of the CPP and GCC manuals.
+@c For copying conditions, see the file gcc.texi.
+
+@c ---------------------------------------------------------------------
+@c Options affecting include directory search in the preprocessor
+@c ---------------------------------------------------------------------
+
+@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.
+
+@item -I @var{dir}
+@opindex I
+Add the directory @var{dir} to the list of directories to be searched
+for header files.
+@ifset cppmanual
+@xref{Search Path}.
+@end ifset
+If you use more than
+one @option{-I} option, the directories are scanned in left-to-right
+order; the standard system directories come after.
+
+This can be used to override a system header
+file, substituting your own version, since these directories are
+searched before the system header file directories. However, you should
+not use this option to add directories that contain vendor-supplied
+system header files (use @option{-isystem} for that).
+
+If a standard system include directory, or a directory specified with
+@option{-isystem}, is also specified with @option{-I}, the @option{-I}
+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 GCC's procedure to fix buggy system headers and
+the ordering for the @code{include_next} directive are not inadvertently changed.
+If you really need to change the search order for system directories,
+use the @option{-nostdinc} and/or @option{-isystem} options.
+@ifset cppmanual
+@xref{System Headers}.
+@end ifset
+
+If @var{dir} begins with @code{=}, then the @code{=} is replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+@item -iquote @var{dir}
+@opindex iquote
+Search @var{dir} only for header files requested with
+@code{@w{#include "@var{file}"}}; they are not searched for
+@code{@w{#include <@var{file}>}}, before all directories specified by
+@option{-I} and before the standard system directories.
+@ifset cppmanual
+@xref{Search Path}.
+@end ifset
+If @var{dir} begins with @code{=}, then the @code{=} is replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+@item -isystem @var{dir}
+@opindex isystem
+Search @var{dir} for header files, after all directories specified by
+@option{-I} 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.
+@ifset cppmanual
+@xref{System Headers}.
+@end ifset
+If @var{dir} begins with @code{=}, then the @code{=} is replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+@item -I-
+@opindex I-
+Split the include path.
+This option has been deprecated. Please use @option{-iquote} instead for
+@option{-I} directories before the @option{-I-} and remove the @option{-I-}
+option.
+
+Any directories specified with @option{-I}
+options before @option{-I-} are searched only for headers requested with
+@code{@w{#include "@var{file}"}}; they are not searched for
+@code{@w{#include <@var{file}>}}. If additional directories are
+specified with @option{-I} options after the @option{-I-}, those
+directories are searched for all @samp{#include} directives.
+
+In addition, @option{-I-} inhibits the use of the directory of the current
+file directory as the first search directory for @code{@w{#include
+"@var{file}"}}. There is no way to override this effect of @option{-I-}.
+@ifset cppmanual
+@xref{Search Path}.
+@end ifset
+
+@item -idirafter @var{dir}
+@opindex idirafter
+Search @var{dir} for header files, but do it @emph{after} all
+directories specified with @option{-I} and the standard system directories
+have been exhausted. @var{dir} is treated as a system include directory.
+If @var{dir} begins with @code{=}, then the @code{=} will be replaced
+by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
+
+@item -iprefix @var{prefix}
+@opindex iprefix
+Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
+options. If the prefix represents a directory, you should include the
+final @samp{/}.
+
+@item -iwithprefix @var{dir}
+@itemx -iwithprefixbefore @var{dir}
+@opindex iwithprefix
+@opindex iwithprefixbefore
+Append @var{dir} to the prefix specified previously with
+@option{-iprefix}, and add the resulting directory to the include search
+path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
+would; @option{-iwithprefix} puts it where @option{-idirafter} would.
+
+@item -isysroot @var{dir}
+@opindex isysroot
+This option is like the @option{--sysroot} option, but applies only to
+header files (except for Darwin targets, where it applies to both header
+files and libraries). See the @option{--sysroot} option for more
+information.
+
+@item -imultilib @var{dir}
+@opindex imultilib
+Use @var{dir} as a subdirectory of the directory containing
+target-specific C++ headers.
+
+@item -nostdinc
+@opindex nostdinc
+Do not search the standard system directories for header files.
+Only the directories you have specified with @option{-I} options
+(and the directory of the current file, if appropriate) are searched.
+
+@item -nostdinc++
+@opindex 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.)
+
@xref{Standard Predefined Macros}.
@end ifset
-@item -I @var{dir}
-@opindex I
-Add the directory @var{dir} to the list of directories to be searched
-for header files.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-Directories named by @option{-I} are searched before the standard
-system include directories. If the directory @var{dir} is a standard
-system include directory, the option is ignored to ensure that the
-default search order for system directories and the special treatment
-of system headers are not defeated
-@ifset cppmanual
-(@pxref{System Headers})
-@end ifset
-.
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@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.
-This warning is enabled by @option{-Wall}.
-
-@item -Wtrigraphs
-@opindex Wtrigraphs
-@anchor{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.
-
-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 -Wundef
-@opindex Wundef
-@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
-Warn about macros defined in the main file that are unused. A macro
-is @dfn{used} if it is expanded or tested for existence at least once.
-The preprocessor will also warn if the macro has not been used at the
-time it is redefined or undefined.
-
-Built-in macros, macros defined on the command line, and macros
-defined in include files are not warned about.
-
-@emph{Note:} If a macro is actually used, but only used in skipped
-conditional blocks, then CPP will report 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:
-
-@smallexample
-#if defined the_macro_causing_the_warning
-#endif
-@end smallexample
-
-@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.
-This usually happens in code of the form
-
-@smallexample
-#if FOO
-@dots{}
-#else FOO
-@dots{}
-#endif FOO
-@end smallexample
-
-@noindent
-The second and third @code{FOO} should be in comments, but often are not
-in older programs. This warning is on by default.
-
@item -M
@opindex M
@cindex @command{make}
safe to edit the filename if the PCH file is available in a different
location. The filename may be absolute or it may be relative to GCC's
current directory.
-
@end ifclear
-@item -I-
-@opindex I-
-Split the include path. Any directories specified with @option{-I}
-options before @option{-I-} are searched only for headers requested with
-@code{@w{#include "@var{file}"}}; they are not searched for
-@code{@w{#include <@var{file}>}}. If additional directories are
-specified with @option{-I} options after the @option{-I-}, those
-directories are searched for all @samp{#include} directives.
-
-In addition, @option{-I-} inhibits the use of the directory of the current
-file directory as the first search directory for @code{@w{#include
-"@var{file}"}}.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-This option has been deprecated.
-
-@item -nostdinc
-@opindex nostdinc
-Do not search the standard system directories for header files.
-Only the directories you have specified with @option{-I} options
-(and the directory of the current file, if appropriate) are searched.
-
-@item -nostdinc++
-@opindex 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.)
@item -include @var{file}
@opindex include
All files specified by @option{-imacros} are processed before all files
specified by @option{-include}.
-@item -idirafter @var{dir}
-@opindex idirafter
-Search @var{dir} for header files, but do it @emph{after} all
-directories specified with @option{-I} and the standard system directories
-have been exhausted. @var{dir} is treated as a system include directory.
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -iprefix @var{prefix}
-@opindex iprefix
-Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
-options. If the prefix represents a directory, you should include the
-final @samp{/}.
-
-@item -iwithprefix @var{dir}
-@itemx -iwithprefixbefore @var{dir}
-@opindex iwithprefix
-@opindex iwithprefixbefore
-Append @var{dir} to the prefix specified previously with
-@option{-iprefix}, and add the resulting directory to the include search
-path. @option{-iwithprefixbefore} puts it in the same place @option{-I}
-would; @option{-iwithprefix} puts it where @option{-idirafter} would.
-
-@item -isysroot @var{dir}
-@opindex isysroot
-This option is like the @option{--sysroot} option, but applies only to
-header files (except for Darwin targets, where it applies to both header
-files and libraries). See the @option{--sysroot} option for more
-information.
-
-@item -imultilib @var{dir}
-@opindex imultilib
-Use @var{dir} as a subdirectory of the directory containing
-target-specific C++ headers.
-
-@item -isystem @var{dir}
-@opindex isystem
-Search @var{dir} for header files, after all directories specified by
-@option{-I} 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.
-@ifset cppmanual
-@xref{System Headers}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
-@item -iquote @var{dir}
-@opindex iquote
-Search @var{dir} only for header files requested with
-@code{@w{#include "@var{file}"}}; they are not searched for
-@code{@w{#include <@var{file}>}}, before all directories specified by
-@option{-I} and before the standard system directories.
-@ifset cppmanual
-@xref{Search Path}.
-@end ifset
-If @var{dir} begins with @code{=}, then the @code{=} will be replaced
-by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}.
-
@item -fdirectives-only
@opindex fdirectives-only
When preprocessing, handle directives, but do not expand macros.
--- /dev/null
+@c Copyright (C) 1999-2016 Free Software Foundation, Inc.
+@c This is part of the CPP and GCC manuals.
+@c For copying conditions, see the file gcc.texi.
+
+@c ---------------------------------------------------------------------
+@c Options affecting preprocessor warnings
+@c ---------------------------------------------------------------------
+
+@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.
+
+@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.
+This warning is enabled by @option{-Wall}.
+
+@item -Wtrigraphs
+@opindex Wtrigraphs
+@anchor{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.
+
+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 -Wundef
+@opindex Wundef
+@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
+Warn about macros defined in the main file that are unused. A macro
+is @dfn{used} if it is expanded or tested for existence at least once.
+The preprocessor will also warn if the macro has not been used at the
+time it is redefined or undefined.
+
+Built-in macros, macros defined on the command line, and macros
+defined in include files are not warned about.
+
+@emph{Note:} If a macro is actually used, but only used in skipped
+conditional blocks, then CPP will report 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:
+
+@smallexample
+#if defined the_macro_causing_the_warning
+#endif
+@end smallexample
+
+@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.
+This usually happens in code of the form
+
+@smallexample
+#if FOO
+@dots{}
+#else FOO
+@dots{}
+#endif FOO
+@end smallexample
+
+@noindent
+The second and third @code{FOO} should be in comments, but often are not
+in older programs. This warning is on by default.
+
-Wdisabled-optimization @gol
-Wno-discarded-qualifiers -Wno-discarded-array-qualifiers @gol
-Wno-div-by-zero -Wdouble-promotion -Wduplicated-cond @gol
--Wempty-body -Wenum-compare -Wno-endif-labels @gol
+-Wempty-body -Wenum-compare -Wno-endif-labels -Wexpansion-to-defined @gol
-Werror -Werror=* -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
-Wno-format-contains-nul -Wno-format-extra-args -Wformat-length=@var{n} @gol
-Wformat-nonliteral @gol
-Wtype-limits -Wundef @gol
-Wuninitialized -Wunknown-pragmas -Wunsafe-loop-optimizations @gol
-Wunsuffixed-float-constants -Wunused -Wunused-function @gol
--Wunused-label -Wunused-local-typedefs -Wunused-parameter @gol
--Wno-unused-result -Wunused-value @gol -Wunused-variable @gol
+-Wunused-label -Wunused-local-typedefs -Wunused-macros @gol
+-Wunused-parameter -Wno-unused-result @gol
+-Wunused-value -Wunused-variable @gol
-Wunused-const-variable -Wunused-const-variable=@var{n} @gol
-Wunused-but-set-parameter -Wunused-but-set-variable @gol
-Wuseless-cast -Wvariadic-macros -Wvector-operation-performance @gol
@xref{Preprocessor Options,,Options Controlling the Preprocessor}.
@gccoptlist{-A@var{question}=@var{answer} @gol
-A-@var{question}@r{[}=@var{answer}@r{]} @gol
--C -dD -dI -dM -dN @gol
--D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
--idirafter @var{dir} @gol
--include @var{file} -imacros @var{file} @gol
--iprefix @var{file} -iwithprefix @var{dir} @gol
--iwithprefixbefore @var{dir} -isystem @var{dir} @gol
--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 -traditional -traditional-cpp -trigraphs @gol
--undef -U@var{macro} @gol
--Wp,@var{option} -Xpreprocessor @var{option} -no-integrated-cpp}
-
-@item Assembler Option
+-C -CC -D@var{macro}@r{[}=@var{defn}@r{]} @gol
+-dD -dI -dM -dN -dU @gol
+-fdebug-cpp -fdirectives-only -fdollars-in-identifiers @gol
+-fexec-charset=@var{charset} -fextended-identifiers @gol
+-finput-charset=@var{charset} -fno-canonical-system-headers @gol
+-fpch-deps -fpch-preprocess -fpreprocessed @gol
+-ftabstop=@var{width} -ftrack-macro-expansion @gol
+-fwide-exec-charset=@var{charset} -fworking-directory @gol
+-H -imacros @var{file} -include @var{file} @gol
+-M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
+-no-integrated-cpp -P -remap @gol
+-traditional -traditional-cpp -trigraphs @gol
+-U@var{macro} -undef @gol
+-Wp,@var{option} -Xpreprocessor @var{option}}
+
+@item Assembler Options
@xref{Assembler Options,,Passing Options to the Assembler}.
@gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
@item Directory Options
@xref{Directory Options,,Options for Directory Search}.
-@gccoptlist{-B@var{prefix} -I@var{dir} -iplugindir=@var{dir} @gol
--iquote@var{dir} -L@var{dir} -no-canonical-prefixes -I- @gol
---sysroot=@var{dir} --no-sysroot-suffix}
+@gccoptlist{-B@var{prefix} -I@var{dir} -I- @gol
+-idirafter @var{dir} @gol
+-imacros @var{file} -imultilib @var{dir} @gol
+-iplugindir=@var{dir} -iprefix @var{file} @gol
+-iquote @var{dir} -isysroot @var{dir} -isystem @var{dir} @gol
+-iwithprefix @var{dir} -iwithprefixbefore @var{dir} @gol
+-L@var{dir} -no-canonical-prefixes --no-sysroot-suffix @gol
+-nostdinc -nostdinc++ --sysroot=@var{dir}}
@item Code Generation Options
@xref{Code Gen Options,,Options for Code Generation Conventions}.
@code{<} or @code{>=}. This warning is also enabled by
@option{-Wextra}.
+@include cppwarnopts.texi
+
@item -Wbad-function-cast @r{(C and Objective-C only)}
@opindex Wbad-function-cast
@opindex Wno-bad-function-cast
they cause the preprocessor output to be unsuitable for actual
compilation.
+In addition to the options listed here, there are a number of options
+to control search paths for include files documented in
+@ref{Directory Options}.
+Options to control preprocessor diagnostics are listed in
+@ref{Warning Options}.
+
@table @gcctabopt
+@include cppopts.texi
+
@item -Wp,@var{option}
@opindex Wp
You can use @option{-Wp,@var{option}} to bypass the compiler driver
perform additional processing of the program source between
normal preprocessing and compilation.
-@include cppopts.texi
@end table
@node Assembler Options
libraries and for parts of the compiler:
@table @gcctabopt
-@item -I@var{dir}
-@opindex I
-Add the directory @var{dir} to the head of the list of directories to be
-searched for header files. This can be used to override a system header
-file, substituting your own version, since these directories are
-searched before the system header file directories. However, you should
-not use this option to add directories that contain vendor-supplied
-system header files (use @option{-isystem} for that). If you use more than
-one @option{-I} option, the directories are scanned in left-to-right
-order; the standard system directories come after.
-
-If a standard system include directory, or a directory specified with
-@option{-isystem}, is also specified with @option{-I}, the @option{-I}
-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 GCC's procedure to fix buggy system headers and
-the ordering for the @code{include_next} directive are not inadvertently changed.
-If you really need to change the search order for system directories,
-use the @option{-nostdinc} and/or @option{-isystem} options.
+@include cppdiropts.texi
@item -iplugindir=@var{dir}
@opindex iplugindir=
@option{-fplugin=@var{path}/@var{name}.so}. This option is not meant
to be used by the user, but only passed by the driver.
-@item -iquote@var{dir}
-@opindex iquote
-Add the directory @var{dir} to the head of the list of directories to
-be searched for header files only for the case of @code{#include
-"@var{file}"}; they are not searched for @code{#include <@var{file}>},
-otherwise just like @option{-I}.
-
@item -L@var{dir}
@opindex L
Add directory @var{dir} to the list of directories to be searched
@file{@var{dir}/usr/include}. This option disables the addition of
such a suffix.
-@item -I-
-@opindex I-
-This option has been deprecated. Please use @option{-iquote} instead for
-@option{-I} directories before the @option{-I-} and remove the @option{-I-}
-option.
-Any directories you specify with @option{-I} options before the @option{-I-}
-option are searched only for the case of @code{#include "@var{file}"};
-they are not searched for @code{#include <@var{file}>}.
-
-If additional directories are specified with @option{-I} options after
-the @option{-I-} option, these directories are searched for all @code{#include}
-directives. (Ordinarily @emph{all} @option{-I} directories are used
-this way.)
-
-In addition, the @option{-I-} option inhibits the use of the current
-directory (where the current input file came from) as the first search
-directory for @code{#include "@var{file}"}. There is no way to
-override this effect of @option{-I-}. With @option{-I.} you can specify
-searching the directory that is current when the compiler is
-invoked. That is not exactly the same as what the preprocessor does
-by default, but it is often satisfactory.
-
-@option{-I-} does not inhibit the use of the standard system directories
-for header files. Thus, @option{-I-} and @option{-nostdinc} are
-independent.
@end table
@node Code Gen Options
projects / gcc.git / commitdiff