1[[bbv2.util]] 2= Utilities 3 4[[bbv2.util.debugger]] 5== Debugger 6 7[[bbv2.util.debugger.overview]] 8=== Overview 9 10B2 comes with a debugger for Jamfiles. To run the debugger, 11start B2 with `b2 -dconsole`. 12 13.... 14$ b2 -dconsole 15(b2db) break gcc.init 16Breakpoint 1 set at gcc.init 17(b2db) run 18Starting program: /usr/bin/b2 19Breakpoint 1, gcc.init ( ) at /usr/share/boost-build/tools/gcc.jam:74 2074 local tool-command = ; 21(b2db) quit 22.... 23 24[[bbv2.util.debugger.running]] 25=== Running the Program 26 27The `run` command is used to start a new `b2` subprocess for debugging. 28The arguments to `run` are passed on the command line. If a child 29process is already running, it will be terminated before the new child 30is launched. 31 32When the program is paused `continue` will resume execution. The `step` 33command will advance the program by a single statement, stopping on 34entry to another function or return from the current function. `next` is 35like `step` except that it skips over function calls. `finish` executes 36until the current function returns. 37 38The `kill` command terminates the current child immediately. 39 40[[bbv2.util.debugger.break]] 41=== Breakpoints 42 43Breakpoints are set using the `break` command. The location of the 44breakpoint can be specified as either the name of a function (including 45the module name) or or a file name and line number of the form 46`file:line`. When a breakpoint is created it is given a unique id which 47is used to identify it for other commands. 48 49.... 50(b2db) break Jamfile:10 51Breakpoint 1 set at Jamfile:10 52(b2db) break msvc.init 53Breakpoint 2 set at msvc.init 54.... 55 56A breakpoint can be temporarily disabled using the `disable` command. 57While a breakpoint is disabled, the child will not stop when it is hit. 58A disabled breakpoint can be activated again with `enable`. 59 60.... 61(b2db) disable 1 62(b2db) enable 1 63.... 64 65Breakpoints can be removed permanently with `delete` or `clear`. The 66difference between them is that `delete` takes the breakpoint id while 67`clear` takes the location of the breakpoint as originally specified to 68break. 69 70.... 71(b2db) clear Jamfile:10 72Deleted breakpoint 1 73(b2db) delete 2 74.... 75 76[[bbv2.util.debugger.stack]] 77=== Examining the Stack 78 79The `backtrace` command will print a summary of every frame on the 80stack. 81 82The `print` command can be used to show the value of an expression. 83 84.... 85(b2db) print [ modules.peek : ARGV ] 86/usr/bin/b2 toolset=msvc install 87(b2db) print $(__file__) 88Jamfile.jam 89.... 90 91[[bbv2.util.debugger.misc]] 92=== Miscellaneous Commands 93 94`quit` exits the debugger. `help` describes the available commands. 95