Fix preprocessor/5899

Neil Booth neil@daikokuya.demon.co.uk
Sun Mar 10 13:52:00 GMT 2002


Zack Weinberg wrote:-

> We've got support for @set/@clear in texi2pod already, so that part
> should just work.
> 
> @include is going to be a bit trickier, but I think I can see how to
> do it.  Stay tuned.

This patch addresses your points, and also documents the undocumented
"CPATH" environment variable.

Can I apply this, Zack, and assume you'll look into the podulator
issues, where I have little to no clue?  I've applied the cppinit.c
fix to 3.1 and 3.2.

Neil.

	* Makefile.in: Update.
doc:
	* cppenv.texi, cppopts.texi: Split out of cpp.texi and gcc.texi.
	Update documentation.
	* gcc.texi: Include cppopts.texi and cppenv.texi.
	* cpp.texi: Include cppopts.texi and cppenv.texi.

Index: Makefile.in
===================================================================
RCS file: /cvs/gcc/gcc/gcc/Makefile.in,v
retrieving revision 1.830
diff -u -p -r1.830 Makefile.in
--- Makefile.in	2002/02/22 04:42:38	1.830
+++ Makefile.in	2002/03/10 21:46:21
@@ -2260,7 +2260,8 @@ docdir = $(srcdir)/doc
 doc: $(BUILD_INFO) $(GENERATED_MANPAGES) gccbug
 info: $(docdir)/cpp.info $(docdir)/gcc.info $(docdir)/gccint.info lang.info $(docdir)/cppinternals.info
 
-$(docdir)/cpp.info: $(docdir)/cpp.texi $(docdir)/include/fdl.texi
+$(docdir)/cpp.info: $(docdir)/cpp.texi $(docdir)/include/fdl.texi \
+  $(docdir)/cppenv.texi $(docdir)/cppopts.texi
 	cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/cpp.info doc/cpp.texi
 
 $(docdir)/gcc.info: $(docdir)/gcc.texi $(docdir)/include/gcc-common.texi \
@@ -2271,7 +2272,7 @@ $(docdir)/gcc.info: $(docdir)/gcc.texi $
 	 $(docdir)/contribute.texi $(docdir)/vms.texi \
 	 $(docdir)/include/funding.texi $(docdir)/gnu.texi \
 	 $(docdir)/include/gpl.texi $(docdir)/include/fdl.texi \
-	 $(docdir)/contrib.texi
+	 $(docdir)/contrib.texi $(docdir)/cppenv.texi $(docdir)/cppopts.texi
 	cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
 
 $(docdir)/gccint.info: $(docdir)/gccint.texi \
@@ -2295,7 +2296,8 @@ $(docdir)/cppinternals.info: $(docdir)/c
 dvi: gcc.dvi gccint.dvi cpp.dvi lang.dvi cppinternals.dvi
 
 # This works with GNU Make's default rule.
-cpp.dvi: $(docdir)/cpp.texi $(docdir)/include/fdl.texi
+cpp.dvi: $(docdir)/cpp.texi $(docdir)/include/fdl.texi \
+	$(docdir)/cppenv.texi $(docdir)/cppopts.texi
 	$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/cpp.texi
 
 gcc.dvi: $(docdir)/gcc.texi $(docdir)/include/gcc-common.texi \
@@ -2306,7 +2308,7 @@ gcc.dvi: $(docdir)/gcc.texi $(docdir)/in
 	 $(docdir)/contribute.texi $(docdir)/vms.texi \
 	 $(docdir)/include/funding.texi $(docdir)/gnu.texi \
 	 $(docdir)/include/gpl.texi $(docdir)/include/fdl.texi \
-	 $(docdir)/contrib.texi
+	 $(docdir)/contrib.texi $(docdir)/cppenv.texi $(docdir)/cppopts.texi
 	$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
 
 gccint.dvi: $(docdir)/gccint.texi \
Index: doc/cpp.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/cpp.texi,v
retrieving revision 1.24.2.1
diff -u -p -r1.24.2.1 cpp.texi
--- cpp.texi	2002/03/01 22:20:31	1.24.2.1
+++ cpp.texi	2002/03/10 21:46:37
@@ -46,6 +46,12 @@ This manual contains no Invariant Sectio
 @code{\body\}
 @end macro
 
+@c Create a separate index for command line options.
+@defcodeindex op
+
+@c Used in cppopts.texi and cppenv.texi.
+@set cppmanual
+
 @ifinfo
 @dircategory Programming
 @direntry
@@ -88,7 +94,9 @@ useful on its own.
 * Traditional Mode::
 * Implementation Details::
 * Invocation::
+* Environment Variables::
 * GNU Free Documentation License::
+* Option Index::
 * Index of Directives::
 * Concept Index::
 
@@ -3878,475 +3886,38 @@ options may @emph{not} be grouped: @opti
 @w{@samp{-d -M}}.
 
 @cindex options
