Hi,
I created a short SVN_DBG overview for the debugging page in the
HACKING GUIDE.
Please let me know if this can be improved.
Gabriela
[[[
Add section describing usage of the SVN_DBG macro to the Community Guide
page 'Debugging Subversion'.
* publish/docs/community-guide/debugging.part.html
(svn_dbg): Provide overview, links, hints and sample patches.
* publish/docs/community-guide/debugging.toc.html
(): Add link to section svn_dbg.
Suggested by: danielsh
]]]
(Just the raw text for ease of reading)
-------------------------------------------------------------------
Debugging with SVN_DBG
The SVN_DBG debugging tool is a C Preprocessor macro that sends
debugging output to stdout (by default) or stderr whilst not
interfering with the SVN test suite.
It provides an alternative to a debugger such as gdb, or
alternatively, extra information to assist in the use of a
debugger. It might be especially useful in situations where a
debugger cannot be used.
The svn_debug module contains two debug aid macros that print the
file:line of the call and printf-like arguments to the
#SVN_DBG_OUTPUT stdio stream (#stdout by default):
SVN_DBG( ( const char *fmt, ...) ) /* double braces are neccessary */
and
SVN_DBG_PROPS( ( apr_hash_t *props, const char *header_fmt, ...) )
Controlling SVN_DBG output:
* SVN_DBG is enabled whenever svn is configured with
--enable-maintainer-mode.
* The SVN test suite turns off SVN_DBG output automatically, to
suppress the output manually, set the SVN_DBG_QUIET variable
to 1 in your shell environment.
* When you are done, please be sure to remove any instances of
the SVN_DBG and SVN_DBG_PROPS macros from any code you are
committing and from any patch that you send to the
list. (AKA: Do not forget a scalpel in the patient!)
The SVN_DBG macro definitions and code are located in:
* subversion/include/private/svn_debug.h
* subversion/libsvn_subr/debug.c
Sample patch showing usage of the SVN_DBG macro:
Index: subversion/libsvn_fs_fs/fs_fs.c
===================================================================
--- subversion/libsvn_fs_fs/fs_fs.c (revision 1476635)
+++ subversion/libsvn_fs_fs/fs_fs.c (working copy)
@@ -2303,6 +2303,9 @@ get_node_revision_body(node_revision_t **noderev_p
/* First, try a cache lookup. If that succeeds, we are done here. */
SVN_ERR(get_cached_node_revision_body(noderev_p, fs, id, &is_cached,
pool));
+ SVN_DBG(("Getting %s from: %s\n",
+ svn_fs_fs__id_unparse(id),
+ is_cached ? "cache" : "disk"));
if (is_cached)
return SVN_NO_ERROR;
Sample patch showing usage of the SVN_DBG_PROPS macro:
Index: subversion/svn/proplist-cmd.c
===================================================================
--- subversion/svn/proplist-cmd.c(revision 1475745)
+++ subversion/svn/proplist-cmd.c(working copy)
@@ -221,6 +221,7 @@ svn_cl__proplist(apr_getopt_t *os,
URL, &(opt_state->start_revision),
&rev, ctx, scratch_pool));
+ /* this can be called with svn proplist --revprop -r <rev> */
+ SVN_DBG_PROPS((proplist,"The variable apr_hash_t *proplist
contains: "));
if (opt_state->xml)
{
svn_stringbuf_t *sb = NULL;
Add section describing usage of the SVN_DBG macro to the Community Guide page
'Debugging SVN'.
* publish/docs/community-guide/debugging.part.html
(svn_dbg): Provide overview, links, hints and sample patches.
* publish/docs/community-guide/debugging.toc.html
(): Add link to section svn_dbg.
Suggested by: danielsh
Index: publish/docs/community-guide/debugging.part.html
===================================================================
--- publish/docs/community-guide/debugging.part.html (revision 1479254)
+++ publish/docs/community-guide/debugging.part.html (working copy)
@@ -6,8 +6,95 @@
<!--#include virtual="debugging.toc.html" -->
-<p class="todo">TODO: document <tt>SVN_DBG</tt></p>
+<div class="h2" id="svn_dbg">
+<h2>Debugging with SVN_DBG
+ <a class="sectionlink" href="<!--#echo var="GUIDE_DEBUGGING_PAGE" -->#debugging-svn_debug"
+ title="Link to this section">¶</a>
+</h2>
+<p>The SVN_DBG debugging tool is a C Preprocessor macro that sends
+debugging output to stdout (by default) or stderr whilst not interfering
+with the SVN test suite.</p>
+
+<p>It provides an alternative to a debugger such as gdb, or
+alternatively, extra information to assist in the use of a debugger. It
+might be especially useful in situations where a debugger cannot be
+used.</p>
+
+<p>The svn_debug module contains two debug aid macros that print the
+file:line of the call and printf-like arguments to
+the <code>#SVN_DBG_OUTPUT </code> stdio stream (#stdout by
+default):</p>
+
+<pre>
+SVN_DBG( ( const char *fmt, ...) ) /* double braces are neccessary */
+</pre>
+and
+<pre>
+SVN_DBG_PROPS( ( apr_hash_t *props, const char *header_fmt, ...) )
+</pre>
+
+<p>Controlling SVN_DBG output:</p>
+<ul>
+<li>SVN_DBG is enabled whenever svn is configured
+with <code>--enable-maintainer-mode</code>.
+</li>
+<li>The SVN test suite turns off SVN_DBG output automatically, to
+suppress the output manually, set the <code>SVN_DBG_QUIET</code>
+variable to 1 in your shell environment.
+</li>
+<li>When you are done, please be sure to remove any instances of
+the <code>SVN_DBG </code> and <code>SVN_DBG_PROPS </code> macros from
+any code you are committing and from any patch that you send to the
+list. (AKA: Do not forget a scalpel in the patient!)
+</li>
+</ul>
+
+<p>The SVN_DBG macro definitions and code are located in:</p>
+<ul>
+<li><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/include/private/svn_debug.h";>
+subversion/include/private/svn_debug.h</a> </li>
+<li><a href="https://svn.apache.org/repos/asf/subversion/trunk/subversion/libsvn_subr/debug.c";>
+subversion/libsvn_subr/debug.c
+</a></li>
+</ul>
+
+<p>Sample patch showing usage of the SVN_DBG macro:</p>
+
+<pre>
+Index: subversion/libsvn_fs_fs/fs_fs.c
+===================================================================
+--- subversion/libsvn_fs_fs/fs_fs.c (revision 1476635)
++++ subversion/libsvn_fs_fs/fs_fs.c (working copy)
+@@ -2303,6 +2303,9 @@ get_node_revision_body(node_revision_t **noderev_p
+
+ /* First, try a cache lookup. If that succeeds, we are done here. */
+ SVN_ERR(get_cached_node_revision_body(noderev_p, fs, id, &is_cached, pool));
++ SVN_DBG(("Getting %s from: %s\n",
++ svn_fs_fs__id_unparse(id),
++ is_cached ? "cache" : "disk"));
+ if (is_cached)
+ return SVN_NO_ERROR;
+</pre>
+
+<p>Sample patch showing usage of the SVN_DBG_PROPS macro:</p>
+
+<pre>
+Index: subversion/svn/proplist-cmd.c
+===================================================================
+--- subversion/svn/proplist-cmd.c (revision 1475745)
++++ subversion/svn/proplist-cmd.c (working copy)
+@@ -221,6 +221,7 @@ svn_cl__proplist(apr_getopt_t *os,
+ URL, &(opt_state->start_revision),
+ &rev, ctx, scratch_pool));
++ /* this can be called with svn proplist --revprop -r <rev> */
++ SVN_DBG_PROPS((proplist,"The variable apr_hash_t *proplist contains: "));
+ if (opt_state->xml)
+ {
+ svn_stringbuf_t *sb = NULL;
+</pre>
+</div> <!-- svn_debug -->
+
<div class="h2" id="server-debugging">
<h2>Debugging the server
<a class="sectionlink" href="<!--#echo var="GUIDE_DEBUGGING_PAGE" -->#server-debugging"
Index: publish/docs/community-guide/debugging.toc.html
===================================================================
--- publish/docs/community-guide/debugging.toc.html (revision 1479254)
+++ publish/docs/community-guide/debugging.toc.html (working copy)
@@ -1,5 +1,6 @@
<!--#if expr='"$DOCUMENT_NAME" = "debugging.html" || "$DOCUMENT_NAME" = "community-guide.html"' -->
<ul>
+ <li><a href="#svn_dbg">Debugging with SVN_DBG</a></li>
<li><a href="#server-debugging">Debugging the server</a></li>
<li><a href="#net-trace">Tracing network traffic</a></li>
<li><a href="#tracing-memory-leaks">Tracking down memory leaks</a></li>
@@ -6,6 +7,7 @@
</ul>
<!--#else -->
<ul>
+ <li><a href="debugging.html#svn_dbg">Debugging with SVN_DBG</a></li>
<li><a href="debugging.html#server-debugging">Debugging the server</a></li>
<li><a href="debugging.html#net-trace">Tracing network traffic</a></li>
<li><a href="debugging.html#tracing-memory-leaks">Tracking down memory leaks</a></li>
