[cfe-commits] r75432 - /cfe/trunk/docs/UsersManual.html

Chris Lattner sabre at nondot.org
Sun Jul 12 14:22:10 PDT 2009

Author: lattner
Date: Sun Jul 12 16:22:10 2009
New Revision: 75432

URL: http://llvm.org/viewvc/llvm-project?rev=75432&view=rev
document the diagnostics pragmas, patch by Louis Gerbarg!


Modified: cfe/trunk/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.html?rev=75432&r1=75431&r2=75432&view=diff

--- cfe/trunk/docs/UsersManual.html (original)
+++ cfe/trunk/docs/UsersManual.html Sun Jul 12 16:22:10 2009
@@ -33,6 +33,12 @@
 <li><a href="#general_features">Language and Target-Independent Features</a>
   <li><a href="#diagnostics">Controlling Errors and Warnings</a></li>
+   <ul>
+   <li><a href="#diagnostics_display">Controlling How Clang Displays Diagnostics</a></li>
+   <li><a href="#diagnostics_mappings">Diagnostic Mappings</a></li>
+   <li><a href="#diagnostics_commandline">Controlling Diagnostics via Command Line Flags</a></li>
+   <li><a href="#diagnostics_pragmas">Controlling Diagnostics via Pragmas</a></li>
+   </ul>
   <li><a href="#precompiledheaders">Precompiled Headers</a></li>
@@ -362,7 +368,7 @@
 <p>Clang provides a number of ways to control which code constructs cause it to
 emit errors and warning messages, and how they are displayed to the console.</p>
-<h4>Controlling How Clang Displays Diagnostics</h4>
+<h4 id="diagnostics_display">Controlling How Clang Displays Diagnostics</h4>
 <p>When Clang emits a diagnostic, it includes rich information in the output,
 and gives you fine-grain control over which information is printed.  Clang has
@@ -394,18 +400,64 @@
 <p>For more information please see <a href="#cl_diag_formatting">Formatting of
-<h4>Controlling Which Diagnostics Clang Generates</h4>
+<h4 id="diagnostics_mappings">Diagnostic Mappings</h4>
-<p>mappings: ignore, note, warning, error, fatal</p>
+<p>All diagnostics are mapped into one of these 5 classes:</p>
-The two major classes are control from the command line and control via pragmas
-in your code.</p>
+<h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line Flags</h4>
 <p>-W flags, -pedantic, etc</p>
-<p>pragma GCC diagnostic</p>
+<h4 id="diagnostics_pragmas">Controlling Diagnostics via Pragmas</h4>
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific warnings
+in a section of source code. Clang supports GCC's pragma for compatibility
+with existing source code, as well as several extensions. </p>
+<p>The pragma may control any warning that can be used from the command line.
+Warnings may be set to ignored, warning, error, or fatal. The following 
+example code will tell Clang or GCC to ignore the -Wall warnings:</p>
+#pragma GCC diagnostic ignored "-Wall"
+<p>In addition to all of the functionality of provided by GCC's pragma, Clang 
+also allows you to push and pop the current warning state.  This is particularly
+useful when writing a header file that will be compiled by other people, because 
+you don't know what warning flags they build with.</p>
+<p>In the below example
+-Wmultichar is ignored for only a single line of code, after which the
+diagnostics return to whatever state had previously existed.</p>
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmultichar"
+char b = 'df'; // no warning.
+#pragma clang diagnostic pop
+<p>The push and pop pragmas will save and restore the full diagnostic state of
+the compiler, regardless of how it was set. That means that it is possible to
+use push and pop around GCC compatible diagnostics and Clang will push and pop
+them appropriately, while GCC will ignore the pushes and pops as unknown 
+pragmas. It should be noted that while Clang supports the GCC pragma, Clang and
+GCC do not support the exact same set of warnings, so even when using GCC
+compatible #pragmas there is no guarantee that they will have identical behaviour
+on both compilers. </p>
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
 <h3 id="precompiledheaders">Precompiled Headers</h3>

More information about the cfe-commits mailing list