Add support for compile time setting of debug stream

Also add some notes on macros that were redefined as part of an
experimental downstream build as an Rcpp package. These notes
are intended to prevent accidental change and the macros may
get promoted to being formally documented if this approach works
and the R package is published.

Author: jeromekelleher

c/tskit/core.c

@@ -1041,7 +1041,7 @@ FILE *
 tsk_get_debug_stream(void)
 {
     if (_tsk_debug_stream == NULL) {
-        _tsk_debug_stream = stdout;
+        _tsk_debug_stream = TSK_DEFAULT_DEBUG_STREAM;
     }
     return _tsk_debug_stream;
 }

c/tskit/core.h

@@ -511,7 +511,7 @@ disallowed (use compute_mutation_times?).
 */
 #define TSK_ERR_DISALLOWED_UNKNOWN_MUTATION_TIME                    -510
 
-/** 
+/**
 A mutation's parent was not consistent with the topology of the tree.
  */
 #define TSK_ERR_BAD_MUTATION_PARENT                                 -511
@@ -971,6 +971,12 @@ not be freed by client code.
 */
 const char *tsk_strerror(int err);
 
+/* Redefine this macro in downstream builds if stdout is not the
+ * approriate stream to emit debug information when the TSK_DEBUG
+ * flag is passed to supporting functions (e.g. in R).
+ */
+#define TSK_DEFAULT_DEBUG_STREAM stdout
+
 #ifdef TSK_TRACE_ERRORS
 
 static inline int
@@ -981,6 +987,11 @@ _tsk_trace_error(int err, int line, const char *file)
     return err;
 }
 
+/*
+Developer note: this macro may be redefined as part of compilation for
+an R package, and should be treated as part of the documented API
+(no changes).
+*/
 #define tsk_trace_error(err) (_tsk_trace_error(err, __LINE__, __FILE__))
 #else
 #define tsk_trace_error(err) (err)
@@ -1001,6 +1012,11 @@ means compiling without NDEBUG. This macro still asserts when NDEBUG is defined.
 If you are using this macro in your own software then please set TSK_BUG_ASSERT_MESSAGE
 to point users to your issue tracker.
 */
+/*
+Developer note: this macro may redefined as part of compilation for
+an R package, and should be treated as part of the documented API
+(no changes).
+*/
 #define tsk_bug_assert(condition)                                                       \
     do {                                                                                \
         if (!(condition)) {                                                             \