Disable assertions for release builds

Currently our build generates very many warnings if
G_DISABLE_ASSERT is defined.

Add ws_assert() and ws_assert_not_reached() to incrementally
replace existing assertions and then disable them using
WS_DISABLE_ASSERT.

Assertions are disabled with CMake build type Release.
By default the build type is RelWithDebInfo so the current
behaviour of enabling assertions by default is (for now) preserved.

Add some notes to README.Developer.

1 files changed, 30 insertions, 1 deletions

diff --git a/doc/README.developer b/doc/README.developer
index c7658962ee..99108c7470 100644
--- a/doc/README.developer
+++ b/doc/README.developer
@@ -533,7 +533,7 @@ packets without crashing or looping infinitely.
 Here are some suggestions for making code more robust in the face
 of incorrectly-formed packets:
 
-Do *NOT* use "g_assert()" or "g_assert_not_reached()" in dissectors.
+Do *NOT* use "ws_assert()" or "ws_assert_not_reached()" with input data in dissectors.
 *NO* value in a packet's data should be considered "wrong" in the sense
 that it's a problem with the dissector if found; if it cannot do
 anything else with a particular value from a packet's data, the
@@ -541,6 +541,35 @@ dissector should put into the protocol tree an indication that the
 value is invalid, and should return.  The "expert" mechanism should be
 used for that purpose.
 
+Use assertions to catch logic errors in your program. A failed assertion
+indicates a bug in the code. Use ws_assert() instead of g_assert() to
+test a logic condition. Note that ws_assert() will be removed with
+WS_DISABLE_ASSERT. Therefore assertions should not have any side-effects,
+otherwise the program may behave inconsistently.
+
+Use ws_assert_not_reached() instead of g_assert_not_reached() for
+unreachable error conditions. For example if (and only if) you know
+'myvar' can only have the values 1 and 2 do:
+    switch(myvar) {
+    case 1:
+        (...)
+        break;
+    case 2:
+        (...)
+        break;
+    default:
+        ws_assert_not_reached();
+        break;
+    }
+
+For dissectors use DISSECTOR_ASSERT() and DISSECTOR_ASSERT_NOT_REACHED()
+instead, with the same caveats as above.
+
+You should continue to use g_assert_true(), g_assert_cmpstr(), etc for
+"test code", such as unit testing. These assertions are always active.
+See the GLib Testing API documentation for the details on each of those
+functions.
+
 If there is a case where you are checking not for an invalid data item
 in the packet, but for a bug in the dissector (for example, an
 assumption being made at a particular point in the code about the