Debugging

[TOC]

Sometimes we need a better way to Debug our FWL Scripts i describe 2 easy ways how this can be done.

Command Line Interface (CLI)

In this example we use a easy and lightweight Solution from slembcke (Scott Lembcke) · GitHub Copy from this Project https://github.com/slembcke/debugger.lua only debugger.lua into FWL Modules Folder.

Make sure your Script Folder is empty or the Debugger starts , after FWL is loaded (Loading Screen XPLANE)

Start X-Plane from a command-line, How to is well written here --> https://www.x-plane.com/kb/using-command-line-options/

In OSX like this:

larsurban/Volumes/SSD2go\ PKT/X-Plane\ 11\ stable/X-Plane.app/Contents/MacOS/X-Plane --no_fbos

Adapt your own Script like this: (this Text was copied from the project)

local dbg = require("debugger")
-- Consider enabling auto_where to make stepping through code easier to follow.
dbg.auto_where = 2

function foo()
	-- Calling dbg() will enter the debugger on the next executable line, right before it calls print().
	-- Once in the debugger, you will be able to step around and inspect things.
	dbg()
	print("Woo!")

	-- Maybe you only want to start the debugger on a certain condition.
	-- If you pass a value to dbg(), it works like an assert statement.
	-- The debugger only triggers if it's nil or false.
	dbg(5 == 5) -- Will be ignored

	print("Fooooo!")
end

foo()

-- You can also wrap a chunk of code in a dbg.call() block.
-- Any error that occurs will cause the debugger to attach.
-- Then you can inspect the cause.
-- (NOTE: dbg.call() expects a function that takes no parameters)
dbg.call(function()
	-- Put some buggy code in here:
	local err1 = "foo" + 5
	local err2 = (nil).bar
end)

-- Lastly, you can override the standard Lua error() and assert() functions if you want:
-- These variations will enter the debugger instead of aborting the program.
-- dbg.call() is generally more useful though.
local assert = dbg.assert
local error = dbg.error

If we encounter now a "Bug" in our Script, we can see it in our Terminal:

debugger.lua: Loaded for LuaJIT 2.0.5
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/tutorial.lua:88 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/tutorial.lua:0
debugger.lua>

And now ? Type "h" and press Enter --> you can see all possible Shortcuts for Debugging

debugger.lua> h
  <return> => re-run last command
  c(ontinue) => continue execution
  s(tep) => step forward by one line (into functions)
  n(ext) => step forward by one line (skipping over functions)
  f(inish) => step forward until exiting the current function
  u(p) => move up the stack by one frame
  d(own) => move down the stack by one frame
  w(here) [line count] => print source code around the current line
  e(val) [statement] => execute the statement
  p(rint) [expression] => execute the expression and print the result
  t(race) => print the stack trace
  l(ocals) => print the function arguments, locals and upvalues.
  h(elp) => print this message
  q(uit) => halt execution
debugger.lua>

You can write "w" in your Terminal and press again Enter, you see then the starting point after your dbg() Statement

debugger.lua> w
  83    	(c =  Continue execution)
  84    ]]
  85    end
  86
  87    dbg()
  88 => print(str1)
  89
  90    func1()
  91    print(str2)
  92
  93    func2()
debugger.lua>

Follow the whole Tutorial.lua from this project to warm up with this CLI Debugger. You can set statements, print variables ... everything what you need to debug your script.

Real World example

FLW can not tell us whats going on, we see nothing in detail in our XPLANE log nor information in FlyWithLua_Debug.txt ! We only see this on our Screen and the Script Name himself.

and this

FlyWithLua_Debug.txt

[000948] FlyWithLua Debug Info: The Lua stack contains the following elements: [000949] caught (...) exception

XPLANE log.txt

FlyWithLua Info: Lua engine (re)started. LUA_RUN =19, SDK_VERSION = 301, XPLANE_VERSION = 11410, XPLANE_LANGUAGE = German and XPLANE_HOSTID = 1 FlyWithLua Info: HID access initialized. FlyWithLua Info: FlyWithLua.ini full path /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Internals/FlyWithLua.ini FlyWithLua Info: Discovered 10 HID devices. FlyWithLua Info: Load ini file. FlyWithLua Info: Searching for Lua script files FlyWithLua Info: Sorting Lua script files FlyWithLua Info: Start loading script file /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua FlyWithLua Error: CopyDataRefsToLua() failed, can't execute script file: /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua FlyWithLua Error: Unable to load script file /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua FlyWithLua Info: Loading time for all scripts is 0.028823 sec. FlyWithLua Debug Info: The Lua stack contains the following elements: caught (...) exception

