Changes between Version 20 and Version 21 of Guidelines/MaintenanceGuidelines

Timestamp:

Nov 8, 2009, 6:01:40 PM (13 years ago)

Author:

Paul A. Bristow

Comment:

Reordered table and added more examples.

Guidelines/MaintenanceGuidelines

@@ -575 +575 @@
 To a jamfile add  <toolset>msvc:<cxxflags>/Za # disable MS extensions.[[BR]]
 
-If it proves impossible to compile with the \Za option (it is reported to cause trouble with the compiler sometimes), just document this, including in the build jamfile.
+If it proves impossible to compile with the /Za option (it is reported to cause trouble with the MS compiler, sometimes), just document this, including in the build jamfile.
 
 (You might also consider using Microsoft /Wall if available.  You may find
@@ -604 +604 @@
       <toolset>msvc:<warnings>all # == /W4
       <toolset>msvc:<asynch-exceptions>on # Needed for Boost.Test
-      <toolset>msvc:<cxxflags>/Za # disable MS extensions.
+      <toolset>msvc:<cxxflags>/Za # Disable MS extensions.
+      # <toolset>msvc:<cxxflags>/Zc # Enable MS extensions if these are definitely required.
+      #  The define of macros below prevent warnings about the checked versions of SCL and CRT libraries.
+      #  Most Boost code does not need these versions (as they are markedly slower).
       <toolset>msvc:<define>_SCL_SECURE_NO_WARNINGS
       <toolset>msvc:<define>_SCL_SECURE_NO_DEPRECATE
+      <toolset>msvc:<define>_CRT_SECURE_NO_WARNINGS
       <toolset>msvc:<define>_CRT_SECURE_NO_DEPRECATE
-      <toolset>msvc:<define>_CRT_SECURE_NO_WARNINGS
+      #  Alternatively, you can just suppress the warnings (probably not the best way).
       <toolset>msvc:<cxxflags>/wd4996 # 'putenv': The POSIX name for this item is deprecated.
       <toolset>msvc:<cxxflags>/wd4512 # assignment operator could not be generated.
@@ -629 +633 @@
 to the package as possible so that users can still get warnings from *their code*.
 
-For MSVC, this involves pushing to save the current warning state, disabling the warning, and later popping to restore.
-Adding some or all of the warning message is helpful to tell readers what warning is being ignored.
-
+For MSVC, this involves pushing to save the current warning state, disabling the warning, and later popping to restore (abbreviated as ''push'n'pop'').
 {{{
 #if defined(_MSC_VER)
@@ -646 +648 @@
 }}}
 
-If the warning is only for a specific compiler version, us this approach:
+Adding some or all of the warning message as a comment is helpful to tell ''readers'' what warning is being ignored, for example:
+
+{{{
+#  pragma warning(disable: 4510) // default constructor could not be generated
+}}}
+
+If the warning is only for a specific compiler version, use this approach:
 
 {{{
@@ -668 +676 @@
 === Specific Warnings and Suggested Actions. ===
 
-''These are just few for starters and need more especially for gcc. Suggestions may be wrong!  Also need reordering in a table.''
+''These are just few for starters, and need more, especially for gcc. Suggestions may be wrong! ''
+
+The pragma or other code required to suppress warnings is in the right hand box, ready for copy and paste.
 
 '''Microsoft'''
@@ -676 +686 @@
 ||Warning||Warning Description||Suggestions||Suppression||
 
+
+||C4100|| unreferenced formal parameter||Either surround the parameter with C comments, for example: int */ my_variable */)or just delete if the variable name is uninformative. If in other's module(s), or you are too busy/idle, at least suppress warning.||#  pragma warning(disable: 4100) // 'name' : unreferenced formal parameter||
+
+||C4127|| conditional expression is constant||Very common and many believe unhelpful, but a few find it informative, so do not suppress globally.  Even while(true) can trigger this!  Suppress.|| #  pragma warning(disable: 4127) // conditional expression is constant.||
+
+||C4180||  qualifier applied to function type has no meaning; ignored||This can always be suppressed - but check that you didn't mean to put the const somewhere else.||#  pragma warning(disable: 4180) // qualifier applied to function type has no meaning; ignored||
+
+||C4506|| no definition for inline function||If you cannot fix, suppress||#  pragma warning(disable: 4506) // no definition for inline function||
+
 ||C4512|| assignment operator could not be generated||Suppress using push'n'pop for the module(s) causing the warning.||//#  pragma warning(disable: 4512) // assignment operator could not be generated.||
 
-|| C4996||'putenv': The POSIX name for this item is deprecated.||Many other messages about using secure versions.Unless you believe that the 'secure' versions are useful, suppress.||#  pragma warning(disable: 4996) // '' was declared deprecated.||
-
-||C4127|| conditional expression is constant||Very common and many believe unhelpful, but a few find it informative, so do not suppress globally.  Even while(true) can trigger this!  Suppress.|| #  pragma warning(disable: 4127) // conditional expression is constant.||
-
-||C4100|| unreferenced formal parameter||Either surround the parameter with C comments, for example: int */ my_variable */)or just delete if the variable name is uninformative.||||
-
-|| C4701|| local variable may be used without having been initialized||Best is to recode to avoid the message, but if you are '''very''' sure the message is misleading, suppress.|| #  pragma warning(disable: 4701) // local variable may be used without having been initialized||
-
-|| c4511||  copy constructor could not be generated||This can almost certainly be suppressed.|| #  pragma warning(disable: 4511) // copy constructor could not be generated||
-
-|| C4180||  qualifier applied to function type has no meaning; ignored||This can always be suppressed - but check that you didn't mean to put the const somewhere else.||#  pragma warning(disable: 4180) // qualifier applied to function type has no meaning; ignored||
-
-|| C4702||  unreachable code||Be very cautious about suppressing this, but use of macros may make this troublesome, so suppress with care, and always locally.|| #pragma warning(disable: 4702) // unreachable code||
-
-|| C4189|| local variable is initialized but not referenced||This probably indicates a redundant variable and assignment, so probably remove it.If you sure it is required (or has negligible cost for some documentation benefit), suppress.||||
-
-||  C4224|| nonstandard extension used : formal parameter 'arg' was previously defined as a type.||This will bite users who try to compile with Microsoft extensions disabled. So is most undesirable, but may be a major nuisance to change the names in code.However fixing is the Right Thing, but meanwhile suppressing may be helpful.|| #  pragma warning(disable: 4224) // formal parameter 'arg' was previously defined as a type.||
-
-|| C4510||  default constructor could not be generated||Suppress.||#  pragma warning(disable: 4510)||
-
-|| C4800|| int' : forcing value to bool 'true' or 'false'||Suppress.||#  pragma warning(disable: 4800) // int' : forcing value to bool 'true' or 'false'
-
-|| C4244 ||  // Conversion: possible loss of data.||Fix, for example changing type or using static_cast is best, suppress with much caution.||  # pragma warning(disable:4244)    // Conversion: possible loss of data.||
-
-||  C4324||  structure was padded due to __declspec(align())||Suppress||#pragma warning(disable:4324) // structure was padded due to __declspec(align())||
+||c4511||  copy constructor could not be generated||This can almost certainly be suppressed.|| #  pragma warning(disable: 4511) // copy constructor could not be generated||
+
+||C4701|| local variable may be used without having been initialized||Best is to recode to avoid the message, but if you are '''very''' sure the message is misleading, suppress.|| #  pragma warning(disable: 4701) // local variable may be used without having been initialized||
+
+||C4702||  unreachable code||Be very cautious about suppressing this, but use of macros may make this troublesome, so suppress with care, and always locally.|| #pragma warning(disable: 4702) // unreachable code||
+
+||C4189|| local variable is initialized but not referenced||This probably indicates a redundant variable and assignment, so probably remove it. If you are sure it is required (or has negligible cost for some documentation benefit), suppress.||||
+
+||C4224|| nonstandard extension used : formal parameter 'arg' was previously defined as a type.||This will bite users who try to compile with Microsoft extensions disabled. So is most undesirable, but may be a major nuisance to change the names in code.However fixing is the Right Thing, but meanwhile suppressing may be helpful.|| #  pragma warning(disable: 4224) // formal parameter 'arg' was previously defined as a type.||
+
+||C4244 ||  // Conversion: possible loss of data.||Fix, for example changing type or using static_cast is best, suppress with much caution.||  # pragma warning(disable:4244)    // Conversion: possible loss of data.||
+
+||C4324||  structure was padded due to __declspec(align())||Suppress||#pragma warning(disable:4324) // structure was padded due to __declspec(align())||
+
+||C4510||  default constructor could not be generated||Suppress.||#  pragma warning(disable: 4510) // default constructor could not be generated||
+
+||C4800|| int' : forcing value to bool 'true' or 'false'||Suppress.||#  pragma warning(disable: 4800) // int' : forcing value to bool 'true' or 'false'
+
+||C4996||'putenv': The POSIX name for this item is deprecated.||Many other messages about using secure versions.Unless you believe that the 'secure' versions are useful, suppress.||#  pragma warning(disable: 4996) // '' was declared deprecated.||
+
 
 '''GCC'''