Debugging Scripts

Debugging is long and difficult task to do. It is also a crucial state in programming project because this task have to be well done in order to bring a project successful. LuaEdit provides servaral tools to get this *painful* task done as easy as possible. This section will explain the basic actions to debug scripts with LuaEdit.

Basics
First of all, you must press the "Run" (F5) button on the "Debug Toolbar" (Picture 1.1) or by using the menu "Run/Run Script" in order to get into a debug session. This will load the script into a "Lua State" (See Lua 5.0 documentation available through the menu "?/Lua Help") and execute each valid line of you script until it reaches the end or a valid breakpoint (See documentation below for more informations about breakpoints). If an error happened while running the script, LuaEdit will display the message through a message box and through the "Messages Window" (Picture 1.2). Several debugging informations are available, once the script execution breaks on a line. Local and Global variables values are available through the "Local Variables Window" and the "Global Variables Window". Also, the "Lua Stack Window" shows all Lua's stacked variables values at the moment of the current execution and the "Call Stack Window" shows the history of all function calls made from the current script. This call stack may be useful to trace back the values of the local and global variables in previous calls.

Step by Step
A few choices are available to pursue the execution of the script. The "Step Over" (F10) and "Step Into" (F11) buttons allows to jump the function call of the current debugging line if any. If "Step into" is pressed and no function call is made on the current debugging line, the debugger will simulate the "Step Over" feature wich simply jump to the next executed line. The "Run Script to Cursor" (Ctrl+F10) button will run the script until it reaches the line where cursor is currently positioned or until the end of the script. The "Run" (F5) button will pursue the execution of the scipt if already started.

Manipulating Breakpoints
Breakpoins are very useful when debugging. To insert a breakpoint at the line where the cursor is, press the "Toggle Breakpoint" (F9) button from the debug toolbar (Picture 1.2). When debugging a script, the execution should break on a line where a breakpoint has been detected. Advanced manipulation and features for breakpoint are available through the "Breakpoints Window" (Picture 1.3) such as disabling/enabling breakpoints. A disabled breakpoint won't break the execution of the script but will leave the breakpoint marker (maroon/grayed) on the code editor. To disable/enable a breakpoint, simply check/uncheck the checkbox on the left of the breakpoint name in the "Breakpoints Window". You can also set a condition on a breakpoint wich will be evaluated when the scipt is runnning to determine whether or not it will break on this breakpoint. The evaluation of the condition should always return "true" or "false". You can also remove, add and goto breakpoints through the "Breakpoints Window".

Watching Variables
In Lua, just like other languages, variables are very important for the code to be working. Variables in programming are abstract concept since they are located in the RAM and that their content may change several times in a few operations. That's why the "Watch" window (Picture 1.4) becomes a useful tool for the programmer. Since Lua logic is based on tables, LuaEdit has adapted a watch window wich act like the MS Visual Studio .Net^® one. This means that all the content of any tables (variables and nested tables) can be explored in a hierarchic way. This can be extremely useful when complex tables are part of your code. The watch window also display regular variables content.

NOTE: Any complex data such as user data and functions will be displayed as a pointer address. See picture 1.4 for details.

Using the Initializer
LuaEdit offer the possibility to bind the code to a Dynamic-Link Library (DLL) before the execution of the script. This can be very useful if any function call in the scripts refer to some C++ functions defined in such a file. By using the initializer, you will prevent error raised by Lua 5.0 because it can't find the reference of the function call. To set the initializer, just popup the "Project Options Window" by clicking on the "Project/Options..." menu. Once the windowis displayed, select the "Debug" tab and enter the full path of the DLL or simply click on the browse button and open the DLL from the browse dialog. In order to make this feature working your DLL must export a function of one of these prototype according to the right language it has been built from:

• Delphi:  LuaDebug_Initializer(L: PLua_State): Integer; cdecl; 
• C/C++:  int LuaDebug_Initializer(lua_State *L); 

• Delphi:
  •  function LuaEditDebugOpen: Plua_State;   // Function to open the lua_state structure with LuaEdit
  •  procedure LuaEditDebugClose(LuaState: Plua_State);   // Function to close the lua_state structure with LuaEdit
• C/C++:
  •  lua_State *LuaEditDebugOpen(void);   // Function to open the lua_state structure with LuaEdit
  •  void LuaEditDebugClose(lua_State *LuaState);   // Function to close the lua_state structure with LuaEdit

• Delphi:
  •  function LuaEditDebugStart(LuaState: Plua_State; Code: PChar): Integer; 
  •  function LuaEditDebugStartFile(LState: Plua_State; Filename: PChar): Integer; 
• C/C++:
  •  int LuaEditDebugStart(lua_State *LuaState, char *Code); 
  •  int LuaEditDebugStartFile(lua_State *LState, char *Filename);