FlyWithLua Error: Unable to load script file /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua

Now that we know it is located in script --> xsil_autoupdater.lua , we add our Debug Stuff inside the script ! Remember ... we have no idea when the script crashed, we use always in this case the first lines, before we call any code !

--DEBUG START
local dbg = require("debugger")
local assert = dbg.assert
local error = dbg.error
dbg()
--DEBUG END

Reload all LUA script files --> Menü --> Plugin -->FlyWithLua

Have a look in your Terminal now ! Enter "w" --> and we see our break point

debugger.lua> w
  35    local assert = dbg.assert
  36    local error = dbg.error
  37    dbg()
  38    --DEBUG END
  39
  40 => local http_socket = require("socket.http")
  41    local ltn12 = require("ltn12")
  42    local lfs = require("lfs_ffi") -- https://github.com/sonoro1234/luafilesystem
  43    local jjjLib1 = require("jjjLib1")
  44    local graphics = require("graphics")
  45    local toast = require("toast")
debugger.lua>

Enter "n" for:

n(ext) => step forward by one line (skipping over functions)

until we get the line of code where the Script has an issue. HINT --> ( [return] - re-run last command ) Again our Green and Red Message inside X-Plane ... but we see also we jumpt out in line 45

debugger.lua> n
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:41 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:0
debugger.lua>
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:42 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:0
debugger.lua>
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:43 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:0
debugger.lua>
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:44 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:0
debugger.lua>
/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:45 in chunk at /Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:0
debugger.lua>

After we know that our toast lib can`t be loaded we can capsulate this function with a dbg.call

--DEBUG START
local dbg = require("debugger")
local assert = dbg.assert
local error = dbg.error
dbg()
--DEBUG END

local http_socket = require("socket.http")
local ltn12 = require("ltn12")
local lfs = require("lfs_ffi") -- https://github.com/sonoro1234/luafilesystem
local jjjLib1 = require("jjjLib1")
local graphics = require("graphics")
--local toast = require("toast")

dbg.call(function()
	-- Put some buggy code in here:
	local toast = require("toast")
end)

We reload our script and starting again with "n(ext)" until we hit something like this

debugger.lua>
Debugger stopped on error in dbg.call(): "...esources/plugins/FlyWithLua/Scripts/xsil_autoupdater.lua:49: module 'toast' not found:\
\9no field package.preload['toast']\
\9no file './toast.lua'\
\9no file '/usr/local/share/luajit-2.0.5/toast.lua'\
\9no file '/usr/local/share/lua/5.1/toast.lua'\
\9no file '/usr/local/share/lua/5.1/toast/init.lua'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Internals/toast.lua'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Internals/toast/init.lua'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Modules/toast.lua'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Modules/toast/init.lua'\
\9no file './toast.so'\
\9no file '/usr/local/lib/lua/5.1/toast.so'\
\9no file '/usr/local/lib/lua/5.1/loadall.so'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Internals/toast_64.so'\
\9no file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Modules/toast_64.so'"

Reason for this ? In my case forgot to copy my new Module in our FWL Module Folder ;-)

Ok now after this Module was copied ... again the same message ... caught (...) exception ... We don´t change our Debug lines, god thing is our debugger follow the code ! Again press "n" with dbg.call in our script

debugger.lua>
Debugger stopped on error in dbg.call(): "error loading module 'toast' from file '/Volumes/SSD2go PKT/X-Plane 11 stable/Resources/plugins/FlyWithLua/Modules/toast.lua':\
\9...11 stable/Resources/plugins/FlyWithLua/Modules/toast.lua:81: unexpected symbol near '='"

After this detail we can inspect our line of Code

This was a pure Typo in this case inside a Module. --> correct was :

if toast[i] ~= nil then

Both topics were identified within 1 minute ! Without debugger much longer ;-)

Graphical User Interface (GUI)