diff options
Diffstat (limited to 'gcc/doc/cpp.texi')
| -rw-r--r-- | gcc/doc/cpp.texi | 596 |
1 files changed, 117 insertions, 479 deletions
diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index 1e8fd030c8f..39e6a287628 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -46,6 +46,12 @@ This manual contains no Invariant Sections. The Front-Cover Texts are @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:: @@ -822,11 +830,22 @@ version of GCC in use. You can add to this list with the @option{-I@var{dir}} command line option. All the directories named by @option{-I} are searched, in -left-to-right order, @emph{before} the default directories. You can -also prevent GCC from searching any of the default directories with the -@option{-nostdinc} option. This is useful when you are compiling an +left-to-right order, @emph{before} the default directories. The only +exception is when @file{dir} is already searched by default. In +this case, the option is ignored and the search order for system +directories remains unchanged. + +Duplicate directories are removed from the quote and bracket search +chains before the two chains are merged to make the final search chain. +Thus, it is possible for a directory to occur twice in the final search +chain if it was specified in both the quote and bracket chains. + +You can prevent GCC from searching any of the default directories with +the @option{-nostdinc} option. This is useful when you are compiling an operating system kernel or some other program that does not use the standard C library facilities, or the standard C library itself. +@option{-I} options are not ignored as described above when +@option{-nostdinc} is in effect. GCC looks for headers requested with @code{@w{#include "@var{file}"}} first in the directory containing the current file, then in the same @@ -835,12 +854,6 @@ For example, if @file{/usr/include/sys/stat.h} contains @code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in @file{/usr/include/sys}, then in its usual search path. -If you name a search directory with @option{-I@var{dir}} that is also a -system include directory, the @option{-I} wins; the directory will be -searched according to the @option{-I} ordering, and it will not be -treated as a system include directory. GCC will warn you when a system -include directory is hidden in this way. - @samp{#line} (@pxref{Line Control}) does not change GCC's idea of the directory containing the current file. @@ -1073,8 +1086,8 @@ found in that directory will be considered system headers. All directories named by @option{-isystem} are searched @emph{after} all directories named by @option{-I}, no matter what their order was on the command line. If the same directory is named by both @option{-I} and -@option{-isystem}, @option{-I} wins; it is as if the @option{-isystem} option -had never been specified at all. GCC warns you when this happens. +@option{-isystem}, the @option{-I} option is ignored. GCC provides an +informative message when this occurs if @option{-v} is used. @findex #pragma GCC system_header There is also a directive, @code{@w{#pragma GCC system_header}}, which @@ -1668,6 +1681,15 @@ eprintf ("success!\n") @expansion{} fprintf(stderr, "success!\n"); @end example +@noindent +The above explanation is ambiguous about the case where the only macro +parameter is a variable arguments parameter, as it is meaningless to +try to distinguish whether no argument at all is an empty argument or +a missing argument. In this case the C99 standard is clear that the +comma must remain, however the existing GCC extension used to swallow +the comma. So CPP retains the comma when conforming to a specific C +standard, and drops it otherwise. + C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} can appear is in the replacement list of a variadic macro. It may not be used as a macro name, macro argument name, or within a different type @@ -1798,9 +1820,7 @@ conformance to the C Standard. GNU CPP follows the host convention when processing system header files, but when processing user files @code{__STDC__} is always 1. This has been reported to cause problems; for instance, some versions of Solaris provide X Windows headers that -expect @code{__STDC__} to be either undefined or 1. You may be able to -work around this sort of problem by using an @option{-I} option to -cancel treatment of those headers as system headers. @xref{Invocation}. +expect @code{__STDC__} to be either undefined or 1. @xref{Invocation}. @item __STDC_VERSION__ This macro expands to the C Standard's version number, a long integer @@ -3035,6 +3055,13 @@ input. Subsequent lines are counted from @var{linenum}. effect. In addition, @var{filename} is a string constant. The following line and all subsequent lines are reported to come from the file it specifies, until something else happens to change that. +@var{filename} is interpreted according to the normal rules for a string +constant: backslash escapes are interpreted. This is different from +@samp{#include}. + +Previous versions of GNU CPP did not interpret escapes in @samp{#line}; +we have changed it because the standard requires they be interpreted, +and most other compilers do. @item #line @var{anything else} @var{anything else} is checked for macro calls, which are expanded. @@ -3044,7 +3071,35 @@ The result should match one of the above two forms. @samp{#line} directives alter the results of the @code{__FILE__} and @code{__LINE__} predefined macros from that point on. @xref{Standard Predefined Macros}. They do not have any effect on @samp{#include}'s -idea of the directory containing the current file. +idea of the directory containing the current file. This is a change +from GCC 2.95. Previously, a file reading + +@smallexample +#line 1 "../src/gram.y" +#include "gram.h" +@end smallexample + +would search for @file{gram.h} in @file{../src}, then the @option{-I} +chain; the directory containing the physical source file would not be +searched. In GCC 3.0 and later, the @samp{#include} is not affected by +the presence of a @samp{#line} referring to a different directory. + +We made this change because the old behavior caused problems when +generated source files were transported between machines. For instance, +it is common practice to ship generated parsers with a source release, +so that people building the distribution do not need to have yacc or +Bison installed. These files frequently have @samp{#line} directives +referring to the directory tree of the system where the distribution was +created. If GCC tries to search for headers in those directories, the +build is likely to fail. + +The new behavior can cause failures too, if the generated file is not +in the same directory as its source and it attempts to include a header +which would be visible searching from the directory containing the +source file. However, this problem is easily solved with an additional +@option{-I} switch on the command line. The failures caused by the old +semantics could sometimes be corrected only by editing the generated +files, which is difficult and error-prone. @node Pragmas @chapter Pragmas @@ -3224,7 +3279,8 @@ of the form These are called @dfn{linemarkers}. They are inserted as needed into the output (but never within a string or character constant). They mean that the following line originated in file @var{filename} at line -@var{linenum}. +@var{linenum}. @var{filename} will never contain any non-printing +characters; they are replaced with octal escape sequences. After the file name comes zero or more flags, which are @samp{1}, @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces @@ -3680,9 +3736,9 @@ Here are a few more obsolete features. @item Attempting to paste two tokens which together do not form a valid preprocessing token. -The preprocessor currently warns about this and outputs the two tokens -adjacently, which is probably the behavior the programmer intends. It -may not work in future, though. +The preprocessor currently warns about this, and the resulting +preprocessed output is undefined. The tokens remain distinct if the +preprocessor is being used directly by the compiler front end. Most of the time, when you get this warning, you will find that @samp{##} is being used superstitiously, to guard against whitespace appearing @@ -3780,6 +3836,25 @@ were still available in traditional mode. It is now a separate program and does not implement any of the GNU extensions, except for a partial implementation of assertions. Even those may be removed in a future release. + +@item @samp{#line} and @samp{#include} + +The @samp{#line} directive used to change GCC's notion of the +``directory containing the current file,'' used by @samp{#include} with +a double-quoted header file name. In 3.0 and later, it does not. +@xref{Line Control}, for further explanation. + +@item Syntax of @samp{#line} + +In GCC 2.95 and previous, the string constant argument to @samp{#line} +was treated the same way as the argument to @samp{#include}: backslash +escapes were not honored, and the string ended at the second @samp{"}. +This is not compliant with the C standard. In GCC 3.0, an attempt was +made to correct the behavior, so that the string was treated as a real +string constant, but it turned out to be buggy. In 3.1, the bugs have +been fixed. (We are not fixing the bugs in 3.0 because they affect +relatively few people and the fix is quite invasive.) + @end itemize @node Invocation @@ -3842,475 +3917,38 @@ options may @emph{not} be grouped: @option{-dM} is very different from @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. +@include cppopts.texi +@c man end -@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. +@node Environment Variables +@chapter Environment Variables +@cindex environment variables +@c man begin ENVIRONMENT -@item N -Like @samp{D}, but emit only the macro names, not their expansions. +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. -@item I -Output @samp{#include} directives in addition to the result of -preprocessing. -@end table +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 |