Commit c05169aa by Sandra Loosemore Committed by Sandra Loosemore

cppdiropts.texi, [...]: New files, split from...

2016-12-27  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* 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.

From-SVN: r243954
parent c50fe2da
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
......@@ -4349,6 +4349,8 @@ options may @emph{not} be grouped: @option{-dM} is very different from
@table @gcctabopt
@include cppopts.texi
@include cppdiropts.texi
@include cppwarnopts.texi
@end table
@c man end
......
@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.)
......@@ -47,97 +47,6 @@ standard predefined macros remain defined.
@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}
......@@ -295,36 +204,7 @@ You should not write this @code{#pragma} in your own code, but it is
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
......@@ -348,65 +228,6 @@ processing its declarations.
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.
......
@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.
......@@ -272,7 +272,7 @@ Objective-C and Objective-C++ Dialects}.
-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
......@@ -316,8 +316,9 @@ Objective-C and Objective-C++ Dialects}.
-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
......@@ -463,20 +464,22 @@ Objective-C and Objective-C++ Dialects}.
@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}}
......@@ -493,9 +496,14 @@ Objective-C and Objective-C++ Dialects}.
@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}.
......@@ -5638,6 +5646,8 @@ example, warn if an unsigned variable is compared against zero with
@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
......@@ -11305,7 +11315,15 @@ Some of these options make sense only together with @option{-E} because
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
......@@ -11342,7 +11360,6 @@ This option may be useful in conjunction with the @option{-B} or
perform additional processing of the program source between
normal preprocessing and compilation.
@include cppopts.texi
@end table
@node Assembler Options
......@@ -11712,25 +11729,7 @@ These options specify directories to search for header files, for
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=
......@@ -11739,13 +11738,6 @@ by @option{-fplugin=@var{name}} instead of
@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
......@@ -11826,31 +11818,6 @@ headers may for example be found in
@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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment