Changes between Version 27 and Version 28 of Guidelines/WarningsGuidelines

Timestamp:

Dec 6, 2012, 3:17:40 PM (10 years ago)

Author:

Paul A. Bristow

Comment:

Added macro specific to Clang and examples.

Guidelines/WarningsGuidelines

@@ -16 +16 @@
 whether it is correct in the context, and if so, apply appropriate remediation.
 If the warning is not correct in the context, only then should it be suppressed.
+
+To suppress warnings on all platforms is tedious hard work becuase every compiler provides different warnings and different ways of supressing warnings.
+[http://sourceforge.net/p/predef/wiki/Compilers/]
+gives macros provided by compilers that may help in pre-processing to chose the right method.
+
+But it is usually less trouble to eliminate the problem by better coding.
 
 Because developers don't have the same knowledge, even among Boost 
@@ -48 +54 @@
 5  To improve compliance with the C++ Standard.
 
-6  To permit users to set high warning levels when using Boost libraries without being overwhelmed with a barrage of library warnings.
+6  To permit users using Boost libraries to set high warning levels for their code without being overwhelmed with a barrage of library warnings.
 
 7  To document that warnings have been considered by the library author or maintainer
@@ -778 +784 @@
 to turn off warnings from that point forward in the file of the use of deprecated declarations.  Problematically, you have no way of knowing what the user had this option set to.  They might have already had the warnings turned on, they might have had them set to ignore, or they might have had them set to cause an error.  At the end of the file, if you do nothing else, the diagnostic for deprecated declarations stays ignored for anything that includes your file.  You can set them to ignored, error, or warning at the end of the file before exiting, but you don't know which to use.  This is sure to cause angst.
 ====== version 4.6 Now you can restore the user's flags
-For version 4.6 or later, you can save the state of the user's diagnostic flags.  You can insert this around the line that causes the spurious warning:
+For version 4.6 or later, you can save the state of the user's diagnostic flags.
+
+See [http://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html]
+
+  You can insert this around the line that causes the spurious warning:
 {{{
 #pragma GCC diagnostic push[[BR]]
@@ -790 +800 @@
 Of course this could cover everything from a line up to the whole file, and in between the push and the pop you could make multiple changes to each of multiple options.
 
-====== A handy macro to help you do some of this
+== ====== ==
+ A handy macro to help you do some of this
+
 Jonathan Wakely came up with a nice macro set to control this and I'm sharing a slightly modified version of it with you.  It defines:
  GCC_DIAG_OFF(FLAG):: 
@@ -866 +878 @@
 
 -Wall turns on the following warning flags:
-
-          -Waddress   
-          -Warray-bounds (only with -O2)  
-          -Wc++11-compat  
-          -Wchar-subscripts  
-          -Wenum-compare (in C/ObjC; this is on by default in C++) 
-          -Wimplicit-int (C and Objective-C only) 
-          -Wimplicit-function-declaration (C and Objective-C only) 
-          -Wcomment  
-          -Wformat   
-          -Wmain (only for C/ObjC and unless -ffreestanding)  
-          -Wmaybe-uninitialized 
-          -Wmissing-braces (only for C/ObjC) 
-          -Wnonnull  
-          -Wparentheses  
-          -Wpointer-sign  
-          -Wreorder   
-          -Wreturn-type  
-          -Wsequence-point  
-          -Wsign-compare (only in C++)  
-          -Wstrict-aliasing  
-          -Wstrict-overflow=1  
-          -Wswitch  
-          -Wtrigraphs  
-          -Wuninitialized  
-          -Wunknown-pragmas  
-          -Wunused-function  
-          -Wunused-label     
-          -Wunused-value     
-          -Wunused-variable  
-          -Wvolatile-register-var 
-
+{{{
+  -Waddress   
+  -Warray-bounds (only with -O2)  
+  -Wc++11-compat  
+  -Wchar-subscripts  
+  -Wenum-compare (in C/ObjC; this is on by default in C++) 
+  -Wimplicit-int (C and Objective-C only) 
+  -Wimplicit-function-declaration (C and Objective-C only) 
+  -Wcomment  
+  -Wformat   
+  -Wmain (only for C/ObjC and unless -ffreestanding)  
+  -Wmaybe-uninitialized 
+  -Wmissing-braces (only for C/ObjC) 
+  -Wnonnull  
+  -Wparentheses  
+  -Wpointer-sign  
+  -Wreorder   
+  -Wreturn-type  
+  -Wsequence-point  
+  -Wsign-compare (only in C++)  
+  -Wstrict-aliasing  
+  -Wstrict-overflow=1  
+  -Wswitch  
+  -Wtrigraphs  
+  -Wuninitialized  
+  -Wunknown-pragmas  
+  -Wunused-function  
+  -Wunused-label     
+  -Wunused-value     
+  -Wunused-variable  
+  -Wvolatile-register-var 
+}}}
 -Wextra
     This enables some extra warning flags that are not enabled by -Wall. (This option used to be called -W. The older name is still supported, but the newer name is more descriptive.)
-
-              -Wclobbered  
-              -Wempty-body  
-              -Wignored-qualifiers 
-              -Wmissing-field-initializers  
-              -Wmissing-parameter-type (C only)  
-              -Wold-style-declaration (C only)  
-              -Woverride-init  
-              -Wsign-compare  
-              -Wtype-limits  
-              -Wuninitialized  
-              -Wunused-parameter (only with -Wunused or -Wall) 
-              -Wunused-but-set-parameter (only with -Wunused or -Wall)  
-   
+{{{
+  -Wclobbered  
+  -Wempty-body  
+  -Wignored-qualifiers 
+  -Wmissing-field-initializers  
+  -Wmissing-parameter-type (C only)  
+  -Wold-style-declaration (C only)  
+  -Wsign-compare  
+  -Wtype-limits  
+  -Wuninitialized  
+  -Wunused-parameter (only with -Wunused or -Wall) 
+  -Wunused-but-set-parameter (only with -Wunused or -Wall)  
+ }}}  
 The option -Wextra also prints warning messages for the following cases:
-
-        A pointer is compared against integer zero with `<', `<=', `>', or `>='.
-        (C++ only) An enumerator and a non-enumerator both appear in a conditional expression.
-        (C++ only) Ambiguous virtual bases.
-        (C++ only) Subscripting an array that has been declared `register'.
-        (C++ only) Taking the address of a variable that has been declared `register'.
-        (C++ only) A base class is not initialized in a derived class's copy constructor. 
-
+{{{
+  A pointer is compared against integer zero with `<', `<=', `>', or `>='.
+  (C++ only) An enumerator and a non-enumerator both appear in a conditional expression.
+  (C++ only) Ambiguous virtual bases.
+  (C++ only) Subscripting an array that has been declared `register'.
+  (C++ only) Taking the address of a variable that has been declared `register'.
+  (C++ only) A base class is not initialized in a derived class's copy constructor. 
+}}}
 However, it may still be necessary to suppress those that are not providing any useful guidance and cannot be reasonably eliminated.
 
@@ -931 +942 @@
 To ignore via a command line, to an option like "-Wunused-variable" add a preceeding "no-" thus: "-Wno-unused-variable".
 
-In a jamfile, add
-{{{
-<cxxflags>-Wno-unused-variable
+In a jamfile, add, for example:
+{{{
+<toolset=clang><cxxflags>-Wno-unused-variable
 <cxxflags>-Wno-maybe-uninitialized
 ...
@@ -955 +966 @@
 }}}
 
-
-More info needed on Clang.
+But this is not portable and will produce 'unrecognized pragmas' on other platforms. 
+
+Macros that allow this to be done without causing complaint from other compilers is
+{{{
+
+#ifdef __clang__
+#  define CLANG_DIAG_STR(s) # s
+// stringize s to "no-unused-variable"
+#  define CLANG_DIAG_JOINSTR(x,y) CLANG_DIAG_STR(x ## y)
+//  join -W with no-unused-variable to "-Wno-unused-variable"
+#  define CLANG_DIAG_DO_PRAGMA(x) _Pragma (#x)
+// _Pragma is unary operator  #pragma ("")
+#  define CLANG_DIAG_PRAGMA(x) CLANG_DIAG_DO_PRAGMA(clang diagnostic x)
+#    define CLANG_DIAG_OFF(x) CLANG_DIAG_PRAGMA(push) \
+          CLANG_DIAG_PRAGMA(ignored CLANG_DIAG_JOINSTR(-W,x))
+// For example: #pragma clang diagnostic ignored "-Wno-unused-variable"
+#   define CLANG_DIAG_ON(x) CLANG_DIAG_PRAGMA(pop)
+// For example: #pragma clang diagnostic warning "-Wno-unused-variable"
+#else // Ensure these macros so nothing for other compilers.
+#  define CLANG_DIAG_OFF(x)
+#  define CLANG_DIAG_ON(x)
+#  define CLANG_DIAG_PRAGMA(x)
+#endif
+
+/* Usage:
+  CLANG_DIAG_OFF(unused-variable)
+  CLANG_DIAG_OFF(unused-parameter)
+  CLANG_DIAG_OFF(uninitialized)
+ */
+}}}
+
+
+{{{
+#include <iostream>
+#include <boost/assert.hpp>
+
+int main()
+{
+  #ifdef __clang__
+  std::cout << "Clang "<< __clang_major__ << '.' << __clang_minor__<< '.' << __clang_patchlevel__ << std::endl;
+  #endif
+
+
+// Clang method of saving and restoring current warning state.
+  #pragma clang diagnostic push
+  #pragma clang diagnostic pop
+
+// Example of using Clang push'n'pop around two ignored warnings.
+  #pragma clang diagnostic push
+  #pragma clang diagnostic ignored "-Wmultichar"
+  #pragma clang diagnostic ignored "-Wconstant-conversion"
+  #pragma clang diagnostic ignored  "-Wunused-variable"
+  char b = 'df'; // Most unwisely ignoring ALL warnings.
+  #pragma clang diagnostic pop
+
+// Example of using macro for push and pop pragmas.
+  CLANG_DIAG_PRAGMA(push);
+  #pragma clang diagnostic ignored "-Wunused-variable"
+  int unused;
+  CLANG_DIAG_PRAGMA(pop);
+
+  // example of using macro to push warning state,suppress a warning and restore state.
+  CLANG_DIAG_OFF(unused-variable)
+  int unused_two;  // No warning from unused variable.
+  CLANG_DIAG_ON(unused-variable) //
+
+  int unused_too; // Expect an unused-variable warning!
+
+  return 0;
+}
+
+/*  Output:
+  Clang 3.1.0
+
+ clang++.exe -dD -Wall -Wextra   -c -g -Wall -I/i/boost-trunk -MMD -MP -MF build/Debug/MinGW_Clang-Windows/warnings_1.o.d -o build/Debug/MinGW_Clang-Windows/warnings_1.o warnings_1.cpp
+warnings_1.cpp:97:7: warning: unused variable 'unused_too' [-Wunused-variable]
+  int unused_too; // Expect an unused-variable warning!
+      ^
+1 warning generated.
+ *
+ *
+ * but for MSVC
+ *
+ ClCompile:
+  warning_1.cpp
+warning_1.cpp(77): warning C4068: unknown pragma
+warning_1.cpp(78): warning C4068: unknown pragma
+warning_1.cpp(81): warning C4068: unknown pragma
+warning_1.cpp(82): warning C4068: unknown pragma
+warning_1.cpp(83): warning C4068: unknown pragma
+warning_1.cpp(84): warning C4068: unknown pragma
+warning_1.cpp(85): warning C4305: 'initializing' : truncation from 'int' to 'char'
+warning_1.cpp(85): warning C4309: 'initializing' : truncation of constant value
+warning_1.cpp(86): warning C4068: unknown pragma
+warning_1.cpp(90): warning C4068: unknown pragma
+warning_1.cpp(99): warning C4101: 'unused_too' : unreferenced local variable
+warning_1.cpp(96): warning C4101: 'unused_two' : unreferenced local variable
+warning_1.cpp(85): warning C4189: 'b' : local variable is initialized but not referenced
+warning_1.cpp(91): warning C4101: 'unused' : unreferenced local variable
+j:\cpp\svg\warning_1\warning_1.cpp(66): warning C4701: potentially uninitialized local variable 'x' used
+
+*/
+}}}
+
+showing that eliminating warnings is usually much less trouble.
+
+More info and experience needed on Clang.
 
 '''Intel'''