Changes between Version 13 and Version 14 of Guidelines/MaintenanceGuidelines

Timestamp:

Nov 5, 2009, 3:13:34 PM (13 years ago)

Author:

Paul A. Bristow

Comment:

1st draft of Boost compiler warnings

Guidelines/MaintenanceGuidelines

@@ -538 +538 @@
 Discuss the issue on the ML and do a ticket on the Trac system if there is something to improve.
 
+-----------------------------------------------------------------------------------------------
+== Warnings from Compilers (and other tools) - Code-Round, Suppress Warnings, or Document. == #warnings
+
+Boost aims to avoid warnings messages as far as is reasonably practicable,
+even when compiled with the highest and most pedantic warning level,
+avoiding vendor specific extensions if possible.
+
+'''Some reasons are:'''
+
+1  To allow users whose environment enforces these conditions to use Boost code.
+
+2  To avoid the nuisance, perhaps overwhelming, of spurious warning messages.
+
+3  To improve code quality by focussing library writers attention on potential problems.
+
+4  To improve portability by drawing attention to potentially non-portable code.
+
+5  To improve compliance with the C++ Standard.
+
+6  To make it possible for users to enable high warning levels compiling their own code
+without being confused by a barrage of warnings from library code.
+
+7  To document that warnings have been considered by the library author or maintainer
+and are considered not significant.
+
+Of these, the last is possibly most important.
+
+'''What to do'''
+
+1  Test compilation with the most pedantic setting for the compiler.
+
+For Microsoft Visual Studio, this means setting level to 4 (command line /W4),
+and disabling Microsoft language extensions
+Disable MS extensions = Yes, command line option /Za
+
+For GCC this means -Wall -pendantic  
+
+Using bjam add warnings=all
+
+2  Consider each warning and
+
+a  Rewrite the C++ code to avoid the error.  For example, a static_cast makes it clear that
+the warned-about potential loss of accuracy has been considered but is not believed to be possible or significant.
+
+Or placing /* comment */ around an unused variable name, allows the name still to be useful documentation.
+
+b  Use the compiler specific mechanism to supress the warning message, but try hard to ensure that this is as local
+to the package as possible so that users can still get warnings from *their code*.
+
+For MSVC, this involved pushing to save the current warning state, disabling the warning, and later popping to restore.
+
+{{{
+#if defined(_MSC_VER)
+#pragma warning(push) // Save warning settings.
+#pragma warning(disable : 4996) // disable depricated localtime/gmtime warning
+#endif 
+
+...
+
+#if defined(_MSC_VER)
+#pragma warning(pop) // Restore warnings to previous state.
+#endif 
+
+}}}
+
+
+If the warning is only for a specific compiler version
+
+
+{{{
+#if BOOST_WORKAROUND(BOOST_MSVC, >= 1400)
+#pragma warning(push)
+#pragma warning(disable:4512) //assignment operator could not be generated
+#endif
+
+...
+
+#if BOOST_WORKAROUND(BOOST_MSVC, >= 1400)
+#pragma warning(pop)
+#endif
+}}}
+
+c  Repeat this process with other compilers and use their specific supression methods.
+
+d  Document the code and the associated documentation, and build tools like bjam to say that it is not possible
+to use some pedantic-ness level for this module, and why.
+
+
+
+
+
+
+