1 files changed, 253 insertions, 0 deletions
diff --git a/www/debugging.html b/www/debugging.html
new file mode 100644
index 0000000..4de2811
--- /dev/null
+++ b/www/debugging.html
@@ -0,0 +1,253 @@
+<!DOCTYPE html>
+<html><head>
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<link href="sqlite.css" rel="stylesheet">
+<title>Hints for Debugging SQLite</title>
+<!-- path= -->
+</head>
+<body>
+<div class=nosearch>
+<a href="index.html">
+<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
+</a>
+<div><!-- IE hack to prevent disappearing logo --></div>
+<div class="tagline desktoponly">
+Small. Fast. Reliable.<br>Choose any three.
+</div>
+<div class="menu mainmenu">
+<ul>
+<li><a href="index.html">Home</a>
+<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
+<li class='wideonly'><a href='about.html'>About</a>
+<li class='desktoponly'><a href="docs.html">Documentation</a>
+<li class='desktoponly'><a href="download.html">Download</a>
+<li class='wideonly'><a href='copyright.html'>License</a>
+<li class='desktoponly'><a href="support.html">Support</a>
+<li class='desktoponly'><a href="prosupport.html">Purchase</a>
+<li class='search' id='search_menubutton'>
+<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
+</ul>
+</div>
+<div class="menu submenu" id="submenu">
+<ul>
+<li><a href='about.html'>About</a>
+<li><a href='docs.html'>Documentation</a>
+<li><a href='download.html'>Download</a>
+<li><a href='support.html'>Support</a>
+<li><a href='prosupport.html'>Purchase</a>
+</ul>
+</div>
+<div class="searchmenu" id="searchmenu">
+<form method="GET" action="search">
+<select name="s" id="searchtype">
+<option value="d">Search Documentation</option>
+<option value="c">Search Changelog</option>
+</select>
+<input type="text" name="q" id="searchbox" value="">
+<input type="submit" value="Go">
+</form>
+</div>
+</div>
+<script>
+function toggle_div(nm) {
+var w = document.getElementById(nm);
+if( w.style.display=="block" ){
+w.style.display = "none";
+}else{
+w.style.display = "block";
+}
+}
+function toggle_search() {
+var w = document.getElementById("searchmenu");
+if( w.style.display=="block" ){
+w.style.display = "none";
+} else {
+w.style.display = "block";
+setTimeout(function(){
+document.getElementById("searchbox").focus()
+}, 30);
+}
+}
+function div_off(nm){document.getElementById(nm).style.display="none";}
+window.onbeforeunload = function(e){div_off("submenu");}
+/* Disable the Search feature if we are not operating from CGI, since */
+/* Search is accomplished using CGI and will not work without it. */
+if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
+document.getElementById("search_menubutton").style.display = "none";
+}
+/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
+function hideorshow(btn,obj){
+var x = document.getElementById(obj);
+var b = document.getElementById(btn);
+if( x.style.display!='none' ){
+x.style.display = 'none';
+b.innerHTML='show';
+}else{
+x.style.display = '';
+b.innerHTML='hide';
+}
+return false;
+}
+var antiRobot = 0;
+function antiRobotGo(){
+if( antiRobot!=3 ) return;
+antiRobot = 7;
+var j = document.getElementById("mtimelink");
+if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
+}
+function antiRobotDefense(){
+document.body.onmousedown=function(){
+antiRobot |= 2;
+antiRobotGo();
+document.body.onmousedown=null;
+}
+document.body.onmousemove=function(){
+antiRobot |= 2;
+antiRobotGo();
+document.body.onmousemove=null;
+}
+setTimeout(function(){
+antiRobot |= 1;
+antiRobotGo();
+}, 100)
+antiRobotGo();
+}
+antiRobotDefense();
+</script>
+
+
+<h1 align='center'>Debugging Hints</h1>
+
+<p>
+The following is a random assortment of techniques used by the
+SQLite developers to trace, examine, and understand the behavior of the
+core SQLite library.
+
+<p>
+These techniques are designed to aid in understanding the
+core SQLite library itself, not applications that merely use SQLite.
+
+<ol>
+<li>
+<p><b>Use the ".eqp full" option on the <a href="cli.html">command-line shell</a></b>
+
+<p>When you have a SQL script that you are debugging or trying
+to understand, it is often useful to run it in the <a href="cli.html">command-line shell</a>
+with the ".eqp full" setting.  When ".eqp" is set to FULL, the shell
+automatically shows the <a href="lang_explain.html">EXPLAIN</a> and <a href="eqp.html">EXPLAIN QUERY PLAN</a> output for
+each command prior to actually running that command.
+
+<p>For added readability, also set ".echo on" so that the output contains
+the original SQL text.
+
+<p>The newer ".eqp trace" command does everything that ".eqp full" does
+and also turns on <a href="pragma.html#pragma_vdbe_trace">VDBE tracing</a>.
+</li>
+
+<li>
+<p><b>Use compile-time options to enable debugging features.</b>
+
+<p>Suggested compile-time options include:
+<ul>
+<li><a href="compile.html#debug">-DSQLITE_DEBUG</a>
+<li><a href="compile.html#enable_explain_comments">-DSQLITE_ENABLE_EXPLAIN_COMMENTS</a>
+<li>-DSQLITE_ENABLE_TREETRACE
+<li>-DSQLITE_ENABLE_WHERETRACE
+</ul>
+</li>
+
+<p>The SQLITE_ENABLE_TREETRACE and SQLITE_ENABLE_WHERETRACE options
+are not documented in <a href="compile.html">compile-time options</a> document because they
+are not officially supported.  What they do is activate the
+".treetrace" and ".wheretrace" dot-commands in the command-line
+shell, which provide low-level tracing output for the logic that
+generates code for SELECT and DML statements and WHERE clauses, respectively.
+
+<li>
+<p><b>Call sqlite3ShowExpr() and similar from the debugger.</b>
+
+<p>When compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>, SQLite includes routines that will
+print out various internal abstract syntax tree structures as ASCII-art graphs.
+This can be very useful in a debugging in order to understand the variables
+that SQLite is working with.  The following routines are available:
+
+<ul>
+<li>  void sqlite3ShowExpr(const Expr*);
+<li>  void sqlite3ShowExprList(const ExprList*);
+<li>  void sqlite3ShowIdList(const IdList*);
+<li>  void sqlite3ShowSrcList(const SrcList*);
+<li>  void sqlite3ShowSelect(const Select*);
+<li>  void sqlite3ShowWith(const With*);
+<li>  void sqlite3ShowUpsert(const Upsert*);
+<li>  void sqlite3ShowTrigger(const Trigger*);
+<li>  void sqlite3ShowTriggerList(const Trigger*);
+<li>  void sqlite3ShowTriggerStep(const TriggerStep*);
+<li>  void sqlite3ShowTriggerStepList(const TriggerStep*);
+<li>  void sqlite3ShowWindow(const Window*);
+<li>  void sqlite3ShowWinFunc(const Window*);
+</ul>
+
+<p>These routines are not APIs and are subject to change.  They are
+for interactive debugging use only.</p>
+</li>
+
+<li>
+<p><b>Breakpoints on test_addoptrace</b>
+
+<p>When debugging the <a href="opcode.html">bytecode</a> generator, it is often useful to know
+where a particular opcode is being generated.  To find this easily,
+run the script in a debugger.  Set a breakpoint on the "test_addoptrace"
+routine.  Then run the "PRAGMA vdbe_addoptrace=ON;" followed by the
+SQL statement in question.  Each opcode will be displayed as it is
+appended to the VDBE program, and the breakpoint will fire immediately
+thereafter.  Step until reaching the opcode then look backwards
+in the stack to see where and how it was generated.
+
+<p>This only works when compiled with <a href="compile.html#debug">SQLITE_DEBUG</a>.
+</li>
+
+<li>
+<p><b>Using the ".treetrace" and ".wheretrace" shell commands</b>
+
+<p>When the command-line shell and the core SQLite library are
+both compiled with <a href="compile.html#debug">SQLITE_DEBUG</a> and
+SQLITE_ENABLE_TREETRACE and SQLITE_ENABLE_WHERETRACE, then the
+shell has two commands used to turn on debugging facilities for the
+most intricate parts of the code generator - the logic dealing with
+SELECT statements and WHERE clauses, respectively.
+The ".treetrace" and ".wheretrace" commands each take a numeric
+argument which can be expressed in hexadecimal.  Each bit turns on
+various parts of debugging.  Values of "0xfff" and "0xff" are commonly
+used.  Use an argument of "0" to turn all tracing output back off.
+</li>
+
+<li>
+<p><b>Using the ".breakpoint" shell command</b>
+
+<p>The ".breakpoint" command in the CLI does nothing but invoke the
+procedure named "test_breakpoint()", which is a no-op.
+
+<p>If you have a script and you want to start debugging at some point
+half-way through that script, simply set a breakpoint in gdb (or whatever
+debugger you are using) on the test_breakpoint() function, and add a
+".breakpoint" command where you want to stop.  When you reach that first
+breakpoint, set whatever additional breakpoints are variable traces you
+need.
+
+<li>
+<p><b>Disable the <a href="malloc.html#lookaside">lookaside memory allocator</a></b>
+
+<p>When looking for memory allocation problems (memory leaks, use-after-free
+errors, buffer overflows, etc) it is sometimes useful to disable the
+<a href="malloc.html#lookaside">lookaside memory allocator</a> then run the test under valgrind or MSAN or
+some other heap memory debugging tool.
+The lookaside memory allocator can 
+be disabled at start-time using the <a href="c3ref/c_config_covering_index_scan.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>
+interface.  The <a href="cli.html">command-line shell</a> will use that interface to
+disable lookaside if it is started with the "--lookaside 0 0"
+command line option.
+</li>
+</ol>
+<p align="center"><small><i>This page last modified on  <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink"  data-href="https://sqlite.org/docsrc/finfo/pages/debugging.in?m=ffab87c7343ef0cf5">2022-04-06 18:55:14</a> UTC </small></i></p>
+