From fb9753dc87d0cfd04956c96feda63436523d48ab Mon Sep 17 00:00:00 2001 From: tromey Date: Tue, 13 May 2008 14:50:27 +0000 Subject: libcpp PR preprocessor/22168: * include/cpplib.h (struct cpp_options) : Update documentation. * expr.c (eval_token): Warn for use of assertions. * directives.c (directive_diagnostics): Warn about extensions. (DEPRECATED): New define. (DIRECTIVE_TABLE): Use it. gcc PR preprocessor/22168: * doc/cpp.texi (Top): Update menu. (Alternatives to Wrapper #ifndef): New node. (Other Directives): Document deprecation. (Obsolete Features): Remove menu. (Assertions): Merge node into Obsolete Features. (Obsolete once-only headers): Move earlier; rename to Alternatives to Wrapper #ifndef. * doc/cppopts.texi: Update. * c.opt (Wdeprecated): Enable for C and ObjC. * doc/invoke.texi (Option Summary): Move -Wno-deprecated. (C++ Dialect Options): Move -Wno-deprecated from here to... (Warning Options): ... here. gcc/testsuite PR preprocessor/22168: * gcc.dg/pch/import-2.hs: Add -Wno-deprecated. * gcc.dg/pch/import-1.hs: Add -Wno-deprecated. * gcc.dg/pch/import-2.c: Add -Wno-deprecated. * gcc.dg/pch/import-1.c: Add -Wno-deprecated. * gcc.dg/cpp/import2.c: Add -Wno-deprecated. * gcc.dg/cpp/import1.c: Add -Wno-deprecated. * gcc.dg/cpp/trad/assert3.c: Add -Wno-deprecated. * gcc.dg/cpp/trad/assert2.c: Add -Wno-deprecated. * gcc.dg/cpp/trad/assert1.c: Add -Wno-deprecated. * gcc.dg/cpp/ident.c: Add -Wno-deprecated. * gcc.dg/cpp/ident-1.c: Add -Wno-deprecated. * gcc.dg/cpp/extratokens.c: Add -Wno-deprecated. * gcc.dg/cpp/assert3.c: Add -Wno-deprecated. * gcc.dg/cpp/assert2.c: Add -Wno-deprecated. * gcc.dg/cpp/assert1.c: Add -Wno-deprecated. * gcc.dg/cpp/assert4.c: Compile with -ansi and not -pedantic. Add -Wno-deprecated. * gcc.dg/cpp/pr22168.c: New file. * gcc.dg/cpp/pr22168-2.c: New file. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@135264 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/doc/cpp.texi | 91 +++++++++++++++++++++++++++----------------------------- 1 file changed, 44 insertions(+), 47 deletions(-) (limited to 'gcc/doc/cpp.texi') diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index b98aef2bd68..9e2f19ad0b5 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -111,6 +111,7 @@ Header Files * Include Operation:: * Search Path:: * Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: * Computed Includes:: * Wrapper Headers:: * System Headers:: @@ -168,8 +169,7 @@ Implementation Details Obsolete Features -* Assertions:: -* Obsolete once-only headers:: +* Obsolete Features:: @end detailmenu @end menu @@ -734,6 +734,7 @@ underscores in header file names, and at most one dot. * Include Operation:: * Search Path:: * Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: * Computed Includes:: * Wrapper Headers:: * System Headers:: @@ -959,6 +960,42 @@ begin with @samp{_}. In a system header file, it should begin with file, the macro name should contain the name of the file and some additional text, to avoid conflicts with other header files. +@node Alternatives to Wrapper #ifndef +@section Alternatives to Wrapper #ifndef + +CPP supports two more ways of indicating that a header file should be +read only once. Neither one is as portable as a wrapper @samp{#ifndef} +and we recommend you do not use them in new programs, with the caveat +that @samp{#import} is standard practice in Objective-C. + +@findex #import +CPP supports a variant of @samp{#include} called @samp{#import} which +includes a file, but does so at most once. If you use @samp{#import} +instead of @samp{#include}, then you don't need the conditionals +inside the header file to prevent multiple inclusion of the contents. +@samp{#import} is standard in Objective-C, but is considered a +deprecated extension in C and C++. + +@samp{#import} is not a well designed feature. It requires the users of +a header file to know that it should only be included once. It is much +better for the header file's implementor to write the file so that users +don't need to know this. Using a wrapper @samp{#ifndef} accomplishes +this goal. + +In the present implementation, a single use of @samp{#import} will +prevent the file from ever being read again, by either @samp{#import} or +@samp{#include}. You should not rely on this; do not use both +@samp{#import} and @samp{#include} to refer to the same header file. + +Another way to prevent a header file from being included more than once +is with the @samp{#pragma once} directive. If @samp{#pragma once} is +seen when scanning a header file, that file will never be read again, no +matter what. + +@samp{#pragma once} does not have the problems that @samp{#import} does, +but it is not recognized by all preprocessors, so you cannot rely on it +in a portable program. + @node Computed Includes @section Computed Includes @cindex computed includes @@ -3467,6 +3504,8 @@ These directives are not part of the C standard, but they are not official GNU extensions either. What historical information we have been able to find, suggests they originated with System V@. +Both @samp{#ident} and @samp{#sccs} are deprecated extensions. + @cindex null directive The @dfn{null directive} consists of a @samp{#} followed by a newline, with only whitespace (including comments) in between. A null directive @@ -4004,16 +4043,10 @@ may not be a limitation. @node Obsolete Features @section Obsolete Features -CPP has a number of features which are present mainly for -compatibility with older programs. We discourage their use in new code. -In some cases, we plan to remove the feature in a future version of GCC@. +CPP has some features which are present mainly for compatibility with +older programs. We discourage their use in new code. In some cases, +we plan to remove the feature in a future version of GCC@. -@menu -* Assertions:: -* Obsolete once-only headers:: -@end menu - -@node Assertions @subsection Assertions @cindex assertions @@ -4097,42 +4130,6 @@ no effect. You can also make or cancel assertions using command line options. @xref{Invocation}. -@node Obsolete once-only headers -@subsection Obsolete once-only headers - -CPP supports two more ways of indicating that a header file should be -read only once. Neither one is as portable as a wrapper @samp{#ifndef}, -and we recommend you do not use them in new programs. - -@findex #import -In the Objective-C language, there is a variant of @samp{#include} -called @samp{#import} which includes a file, but does so at most once. -If you use @samp{#import} instead of @samp{#include}, then you don't -need the conditionals inside the header file to prevent multiple -inclusion of the contents. GCC permits the use of @samp{#import} in C -and C++ as well as Objective-C@. However, it is not in standard C or C++ -and should therefore not be used by portable programs. - -@samp{#import} is not a well designed feature. It requires the users of -a header file to know that it should only be included once. It is much -better for the header file's implementor to write the file so that users -don't need to know this. Using a wrapper @samp{#ifndef} accomplishes -this goal. - -In the present implementation, a single use of @samp{#import} will -prevent the file from ever being read again, by either @samp{#import} or -@samp{#include}. You should not rely on this; do not use both -@samp{#import} and @samp{#include} to refer to the same header file. - -Another way to prevent a header file from being included more than once -is with the @samp{#pragma once} directive. If @samp{#pragma once} is -seen when scanning a header file, that file will never be read again, no -matter what. - -@samp{#pragma once} does not have the problems that @samp{#import} does, -but it is not recognized by all preprocessors, so you cannot rely on it -in a portable program. - @node Differences from previous versions @section Differences from previous versions @cindex differences from previous versions -- cgit v1.2.1