The Lua debugger works in a different way of the traditional debuggers. You will not start debugging a specified file or string, instead the debugger will be activated or not for next executions. Because of this philosophy we always set the debug compilation flag to 1, independent of the $debug in the source code, but this will not be valid for pre-compiled code.
When the debugger is active, every Lua execution pass trough it. But when the debugger is paused, you can execute any code (for example in the command line of the Console window) that it will not pass trough the debugger. By default the debugger will pause on the first line executed of the main function.
Be careful when the debugger is active, because the interface message loop is handled in a different way than when it is not active. So despite you can do things with the debugger active, some results may be weird, like you terminate the application and it doesn't end, click on buttons and they do not respond immediately and so on.
"Stop" will stops execution of every Lua dostring or dofile or callfunction being executed. It is far more than a lua_error call.
"Pause" will break the execution in the current line. This is useful when executing a long loop, but because of the slow refresh of interface message queue the command maybe not immediately. This is valid for the 'Stop" button too.
"Play" continues executing from a PAUSED state. The execution will stop only if there is a breakpoint or the user click on "Pause" or "Stop". When the code is being executed the source code is NOT displayed in the source multiline, but if you set the Animate Delay for 200ms you will seen a nice animation of the code execution.
"Step" executes until one of the step break conditions is reached. If Step Mode is Lines then the step break condition is the number of lines specified, that is usually 1. But if a function is executed, the step depends on the Step Function state. If it is Into the execution will step into the function and continue to count lines. If it is Over, the function will be executed and when it returns the step line counting will continue. If Step Mode is Out the execution will proceed until it steps out of the current stack level. If you step out from main, it will execute until ends. When you step out from a function or step over a function the breakpoits that are set in deeper levels of the stack or inside functions will still break the execution.
The source multiline displays the source code of the current file/string being executed. The current line number will be selected each time you step in the execution. Because you can deselect it when scrolling in the code, the button "->" will return the selection to the current line.
When a dotring or a dofile is excuted during a debug step into, the new file or string is loaded. To check for the current directory you can use the "pwd()" functio, It is an alias to "print(getcwd())". You can also use "chdir(dir_name)" to change the current directory.
Breakpoints can be set on any line of any file, even if the line will not be executed, so be careful. You can add a breakpoint clicking on B in the source multiline (in fact this will toggle a break in the current line) or selecting "Breakpoint >>" then "Add File...", this will ask you for a file and after that a line number.
When you are PAUSED somewhere in the code, the call stack is displayed in this list box.
Only the function names appears in the list. if you want more information of one level, select it and click on Print, and will be displayed in the Output muliline of the Console window.
Stack Level 0: -- shows the current level func, at line 16 -- shows the current line at that level inside function "func" [defined in the file "func.lua" at line 9] -- shows information about function "func"You can also print information about all the levels in the stack, just click on Print All.
Stack: 0| func, at line 16 [defined in the file "func.lua" at line 9] 1| <main of "func.lua">, at line 22 [defined in the file "func.lua"]
When you are PAUSED somewhere in the code, the list of the local variables at the current level of the stack is displayed here. If you select another level of the call stack, then you will see the local variables at that level.
Variables that are numbers or strings are displayed in the list box. But if the string is too large or the variable is not a string you can inspect its value just like entering a command in the Console window, by selecting Print (the output will be in the Output multiline of the Console Window).
You can also change the value of a local variable, just select it and click on Set. The string you entered will be evaluated before the variable is changed, so you can type expressions.
To use the Debugger inside your application you just have to include the header "ldebug.h" and call the function luaDebugCreate("parent", CloseFlag). Check the LUACMD.C file for an example. And do not forget to call utlCreateButtonImages once to initialize the toolbar images, and also luaDebugKill and utlKillButtonImages after the program ends the message loop.