-@table @gcctabopt
-@item -D @var{name}
-Predefine @var{name} as a macro, with definition @code{1}.
-
-@item -D @var{name}=@var{definition}
-Predefine @var{name} as a macro, with definition @var{definition}.
-There are no restrictions on the contents of @var{definition}, but if
-you are invoking the preprocessor from a shell or shell-like program you
-may need to use the shell's quoting syntax to protect characters such as
-spaces that have a meaning in the shell syntax.  If you use more than
-one @option{-D} for the same @var{name}, the rightmost definition takes
-effect.
-
-If you wish to define a function-like macro on the command line, write
-its argument list with surrounding parentheses before the equals sign
-(if any).  Parentheses are meaningful to most shells, so you will need
-to quote the option.  With @command{sh} and @command{csh},
-@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
-
-@item -U @var{name}
-Cancel any previous definition of @var{name}, either built in or
-provided with a @option{-D} option.
-
-All @option{-imacros @var{file}} and @option{-include @var{file}} options
-are processed after all @option{-D} and @option{-U} options.
-
-@item -undef
-Do not predefine any system-specific macros.  The common predefined
-macros remain defined.
-
-@item -I @var{dir}
-Add the directory @var{dir} to the list of directories to be searched
-for header files.  @xref{Search Path}.  Directories named by @option{-I}
-are searched before the standard system include directories.
-
-It is dangerous to specify a standard system include directory in an
-@option{-I} option.  This defeats the special treatment of system
-headers (@pxref{System Headers}).  It can also defeat the repairs to
-buggy system headers which GCC makes when it is installed.
-
-@item -o @var{file}
-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
-Turns on all optional warnings which are desirable for normal code.  At
-present this is @option{-Wcomment} and @option{-Wtrigraphs}.  Note that
-many of the preprocessor's warnings are on by default and have no
-options to control them.
-
-@item -Wcomment
-@itemx -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.)
-
-@item -Wtrigraphs
-Warn if any trigraphs are encountered.  This option used to take effect
-only if @option{-trigraphs} was also specified, but now works
-independently.  Warnings are not given for trigraphs within comments, as
-they do not affect the meaning of the program.
-
-@item -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.
-@xref{Traditional Mode}.
-
-@item -Wimport
-Warn the first time @samp{#import} is used.
-
-@item -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.
-
-@item -Werror
-Make all warnings into hard errors.  Source code which triggers warnings
-will be rejected.
-
-@item -Wsystem-headers
-Issue warnings for code in system headers.  These are normally unhelpful
-in finding bugs in your own code, therefore suppressed.  If you are
-responsible for the system library, you may want to see them.
-
-@item -w
-Suppress all warnings, including those which GNU CPP issues by default.
-
-@item -pedantic
-Issue all the mandatory diagnostics listed in the C standard.  Some of
-them are left out by default, since they trigger frequently on harmless
-code.
-
-@item -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
-Instead of outputting the result of preprocessing, output a rule
-suitable for @command{make} describing the dependencies of the main
-source file.  The preprocessor outputs one @command{make} rule containing
-the object file name for that source file, a colon, and the names of all
-the included files, including those coming from @option{-include} or
-@option{-imacros} command line options.
-
-Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
-object file name consists of the basename of the source file with any
-suffix replaced with object file suffix.  If there are many included
-files then the rule is split into several lines using @samp{\}-newline.
-The rule has no commands.
-
-Passing @option{-M} to the driver implies @option{-E}.
-
-@item -MM
-Like @option{-M} 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.
-
-This implies that the choice of angle brackets or double quotes in an
-@samp{#include} directive does not in itself determine whether that
-header will appear in @option{-MM} dependency output.  This is a
-slight change in semantics from GCC versions 3.0 and earlier.
-
-@item -MF @var{file}
-@anchor{-MF}
-When used with @option{-M} or @option{-MM}, specifies a
-file to write the dependencies to.  If no @option{-MF} switch is given
-the preprocessor sends the rules to the same place it would have sent
-preprocessed output.
-
-When used with the driver options @option{-MD} or @option{-MMD},
-@option{-MF} overrides the default dependency output file.
-
-@item -MG
-When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
-header files as generated files and assume they live in the same
-directory as the source file.  It suppresses preprocessed output, as a
-missing header file is ordinarily an error.
-
-This feature is used in automatic updating of makefiles.
-
-@item -MP
-This option instructs CPP 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 @command{make} gives if you remove header
-files without updating the @file{Makefile} to match.
-
-This is typical output:
-
-@example
-test.o: test.c test.h
-
-test.h:
-@end example
-
-@item -MT @var{target}
-
-Change the target of the rule emitted by dependency generation.  By
-default CPP takes the name of the main input file, including any path,
-deletes any file suffix such as @samp{.c}, and appends the platform's
-usual object suffix.  The result is the target.
-
-An @option{-MT} option will set the target to be exactly the string you
-specify.  If you want multiple targets, you can specify them as a single
-argument to @option{-MT}, or use multiple @option{-MT} options.
-
-For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
-
-@example
-$(objpfx)foo.o: foo.c
-@end example
-
-@item -MQ @var{target}
-
-Same as @option{-MT}, but it quotes any characters which are special to
-Make.  @option{@w{-MQ '$(objpfx)foo.o'}} gives
-
-@example
-$$(objpfx)foo.o: foo.c
-@end example
-
-The default target is automatically quoted, as if it were given with
-@option{-MQ}.
-
-@item -MD
-@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
-@option{-E} is not implied.  The driver determines @var{file} based on
-whether an @option{-o} option is given.  If it is, the driver uses its
-argument but with a suffix of @file{.d}, otherwise it take the
-basename of the input file and applies a @file{.d} suffix.
-
-If @option{-MD} is used in conjunction with @option{-E}, any
-@option{-o} switch is understood to specify the dependency output file
-(but @pxref{-MF}), but if used without @option{-E}, each @option{-o}
-is understood to specify a target object file.
-
-Since @option{-E} is not implied, @option{-MD} can be used to generate
-a dependency output file as a side-effect of the compilation process.
-
-@item -MMD
-Like @option{-MD} except mention only user header files, not system
--header files.
-
-@item -x c
-@itemx -x c++
-@itemx -x objective-c
-@itemx -x assembler-with-cpp
-Specify the source language: C, C++, Objective-C, or assembly.  This has
-nothing to do with standards conformance or extensions; it merely
-selects which base syntax to expect.  If you give none of these options,
-cpp will deduce the language from the extension of the source file:
-@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}.  Some other common
-extensions for C++ and assembly are also recognized.  If cpp does not
-recognize the extension, it will treat the file as C; this is the most
-generic mode.
-
-@strong{Note:} Previous versions of cpp accepted a @option{-lang} option
-which selected both the language and the standards conformance level.
-This option has been removed, because it conflicts with the @option{-l}
-option.
-
-@item -std=@var{standard}
-@itemx -ansi
-Specify the standard to which the code should conform.  Currently cpp
-only knows about the standards for C; other language standards will be
-added in the future.
-
-@var{standard}
-may be one of:
-@table @code
-@item iso9899:1990
-@itemx c89
-The ISO C standard from 1990.  @samp{c89} is the customary shorthand for
-this version of the standard.
-
-The @option{-ansi} option is equivalent to @option{-std=c89}.
-
-@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 gnu89
-The 1990 C standard plus GNU extensions.  This is the default.
-
-@item gnu99
-@itemx gnu9x
-The 1999 C standard plus GNU extensions.
-@end table
-
-@item -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}"}}.  @xref{Search Path}.
-
-@item -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++
-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}
-
-Process @var{file} as if @code{#include "file"} appeared as the first
-line of the primary source file.  However, the first directory searched
-for @var{file} is the preprocessor's working directory @emph{instead of}
-the directory containing the main source file.  If not found there, it
-is searched for in the remainder of the @code{#include "@dots{}"} search
-chain as normal.
-
-If multiple @option{-include} options are given, the files are included
-in the order they appear on the command line.
-
-@item -imacros @var{file}
-
-Exactly like @option{-include}, except that any output produced by
-scanning @var{file} is thrown away.  Macros it defines remain defined.
-This allows you to acquire all the macros from a header without also
-processing its declarations.
-
-All files specified by @option{-imacros} are processed before all files
-specified by @option{-include}.
-
-@item -idirafter @var{dir}
-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.
-
-@item -iprefix @var{prefix}
-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}
-
-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.
-
-Use of these options is discouraged.
-
-@item -isystem @var{dir}
-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.  @xref{System Headers}.
-
-@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 @option{-C} to the compiler without
-problems.  In this mode the integrated preprocessor is little more than
-a tokenizer for the front ends.
-
-@option{-fpreprocessed} is implicit if the input file has one of the
-extensions @samp{.i}, @samp{.ii} or @samp{.mi}.  These are the
-extensions that GCC uses for preprocessed files created by
-@option{-save-temps}.
-
-@item -ftabstop=@var{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.
-
-@item -fno-show-column
-Do not print column numbers in diagnostics.  This may be necessary if
-diagnostics are being scanned by a program that does not understand the
-column numbers, such as @command{dejagnu}.
-
-@item -A @var{predicate}=@var{answer}
-Make an assertion with the predicate @var{predicate} and answer
-@var{answer}.  This form is preferred to the older form @option{-A
-@var{predicate}(@var{answer})}, which is still supported, because
-it does not use shell special characters.  @xref{Assertions}.
-
-@item -A -@var{predicate}=@var{answer}
-Cancel an assertion with the predicate @var{predicate} and answer
-@var{answer}.
-
-@item -A-
-Cancel all predefined assertions and all assertions preceding it on
-the command line.  Also, undefine all predefined macros and all
-macros preceding it on the command line.  (This is a historical wart and
-may change in the future.)
-
-@item -dCHARS
-@var{CHARS} is a sequence of one or more of the following characters,
-and must not be preceded by a space.  Other characters are interpreted
-by the compiler proper, or reserved for future versions of GCC, and so
-are silently ignored.  If you specify characters whose behavior
-conflicts, the result is undefined.
-
-@table @samp
-@item M
-Instead of the normal output, generate a list of @samp{#define}
-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 @file{foo.h}, the command
-
-@example
-touch foo.h; cpp -dM foo.h
-@end example
-
-@noindent
-will show all the predefined macros.
-
-@item D
-Like @samp{M} except in two respects: it does @emph{not} include the
-predefined macros, and it outputs @emph{both} the @samp{#define}
-directives and the result of preprocessing.  Both kinds of output go to
-the standard output file.
-
-@item N
-Like @samp{D}, but emit only the macro names, not their expansions.
+@include cppopts.texi
+@c man end
 
-@item I
-Output @samp{#include} directives in addition to the result of
-preprocessing.
-@end table
+@node Environment Variables
+@chapter Environment Variables
+@cindex environment variables
+@c man begin ENVIRONMENT
+
+This section describes the environment variables that affect how CPP
+operates.  You can use them to specify directories or prefixes to use
+when searching for include files, or to control dependency output.
+
+Note that you can also specify places to search using options such as
+@option{-I}, and control dependency output with options like
+@option{-M} (@pxref{Invocation}).  These take precedence over
+environment variables, which in turn take precedence over the
+configuration of GCC@.
 
-@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.  @xref{Preprocessor Output}.
-
-@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.
-
-You should be prepared for side effects when using @option{-C}; 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 @samp{#}.
-
-@item -gcc
-Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and
-@sc{__gnuc_patchlevel__}.  These are defined automatically when you use
-@command{gcc -E}; you can turn them off in that case with
-@option{-no-gcc}.
-
-@item -traditional
-Try to imitate the behavior of old-fashioned C, as opposed to ISO
-C@.  @xref{Traditional Mode}.
-
-@item -trigraphs
-Process trigraph sequences.  @xref{Initial processing}.
-
-@item -remap
-Enable special code to work around file systems which only permit very
-short file names, such as MS-DOS@.
-
-@item -$
-Forbid the use of @samp{$} in identifiers.  The C standard allows
-implementations to define extra characters that can appear in
-identifiers.  By default GNU CPP permits @samp{$}, a common extension.
-
-@item -h
-@itemx --help
-@itemx --target-help
-Print text describing all the command line options instead of
-preprocessing anything.
-
-@item -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
-Print the name of each header file used, in addition to other normal
-activities.  Each name is indented to show how deep in the
-@samp{#include} stack it is.
-
-@item -version
-@itemx --version
-Print out GNU CPP's version number.  With one dash, proceed to
-preprocess as normal.  With two dashes, exit immediately.
-@end table
+@include cppenv.texi
 @c man end
 
 @include fdl.texi
 
 @page
+@node Option Index
+@unnumbered Option Index
+
+CPP's command line options are indexed here without any initial
+@samp{-} or @samp{--}.
+
+@printindex op
+
 @node Index of Directives
 @unnumbered Index of Directives
 @printindex fn
Index: doc/cppenv.texi
===================================================================
RCS file: cppenv.texi
diff -N cppenv.texi
--- /dev/null	Tue May  5 13:32:27 1998
+++ cppenv.texi	Sun Mar 10 13:46:37 2002
@@ -0,0 +1,76 @@
+@c Copyright (c) 1999, 2000, 2001, 2002
+@c 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 Environment variables affecting 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.
+
+@ftable @env
+@item CPATH
+@itemx C_INCLUDE_PATH
+@itemx CPLUS_INCLUDE_PATH
+@itemx OBJC_INCLUDE_PATH
+@c Commented out until ObjC++ is part of GCC:
+@c @itemx OBJCPLUS_INCLUDE_PATH
+Each variable's value is a list of directories separated by a special
+character, much like @env{PATH}, in which to look for header files.
+The special character, @code{PATH_SEPARATOR}, is target-dependent and
+determined at GCC build time.  For Windows-based targets it is a
+semicolon, and for almost all other targets it is a colon.
+
+@env{CPATH} specifies a list of directories to be searched as if
+specified with @option{-I}, but after any paths given with @option{-I}
+options on the command line.  The environment variable is used
+regardless of which language is being preprocessed.
+
+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 @option{-isystem}, but after any
+paths given with @option{-isystem} options on the command line.
+
+@ifset cppmanual
+See also @ref{Search Path}.
+@end ifset
+
+@item DEPENDENCIES_OUTPUT
+@anchor{DEPENDENCIES_OUTPUT}
+@cindex dependencies for make as 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.
+
+The value of @env{DEPENDENCIES_OUTPUT} 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
+@samp{@var{file} @var{target}}, in which case the rules are written to
+file @var{file} using @var{target} as the target name.
+
+In other words, this environment variable is equivalent to combining
+the options @option{-MM} and @option{-MF}
+@ifset cppmanual
+(@pxref{Invocation}),
+@end ifset
+@ifclear cppmanual
+(@pxref{Preprocessor Options}),
+@end ifclear
+with an optional @option{-MT} switch too.
+
+@item SUNPRO_DEPENDENCIES
+@cindex dependencies for make as output
+This variable is the same as the environment variable
+@env{DEPENDENCIES_OUTPUT} (@pxref{DEPENDENCIES_OUTPUT}), except that
+system header files are not ignored, so it implies @option{-M} rather
+than @option{-MM}.
+@ifset cppmanual
+@xref{Invocation}.
+@end ifset
+@ifclear cppmanual
+@xref{Preprocessor Options}.
+@end ifclear
+@end ftable
Index: doc/cppopts.texi
===================================================================
RCS file: cppopts.texi
diff -N cppopts.texi
--- /dev/null	Tue May  5 13:32:27 1998
+++ cppopts.texi	Sun Mar 10 13:46:38 2002
@@ -0,0 +1,586 @@
+@c Copyright (c) 1999, 2000, 2001, 2002
+@c 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 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.
+
+@table @gcctabopt
+@item -D @var{name}
+@opindex D
+Predefine @var{name} as a macro, with definition @code{1}.
+
+@item -D @var{name}=@var{definition}
+Predefine @var{name} as a macro, with definition @var{definition}.
+There are no restrictions on the contents of @var{definition}, but if
+you are invoking the preprocessor from a shell or shell-like program you
+may need to use the shell's quoting syntax to protect characters such as
+spaces that have a meaning in the shell syntax.
+
+If you wish to define a function-like macro on the command line, write
+its argument list with surrounding parentheses before the equals sign
+(if any).  Parentheses are meaningful to most shells, so you will need
+to quote the option.  With @command{sh} and @command{csh},
+@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works.
+
+@option{-D} and @option{-U} options are processed in the order they
+are given on the command line.  All @option{-imacros @var{file}} and
+@option{-include @var{file}} options are processed after all
+@option{-D} and @option{-U} options.
+
+@item -U @var{name}
+@opindex U
+Cancel any previous definition of @var{name}, either built in or
+provided with a @option{-D} option.
+
+@item -undef
+@opindex undef
+Do not predefine any system-specific macros.  The common predefined
+macros remain defined.
+
+@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.
+
+It is dangerous to specify a standard system include directory in an
+@option{-I} option.  This defeats the special treatment of system
+headers
+@ifset cppmanual
+(@pxref{System Headers})
+@end ifset
+.  It can also defeat the repairs to buggy system headers which GCC
+makes when it is installed.
+
+@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} and @option{-Wtrigraphs}.  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.)
+
+@item -Wtrigraphs
+@opindex Wtrigraphs
+Warn if any trigraphs are encountered.  This option used to take effect
+only if @option{-trigraphs} was also specified, but now works
+independently.  Warnings are not given for trigraphs within comments, as
+they do not affect the meaning of the program.
+
+@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 -Wimport
+@opindex Wimport
+Warn the first time @samp{#import} is used.
+
+@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.
+
+@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 make
+@cindex dependencies, make
+Instead of outputting the result of preprocessing, output a rule
+suitable for @command{make} describing the dependencies of the main
+source file.  The preprocessor outputs one @command{make} rule containing
+the object file name for that source file, a colon, and the names of all
+the included files, including those coming from @option{-include} or
+@option{-imacros} command line options.
+
+Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
+object file name consists of the basename of the source file with any
+suffix replaced with object file suffix.  If there are many included
+files then the rule is split into several lines using @samp{\}-newline.
+The rule has no commands.
+
+This option does not suppress the preprocessor's debug output, such as
+@option{-dM}.  To avoid mixing such debug output with the dependency
+rules you should explicitly specify the dependency output file with
+@option{-MF}, or use an environment variable like
+@env{DEPENDENCIES_OUTPUT} (@pxref{DEPENDENCIES_OUTPUT}).  Debug output
+will still be sent to the regular output stream as normal.
+
+Passing @option{-M} to the driver implies @option{-E}.
+
+@item -MM
+@opindex MM
+Like @option{-M} 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.
+
+This implies that the choice of angle brackets or double quotes in an
+@samp{#include} directive does not in itself determine whether that
+header will appear in @option{-MM} dependency output.  This is a
+slight change in semantics from GCC versions 3.0 and earlier.
+
+@item -MF @var{file}
+@opindex MF
+@anchor{-MF}
+When used with @option{-M} or @option{-MM}, specifies a
+file to write the dependencies to.  If no @option{-MF} switch is given
+the preprocessor sends the rules to the same place it would have sent
+preprocessed output.
+
+When used with the driver options @option{-MD} or @option{-MMD},
+@option{-MF} overrides the default dependency output file.
+
+@item -MG
+@opindex MG
+When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
+header files as generated files and assume they live in the same
+directory as the source file.  It suppresses preprocessed output, as a
+missing header file is ordinarily an error.
+
+This feature is used in automatic updating of makefiles.
+
+@item -MP
+@opindex MP
+This option instructs CPP 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 @command{make} gives if you remove header
+files without updating the @file{Makefile} to match.
+
+This is typical output:
+
+@example
+test.o: test.c test.h
+
+test.h:
+@end example
+
+@item -MT @var{target}
+@opindex MT
+
+Change the target of the rule emitted by dependency generation.  By
+default CPP takes the name of the main input file, including any path,
+deletes any file suffix such as @samp{.c}, and appends the platform's
+usual object suffix.  The result is the target.
+
+An @option{-MT} option will set the target to be exactly the string you
+specify.  If you want multiple targets, you can specify them as a single
+argument to @option{-MT}, or use multiple @option{-MT} options.
+
+For example, @option{@w{-MT '$(objpfx)foo.o'}} might give
+
+@example
+$(objpfx)foo.o: foo.c
+@end example
+
+@item -MQ @var{target}
+@opindex MQ
+
+Same as @option{-MT}, but it quotes any characters which are special to
+Make.  @option{@w{-MQ '$(objpfx)foo.o'}} gives
+
+@example
+$$(objpfx)foo.o: foo.c
+@end example
+
+The default target is automatically quoted, as if it were given with
+@option{-MQ}.
+
+@item -MD
+@opindex MD
+@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
+@option{-E} is not implied.  The driver determines @var{file} based on
+whether an @option{-o} option is given.  If it is, the driver uses its
+argument but with a suffix of @file{.d}, otherwise it take the
+basename of the input file and applies a @file{.d} suffix.
+
+If @option{-MD} is used in conjunction with @option{-E}, any
+@option{-o} switch is understood to specify the dependency output file
+(but @pxref{-MF}), but if used without @option{-E}, each @option{-o}
+is understood to specify a target object file.
+
+Since @option{-E} is not implied, @option{-MD} can be used to generate
+a dependency output file as a side-effect of the compilation process.
+
+@item -MMD
+@opindex MMD
+Like @option{-MD} except mention only user header files, not system
+-header files.
+
+@item -x c
+@itemx -x c++
+@itemx -x objective-c
+@itemx -x assembler-with-cpp
+@opindex x
+Specify the source language: C, C++, Objective-C, or assembly.  This has
+nothing to do with standards conformance or extensions; it merely
+selects which base syntax to expect.  If you give none of these options,
+cpp will deduce the language from the extension of the source file:
+@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}.  Some other common
+extensions for C++ and assembly are also recognized.  If cpp does not
+recognize the extension, it will treat the file as C; this is the most
+generic mode.
+
+@strong{Note:} Previous versions of cpp accepted a @option{-lang} option
+which selected both the language and the standards conformance level.
+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
+only knows about the standards for C; other language standards will be
+added in the future.
+
+@var{standard}
+may be one of:
+@table @code
+@item iso9899:1990
+@itemx c89
+The ISO C standard from 1990.  @samp{c89} is the customary shorthand for
+this version of the standard.
+
+The @option{-ansi} option is equivalent to @option{-std=c89}.
+
+@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 gnu89
+The 1990 C standard plus GNU extensions.  This is the default.
+
+@item gnu99
+@itemx gnu9x
+The 1999 C standard plus GNU extensions.
+@end table
+
+@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
+
+@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
+Process @var{file} as if @code{#include "file"} appeared as the first
+line of the primary source file.  However, the first directory searched
+for @var{file} is the preprocessor's working directory @emph{instead of}
+the directory containing the main source file.  If not found there, it
+is searched for in the remainder of the @code{#include "@dots{}"} search
+chain as normal.
+
+If multiple @option{-include} options are given, the files are included
+in the order they appear on the command line.
+
+@item -imacros @var{file}
+@opindex imacros
+Exactly like @option{-include}, except that any output produced by
+scanning @var{file} is thrown away.  Macros it defines remain defined.
+This allows you to acquire all the macros from a header without also
+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.
+
+@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.
+
+Use of these options is discouraged.
+
+@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
+
+@item -fpreprocessed
+@opindex 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 @option{-C} to the compiler without
+problems.  In this mode the integrated preprocessor is little more than
+a tokenizer for the front ends.
+
+@option{-fpreprocessed} is implicit if the input file has one of the
+extensions @samp{.i}, @samp{.ii} or @samp{.mi}.  These are the
+extensions that GCC uses for preprocessed files created by
+@option{-save-temps}.
+
+@item -ftabstop=@var{width}
+@opindex ftabstop
+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.
+
+@item -fno-show-column
+@opindex fno-show-column
+Do not print column numbers in diagnostics.  This may be necessary if
+diagnostics are being scanned by a program that does not understand the
+column numbers, such as @command{dejagnu}.
+
+@item -A @var{predicate}=@var{answer}
+@opindex A
+Make an assertion with the predicate @var{predicate} and answer
+@var{answer}.  This form is preferred to the older form @option{-A
+@var{predicate}(@var{answer})}, which is still supported, because
+it does not use shell special characters.
+@ifset cppmanual
+@xref{Assertions}.
+@end ifset
+
+@item -A -@var{predicate}=@var{answer}
+Cancel an assertion with the predicate @var{predicate} and answer
+@var{answer}.
+
+@item -A-
+@opindex A-
+Cancel all predefined assertions and all assertions preceding it on
+the command line.  Also, undefine all predefined macros and all
+macros preceding it on the command line.  (This is a historical wart and
+may change in the future.)
+
+@item -dCHARS
+@var{CHARS} is a sequence of one or more of the following characters,
+and must not be preceded by a space.  Other characters are interpreted
+by the compiler proper, or reserved for future versions of GCC, and so
+are silently ignored.  If you specify characters whose behavior
+conflicts, the result is undefined.
+
+@table @samp
+@item M
+@opindex dM
+Instead of the normal output, generate a list of @samp{#define}
+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 @file{foo.h}, the command
+
+@example
+touch foo.h; cpp -dM foo.h
+@end example
+
+@noindent
+will show all the predefined macros.
+
+@item D
+@opindex dD
+Like @samp{M} except in two respects: it does @emph{not} include the
+predefined macros, and it outputs @emph{both} the @samp{#define}
+directives and the result of preprocessing.  Both kinds of output go to
+the standard output file.
+
+@item N
+@opindex dN
+Like @samp{D}, but emit only the macro names, not their expansions.
+
+@item I
+@opindex dI
+Output @samp{#include} directives in addition to the result of
+preprocessing.
+@end table
+
+@item -P
+@opindex 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.
+@ifset cppmanual
+@xref{Preprocessor Output}.
+@end ifset
+
+@item -C
+@opindex 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.
+
+You should be prepared for side effects when using @option{-C}; 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 @samp{#}.
+
+@item -gcc
+@opindex gcc
+Define the macros @sc{__gnuc__}, @sc{__gnuc_minor__} and
+@sc{__gnuc_patchlevel__}.  These are defined automatically when you use
+@command{gcc -E}; you can turn them off in that case with
+@option{-no-gcc}.
+
+@item -traditional
+@opindex traditional
+Try to imitate the behavior of old-fashioned C, as opposed to ISO
+C@.
+@ifset cppmanual
+@xref{Traditional Mode}.
+@end ifset
+
+@item -trigraphs
+@opindex trigraphs
+Process trigraph sequences.
+@ifset cppmanual
+@xref{Initial processing}.
+@end ifset
+@ifclear cppmanual
+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.
+
+The nine trigraphs and their replacements are
+
+@example
+Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
+Replacement:      [    ]    @{    @}    #    \    ^    |    ~
+@end example
+@end ifclear
+
+@item -remap
+@opindex remap
+Enable special code to work around file systems which only permit very
+short file names, such as MS-DOS@.
+
+@item -$
+@opindex $
+Forbid the use of @samp{$} in identifiers.  The C standard allows
+implementations to define extra characters that can appear in
+identifiers.  By default GNU CPP permits @samp{$}, a common extension.
+
+@item -h
+@itemx --help
+@itemx --target-help
+@opindex h
+@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
+activities.  Each name is indented to show how deep in the
+@samp{#include} stack it is.
+
+@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
Index: doc/invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.119.2.4
diff -u -p -r1.119.2.4 invoke.texi
--- invoke.texi	2002/03/07 06:59:07	1.119.2.4
+++ invoke.texi	2002/03/10 21:47:11
@@ -3939,339 +3939,18 @@ Some of these options make sense only to
 they cause the preprocessor output to be unsuitable for actual
 compilation.
 
-@table @gcctabopt
-@item -include @var{file}
-@opindex include
-Process @var{file} as input before processing the regular input file.
-In effect, the contents of @var{file} are compiled first.  Any @option{-D}
-and @option{-U} options on the command line are always processed before
-@option{-include @var{file}}, regardless of the order in which they are
-written.  All the @option{-include} and @option{-imacros} options are
-processed in the order in which they are written.
-
-@item -imacros @var{file}
-@opindex imacros
-Process @var{file} as input, discarding the resulting output, before
-processing the regular input file.  Because the output generated from
-@var{file} is discarded, the only effect of @option{-imacros @var{file}}
-is to make the macros defined in @var{file} available for use in the
-main input.  All the @option{-include} and @option{-imacros} options are
-processed in the order in which they are written.
-
-@item -idirafter @var{dir}
-@opindex idirafter
-@cindex second include path
-Add the directory @var{dir} to the second include path.  The directories
-on the second include path are searched when a header file is not found
-in any of the directories in the main include path (the one that
-@option{-I} adds to).
-
-@item -iprefix @var{prefix}
-@opindex iprefix
-Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix}
-options.
-
-@item -iwithprefix @var{dir}
-@opindex iwithprefix
-Add a directory to the second include path.  The directory's name is
-made by concatenating @var{prefix} and @var{dir}, where @var{prefix} was
-specified previously with @option{-iprefix}.  If you have not specified a
-prefix yet, the directory containing the installed passes of the
-compiler is used as the default.
-
-@item -iwithprefixbefore @var{dir}
-@opindex iwithprefixbefore
-Add a directory to the main include path.  The directory's name is made
-by concatenating @var{prefix} and @var{dir}, as in the case of
-@option{-iwithprefix}.
-
-@item -isystem @var{dir}
-@opindex isystem
-Add a directory to the beginning of the second include path, marking it
-as a system directory, so that it gets the same special treatment as
-is applied to the standard system directories.
-
-@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
-current directory, if appropriate) are searched.  @xref{Directory
-Options}, for information on @option{-I}.
-
-By using both @option{-nostdinc} and @option{-I-}, you can limit the include-file
-search path to only those directories you specify explicitly.
-
-@item -remap
-@opindex remap
-When searching for a header file in a directory, remap file names if a
-file named @file{header.gcc} exists in that directory.  This can be used
-to work around limitations of file systems with file name restrictions.
-The @file{header.gcc} file should contain a series of lines with two
-tokens on each line: the first token is the name to map, and the second
-token is the actual name to use.
-
-@item -undef
-@opindex undef
-Do not predefine any nonstandard macros.  (Including architecture flags).
-
-@item -E
-@opindex E
-Run only the C preprocessor.  Preprocess all the C source files
-specified and output the results to standard output or to the
-specified output file.
-
-@item -C
-@opindex C
-Tell the preprocessor not to discard comments.  Used with the
-@option{-E} option.
-
-@item -P
-@opindex P
-Tell the preprocessor not to generate @samp{#line} directives.
-Used with the @option{-E} option.
-
-@cindex make
-@cindex dependencies, make
-@item -M
-@opindex M
-Instead of outputting the result of preprocessing, output a rule
-suitable for @command{make} describing the dependencies of the main
-source file.  The preprocessor outputs one @command{make} rule containing
-the object file name for that source file, a colon, and the names of all
-the included files, including those coming from @option{-include} or
-@option{-imacros} command line options.
-
-Unless specified explicitly (with @option{-MT} or @option{-MQ}), the
-object file name consists of the basename of the source file with any
-suffix replaced with object file suffix.  If there are many included
-files then the rule is split into several lines using @samp{\}-newline.
-The rule has no commands.
-
-Passing @option{-M} to the driver implies @option{-E}.
-
-@item -MM
-@opindex MM
-Like @option{-M} 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.
-
-This implies that the choice of angle brackets or double quotes in an
-@samp{#include} directive does not in itself determine whether that
-header will appear in @option{-MM} dependency output.  This is a
-slight change in semantics from GCC versions 3.0 and earlier.
-
-@item -MD
-@opindex MD
-@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that
-@option{-E} is not implied.  The driver determines @var{file} based on
-whether an @option{-o} option is given.  If it is, the driver uses its
-argument but with a suffix of @file{.d}, otherwise it take the
-basename of the input file and applies a @file{.d} suffix.
-
-If @option{-MD} is used in conjunction with @option{-E}, any
-@option{-o} switch is understood to specify the dependency output file
-(but @pxref{-MF}), but if used without @option{-E}, each @option{-o}
-is understood to specify a target object file.
-
-Since @option{-E} is not implied, @option{-MD} can be used to generate
-a dependency output file as a side-effect of the compilation process.
-
-With Mach, you can use the utility @code{md} to merge multiple
-dependency files into a single dependency file suitable for using with
-the @samp{make} command.
-
-@item -MMD
-@opindex MMD
-Like @option{-MD} except mention only user header files, not system
--header files.
-
-@item -MF @var{file}
-@opindex MF
-@anchor{-MF}
-When used with @option{-M} or @option{-MM}, specifies a
-file to write the dependencies to.  If no @option{-MF} switch is given
-the preprocessor sends the rules to the same place it would have sent
-preprocessed output.
-
-When used with the driver options @option{-MD} or @option{-MMD},
-@option{-MF} overrides the default dependency output file.
-
-Another way to specify output of a @code{make} rule is by setting
-the environment variable @env{DEPENDENCIES_OUTPUT} (@pxref{Environment
-Variables}).
-
-@item -MG
-@opindex MG
-When used with @option{-M} or @option{-MM}, @option{-MG} says to treat missing
-header files as generated files and assume they live in the same
-directory as the source file.  It suppresses preprocessed output, as a
-missing header file is ordinarily an error.
-
-This feature is used in automatic updating of makefiles.
-
-@item -MP
-@opindex MP
-This option instructs CPP 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 @code{make} gives if you remove header
-files without updating the @code{Makefile} to match.
-
-This is typical output:-
-
-@smallexample
-/tmp/test.o: /tmp/test.c /tmp/test.h
-
-/tmp/test.h:
-@end smallexample
-
-@item -MQ @var{target}
-@item -MT @var{target}
-@opindex MQ
-@opindex MT
-By default CPP uses the main file name, including any path, and appends
-the object suffix, normally ``.o'', to it to obtain the name of the
-target for dependency generation.  With @option{-MT} you can specify a
-target yourself, overriding the default one.
-
-If you want multiple targets, you can specify them as a single argument
-to @option{-MT}, or use multiple @option{-MT} options.
-
-The targets you specify are output in the order they appear on the
-command line.  @option{-MQ} is identical to @option{-MT}, except that the
-target name is quoted for Make, but with @option{-MT} it isn't.  For
-example, @option{-MT '$(objpfx)foo.o'} gives
-
-@smallexample
-$(objpfx)foo.o: /tmp/foo.c
-@end smallexample
-
-but @option{-MQ '$(objpfx)foo.o'} gives
-
-@smallexample
-$$(objpfx)foo.o: /tmp/foo.c
-@end smallexample
-
-The default target is automatically quoted, as if it were given with
-@option{-MQ}.
-
-@item -H
-@opindex H
-Print the name of each header file used, in addition to other normal
-activities.
-
-@item -A@var{question}(@var{answer})
-@opindex A
-Assert the answer @var{answer} for @var{question}, in case it is tested
-with a preprocessing conditional such as @samp{#if
-#@var{question}(@var{answer})}.  @option{-A-} disables the standard
-assertions that normally describe the target machine.
-
-@item -D@var{macro}
-@opindex D
-Define macro @var{macro} with the string @samp{1} as its definition.
-
-@item -D@var{macro}=@var{defn}
-Define macro @var{macro} as @var{defn}.  All instances of @option{-D} on
-the command line are processed before any @option{-U} options.
-
-Any @option{-D} and @option{-U} options on the command line are processed in
-order, and always before @option{-imacros @var{file}}, regardless of the
-order in which they are written.
-
-@item -U@var{macro}
-@opindex U
-Undefine macro @var{macro}.  @option{-U} options are evaluated after all
-@option{-D} options, but before any @option{-include} and @option{-imacros}
-options.
-
-Any @option{-D} and @option{-U} options on the command line are processed in
-order, and always before @option{-imacros @var{file}}, regardless of the
-order in which they are written.
-
-@item -dM
-@opindex dM
-Tell the preprocessor to output only a list of the macro definitions
-that are in effect at the end of preprocessing.  Used with the @option{-E}
-option.
-
-@item -dD
-@opindex dD
-Tell the preprocessing to pass all macro definitions into the output, in
-their proper sequence in the rest of the output.
-
-@item -dN
-@opindex dN
-Like @option{-dD} except that the macro arguments and contents are omitted.
-Only @samp{#define @var{name}} is included in the output.
-
-@item -dI
-@opindex dI
-Output @samp{#include} directives in addition to the result of
-preprocessing.
-
-@item -fpreprocessed
-@opindex 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 @option{-C} to the compiler without
-problems.  In this mode the integrated preprocessor is little more than
-a tokenizer for the front ends.
-
-@option{-fpreprocessed} is implicit if the input file has one of the
-extensions @samp{i}, @samp{ii} or @samp{mi}.  These are the extensions
-that GCC uses for preprocessed files created by @option{-save-temps}.
-
-@item -trigraphs
-@opindex trigraphs
-Process ISO standard trigraph sequences.  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.
-
-The nine trigraph sequences are
-@table @samp
-@item ??(
-@expansion{} @samp{[}
-
-@item ??)
-@expansion{} @samp{]}
-
-@item ??<
-@expansion{} @samp{@{}
-
-@item ??>
-@expansion{} @samp{@}}
-
-@item ??=
-@expansion{} @samp{#}
-
-@item ??/
-@expansion{} @samp{\}
-
-@item ??'
-@expansion{} @samp{^}
-
-@item ??!
-@expansion{} @samp{|}
-
-@item ??-
-@expansion{} @samp{~}
-
-@end table
-
-Trigraph support is not popular, so many compilers do not implement it
-properly.  Portable code should not rely on trigraphs being either
-converted or ignored.
-
-@item -Wp,@var{option}
 @opindex Wp
-Pass @var{option} as an option to the preprocessor.  If @var{option}
-contains commas, it is split into multiple options at the commas.
-@end table
+You can use @option{-Wp,@var{option}} to bypass the compiler driver
+and pass @var{option} directly through to the preprocessor.  If
+@var{option} contains commas, it is split into multiple options at the
+commas.  However, many options are modified, translated or interpreted
+by the compiler driver before being passed to the preprocessor, and
+@option{-Wp} forcibly bypasses this phase.  The preprocessor's direct
+interface is undocumented and subject to change, so whenever possible
+you should avoid using @option{-Wp} and let the driver handle the
+options instead.
+
+@include cppopts.texi
 
 @node Assembler Options
 @section Passing Options to the Assembler
@@ -10346,35 +10025,6 @@ using GCC also uses these directories wh
 libraries for the @option{-l} option (but directories specified with
 @option{-L} come first).
 
-@item C_INCLUDE_PATH
-@itemx CPLUS_INCLUDE_PATH
-@itemx OBJC_INCLUDE_PATH
-@findex C_INCLUDE_PATH
-@findex CPLUS_INCLUDE_PATH
-@findex OBJC_INCLUDE_PATH
-@c @itemx OBJCPLUS_INCLUDE_PATH
-These environment variables pertain to particular languages.  Each
-variable's value is a colon-separated list of directories, much like
-@env{PATH}.  When GCC searches for header files, it tries the
-directories listed in the variable for the language you are using, after
-the directories specified with @option{-I} but before the standard header
-file directories.
-
-@item DEPENDENCIES_OUTPUT
-@findex DEPENDENCIES_OUTPUT
-@cindex dependencies for make as output
-If this variable is set, its value specifies how to output dependencies
-for Make based on the header files processed by the compiler.  This
-output looks much like the output from the @option{-M} option
-(@pxref{Preprocessor Options}), but it goes to a separate file, and is
-in addition to the usual results of compilation.
-
-The value of @env{DEPENDENCIES_OUTPUT} 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
-@samp{@var{file} @var{target}}, in which case the rules are written to
-file @var{file} using @var{target} as the target name.
-
 @item LANG
 @findex LANG
 @cindex locale definition
@@ -10397,6 +10047,12 @@ If @env{LANG} is not defined, or if it h
 compiler will use mblen and mbtowc as defined by the default locale to
 recognize and translate multibyte characters.
 @end table
+
+@noindent
+Some additional environments variables affect the behavior of the
+preprocessor.
+
+@include cppenv.texi
 
 @c man end
 



More information about the Gcc-patches mailing list