sync NDEBUG, RUBY_DEBUG, and RUBY_NDEBUG (#3327)

- When NDEBUG is defined that shall be honoured.
- When RUBY_DEBUG is defined that shall be honoured.
- When both are defined and they conflict, warnings shall be rendered.
- When nothing is specified, nothing shall happen.

4 files changed, 169 insertions, 45 deletions

diff --git a/include/ruby/assert.h b/include/ruby/assert.h
index 8967973bf8..9b70d7103e 100644
--- a/include/ruby/assert.h
+++ b/include/ruby/assert.h
@@ -27,37 +27,105 @@
 #include "ruby/internal/dllexport.h"
 #include "ruby/backward/2/assume.h"
 
-#ifndef RUBY_DEBUG
-# define RUBY_DEBUG 0
-#endif
+/* RUBY_NDEBUG  is very  simple:  after everything  described  below are  done,
+ * define it with either NDEBUG is undefined (=0) or defined (=1).  It is truly
+ * subordinate.
+ *
+ * RUBY_DEBUG versus NDEBUG is complicated.  Assertions shall be:
+ *
+ *                      | -UNDEBUG | -DNDEBUG
+ *       ---------------+----------+---------
+ *       -URUBY_DEBUG   | (*1)     | disabled
+ *       -DRUBY_DEBUG=0 | disabled | disabled
+ *       -DRUBY_DEBUG=1 | enabled  | (*2)
+ *       -DRUBY_DEBUG   | enabled  | (*2)
+ *
+ * where:
+ *
+ *   - (*1): Assertions shall  be silently disabled, no warnings,  in favour of
+ *     commit 21991e6ca59274e41a472b5256bd3245f6596c90.
+ *
+ *   - (*2): Compile-time warnings shall be issued.
+ */
+
+/** @cond INTERNAL_MACRO */
 
-#if RUBY_DEBUG > 0 && defined(NDEBUG)
-#if defined(_MSC_VER)
-# pragma message("NDEBUG is ignored because RUBY_DEBUG>0.")
-#elif defined(__GNUC__)
-# pragma GCC warning "NDEBUG is ignored because RUBY_DEBUG>0."
+/*
+ * Pro tip: `!!RUBY_DEBUG-1` expands to...
+ *
+ * - `!!(-1)`  (== `!0`  ==  `1`) when RUBY_DEBUG is defined to be empty,
+ * - `(!!0)-1` (== `0-1` == `-1`) when RUBY_DEBUG is defined as 0, and
+ * - `(!!n)-1` (== `1-1` ==  `0`) when RUBY_DEBUG is defined as something else.
+ */
+#if ! defined(RUBY_DEBUG)
+# define RBIMPL_RUBY_DEBUG 0
+#elif !!RUBY_DEBUG-1 < 0
+# define RBIMPL_RUBY_DEBUG 0
 #else
-# error NDEBUG is ignored because RUBY_DEBUG>0.
-#endif
+# define RBIMPL_RUBY_DEBUG 1
 #endif
 
 /*
- * Pro tip: `!!NDEBUG-1` expands to...
- *
- * - `!!(-1)`  (== `!0`  ==  `1`) when NDEBUG is defined to be empty,
- * - `(!!0)-1` (== `0-1` == `-1`) when NDEBUG is defined as 0, and
- * - `(!!n)-1` (== `1-1` ==  `0`) when NDEBUG is defined as something else.
+ * ISO/IEC 9899 (all past versions) says that  "If NDEBUG is defined as a macro
+ * name at  the point  in the  source file where  <assert.h> is  included, ..."
+ * which means we must not take its defined value into account.
  */
-#if defined(RUBY_NDEBUG)
-# /* Take that. */
-#elif ! defined(NDEBUG)
-# define RUBY_NDEBUG 0
-#elif !!NDEBUG-1 < 0
-# define RUBY_NDEBUG 0
+#if defined(NDEBUG)
+# define RBIMPL_NDEBUG 1
 #else
+# define RBIMPL_NDEBUG 0
+#endif
+
+/** @endcond */
+
+/* Here we go... */
+#undef RUBY_DEBUG
+#undef RUBY_NDEBUG
+#undef NDEBUG
+#if defined(__DOXYGEN__)
+# /** Define this macro when you want assertions. */
+# define RUBY_DEBUG 0
+# /** Define this macro when you don't want assertions. */
+# define NDEBUG
+# /** This macro is basically the same as #NDEBUG */
+# define RUBY_NDEBUG 1
+
+#elif (RBIMPL_NDEBUG == 1) && (RBIMPL_RUBY_DEBUG == 0)
+# /* Assertions disabled as per request, no conflicts. */
+# define RUBY_DEBUG 0
+# define RUBY_NDEBUG 1
+# define NDEBUG
+
+#elif (RBIMPL_NDEBUG == 0) && (RBIMPL_RUBY_DEBUG == 1)
+# /* Assertions enabled as per request, no conflicts. */
+# define RUBY_DEBUG 1
+# define RUBY_NDEBUG 0
+# /* keep NDEBUG undefined */
+
+#elif (RBIMPL_NDEBUG == 0) && (RBIMPL_RUBY_DEBUG == 0)
+# /* The (*1) situation in avobe diagram. */
+# define RUBY_DEBUG 0
 # define RUBY_NDEBUG 1
+# define NDEBUG
+
+#elif (RBIMPL_NDEBUG == 1) && (RBIMPL_RUBY_DEBUG == 1)
+# /* The (*2) situation in above diagram. */
+# define RUBY_DEBUG 1
+# define RUBY_NDEBUG 0
+# /* keep NDEBUG undefined */
+
+# if defined(_MSC_VER)
+#  pragma message("NDEBUG is ignored because RUBY_DEBUG>0.")
+# elif defined(__GNUC__)
+#  pragma GCC warning "NDEBUG is ignored because RUBY_DEBUG>0."
+# else
+#  error NDEBUG is ignored because RUBY_DEBUG>0.
+# endif
 #endif
+#undef RBIMPL_NDEBUG
+#undef RBIMPL_RUBY_DEBUG
 
+/** @cond INTERNAL_MACRO */
 #define RBIMPL_ASSERT_NOTHING RBIMPL_CAST((void)0)
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
@@ -72,39 +140,95 @@ RBIMPL_SYMBOL_EXPORT_END()
 # define RBIMPL_ASSERT_FUNC RBIMPL_CAST((const char *)0)
 #endif
 
+/** @endcond */
+
+/**
+ * Prints the given message, and terminates the entire process abnormally.
+ *
+ * @param  mesg  The message to display.
+ */
 #define RUBY_ASSERT_FAIL(mesg) \
     rb_assert_failure(__FILE__, __LINE__, RBIMPL_ASSERT_FUNC, mesg)
 
+/**
+ * Asserts that the expression is truthy.  If not aborts with the message.
+ *
+ * @param  expr  What supposedly evaluates to true.
+ * @param  mesg  The message to display on failure.
+ */
 #define RUBY_ASSERT_MESG(expr, mesg) \
     (RB_LIKELY(expr) ? RBIMPL_ASSERT_NOTHING : RUBY_ASSERT_FAIL(mesg))
 
+/**
+ * A variant of #RUBY_ASSERT that does not interface with #RUBY_DEBUG.
+ *
+ * @copydetails #RUBY_ASSERT
+ */
+#define RUBY_ASSERT_ALWAYS(expr) RUBY_ASSERT_MESG((expr), #expr)
+
+/**
+ * Asserts that the given expression is truthy iff #RUBY_DEBUG is truthy.
+ *
+ * @param  expr  What supposedly evaluates to true.
+ */
+#if RUBY_DEBUG
+# define RUBY_ASSERT(expr) RUBY_ASSERT_MESG((expr), #expr)
+#else
+# define RUBY_ASSERT(expr) RBIMPL_ASSERT_NOTHING
+#endif
+
+/**
+ * A  variant  of   #RUBY_ASSERT  that  interfaces  with   #NDEBUG  instead  of
+ * #RUBY_DEBUG.  This almost resembles `assert`  C standard macro, except minor
+ * implementation details.
+ *
+ * @copydetails #RUBY_ASSERT
+ */
+/* Currently  `RUBY_DEBUG == ! defined(NDEBUG)` is  always true.   There is  no
+ * difference any longer between this one and `RUBY_ASSERT`. */
+#if defined(NDEBUG)
+# define RUBY_ASSERT_NDEBUG(expr) RBIMPL_ASSERT_NOTHING
+#else
+# define RUBY_ASSERT_NDEBUG(expr) RUBY_ASSERT_MESG((expr), #expr)
+#endif
+
+/**
+ * @copydoc #RUBY_ASSERT_WHEN
+ * @param  mesg  The message to display on failure.
+ */
 #if RUBY_DEBUG
-# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) RUBY_ASSERT_MESG((expr), mesg)
-#elif ! defined(HAVE_BUILTIN___BUILTIN_CHOOSE_EXPR_CONSTANT_P)
-# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) RUBY_ASSERT_MESG(!(cond) || (expr), mesg)
+# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) RUBY_ASSERT_MESG((expr), (mesg))
 #else
 # define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) \
-    __builtin_choose_expr( \
-        __builtin_constant_p(cond), \
-        __builtin_choose_expr(cond, \
-            RUBY_ASSERT_MESG(expr, mesg), \
-            RBIMPL_ASSERT_NOTHING), \
-        RUBY_ASSERT_MESG(!(cond) || (expr), mesg))
-#endif /* RUBY_DEBUG */
-
-#define RUBY_ASSERT(expr)            RUBY_ASSERT_MESG_WHEN(FALSE, expr, #expr)
-#define RUBY_ASSERT_NDEBUG(expr)     RUBY_ASSERT_MESG_WHEN(RUBY_NDEBUG, expr, #expr)
-#define RUBY_ASSERT_WHEN(cond, expr) RUBY_ASSERT_MESG_WHEN(cond, expr, #expr)
-#define RUBY_ASSERT_ALWAYS(expr)     RUBY_ASSERT_MESG_WHEN(TRUE, expr, #expr)
+    ((cond) ? RUBY_ASSERT_MESG((expr), (mesg)) : RBIMPL_ASSERT_NOTHING)
+#endif
+
+/**
+ * A variant  of #RUBY_ASSERT  that asserts when  either #RUBY_DEBUG  or `cond`
+ * parameter is truthy.
+ *
+ * @param  cond  Extra condition that shall hold for assertion to take effect.
+ * @param  expr  What supposedly evaluates to true.
+ */
+#define RUBY_ASSERT_WHEN(cond, expr) RUBY_ASSERT_MESG_WHEN((cond), (expr), #expr)
 
+/**
+ * This is either #RUBY_ASSERT or #RBIMPL_ASSUME, depending on #RUBY_DEBUG.
+ *
+ * @copydetails #RUBY_ASSERT
+ */
 #if RUBY_DEBUG
-# define RBIMPL_ASSERT_OR_ASSUME(_) RUBY_ASSERT(_)
-#elif defined(RBIMPL_HAVE___ASSUME)
-# define RBIMPL_ASSERT_OR_ASSUME(_) RBIMPL_ASSUME(_)
-#elif !RUBY_ASSERT_NOASSUME && RBIMPL_HAS_BUILTIN(__builtin_assume) && RBIMPL_COMPILER_SINCE(Clang, 7, 0, 0)
-# define RBIMPL_ASSERT_OR_ASSUME(_) RBIMPL_ASSUME(_)
+# define RBIMPL_ASSERT_OR_ASSUME(expr) RUBY_ASSERT_ALWAYS(expr)
+#elif RBIMPL_COMPILER_BEFORE(Clang, 7, 0, 0)
+# /* See commit 67d259c5dccd31fe49d417fec169977712ffdf10 */
+# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING
+#elif defined(RUBY_ASSERT_NOASSUME)
+# /* See commit d300a734414ef6de7e8eb563b7cc4389c455ed08 */
+# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING
+#elif ! defined(RBIMPL_HAVE___ASSUME)
+# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING
 #else
-# define RBIMPL_ASSERT_OR_ASSUME(_) /* void */
+# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSUME(expr)
 #endif
 
 #endif /* RUBY_ASSERT_H */
diff --git a/include/ruby/internal/attr/const.h b/include/ruby/internal/attr/const.h
index f3068f9f5e..d5b8da0c2d 100644
--- a/include/ruby/internal/attr/const.h
+++ b/include/ruby/internal/attr/const.h
@@ -36,7 +36,7 @@
 # define RBIMPL_ATTR_CONST() /* void */
 #endif
 
-/** Enables #RBIMPL_ATTR_CONST iff. !RUBY_DEBUG. */
+/** Enables #RBIMPL_ATTR_CONST iff. ! #RUBY_DEBUG. */
 #if !RUBY_DEBUG
 # define RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONST()
 #else
diff --git a/include/ruby/internal/attr/constexpr.h b/include/ruby/internal/attr/constexpr.h
index 6d81d342a2..96b010ce6f 100644
--- a/include/ruby/internal/attr/constexpr.h
+++ b/include/ruby/internal/attr/constexpr.h
@@ -75,7 +75,7 @@
 # define RBIMPL_ATTR_CONSTEXPR(_) /* void */
 #endif
 
-/** Enables #RBIMPL_ATTR_CONSTEXPR iff. !RUBY_DEBUG. */
+/** Enables #RBIMPL_ATTR_CONSTEXPR iff. ! #RUBY_DEBUG. */
 #if !RUBY_DEBUG
 # define RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(_) RBIMPL_ATTR_CONSTEXPR(_)
 #else
diff --git a/include/ruby/internal/attr/pure.h b/include/ruby/internal/attr/pure.h
index b27adaa840..1a10540ef3 100644
--- a/include/ruby/internal/attr/pure.h
+++ b/include/ruby/internal/attr/pure.h
@@ -33,7 +33,7 @@
 # define RBIMPL_ATTR_PURE() /* void */
 #endif
 
-/** Enables #RBIMPL_ATTR_PURE iff. !RUBY_DEBUG. */
+/** Enables #RBIMPL_ATTR_PURE iff. ! #RUBY_DEBUG. */
 #if !RUBY_DEBUG
 # define RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_PURE()
 #else