In addition to the usual print & trace stuff via the Renoise scripting console (all 'print's will be dumped there), Renoise offers a simple command-line debugger. This debugger can even be used to debug scripts remotely; scripts running on other computers.
Please read the INTRODUCTION first to get an overview about the complete API, and scripting for Renoise in general...
Remdebug is a command-line based remote debugger for Lua, which is included with Renoise.
To use the debugger you will need:
Renoise's "remdebug" module, which can be found in "Scripts/Libraries/remdebug" (no installation required - included in Renoise)
Lua support on your system's command-line with the Lua "socket" module
The debugger will be controlled via a command-line Lua interpreter, outside of Renoise via the remdebug/controller.lua script. To start a local debug session from within Renoise you can use the function "debug.start()":
-- Opens a debugger controller in a new terminal/cmd window and -- attaches the debugger to this script. Immediately breaks execution. debug.start()
You can add this anywhere in any script that runs in Renoise. This will work in a tool's main.lua main() body, just like a local function that you include. It also works in the TestPad.lua script that is used in Renoise's Scripting Editor.
Let's debug the following small test script, paste into RENOISE_PREFERENCES/Scripts/TestPad.lua:
debug.start() local function sum(a, b) return a + b end local c = sum(1, 2) print(c) debug.stop()
Launch Renoise's scripting editor, open "TestPad.lua", and hit the "Execute" button to run the script.
If Lua is correctly installed on your system, and remdebug was found, Renoise should be frozen now, with a terminal window opened showing something like:
> "Lua Remote Debugger" > "Paused at file RENOISE_PREFERENCES_FOLDER/Scripts/TestPad.lua line 5" > > 1 debug.start() > 2 > 3 local function sum(a, b) > 4 return a + b > 5*** end > 6 > 7 local c = sum(1, 2) > 8 print(c) > 9 > 10 debug.stop() > >>
To step through the code, you can use the "s" and "n" commands in the terminal.
Let's do so by entering "s" (Return) until we've reached line 8. Anything you
type into the debugger, which is not a debugger command, will get evaluated in
your running script as an expression. So let's try this by entering: c=99
Then step over the line by entering "n" (Return) to evaluate the "print(c)"
on line 9 in the script. You should see a "99" dumped out. To watch the value
again, enter for example a print(c). You should again see a "99" dumped out.
You can also set break and watchpoints in the debugger. Type 'help' in the terminal to get more info about this. Those who are familiar with gdb on the command-line may be able to quickly get up to speed when using the most common shortcuts (c,b,q, and so on...).
Please note that although "debug.stop()" is not necessary (you can simply quit the controller at any time to exit), its recommended and will be more comfortable when running a session over and over again.
Renoise's remdebug is fully compatible with the original remdebug controller from the kepler project. This means you can, in theory, also use debugger GUIs that use the original remdebug, like Lua Eclipse or SciTE for Lua.
However, this is often a PITA to setup and configure, and might not be worth the trouble. Try at your own risk...
The debugger can also be used to remote debug scripts, scripts running on other computers. To do so, use remdebug.engine.start/stop instead of "debug". debug.start/stop is just a shortcut to remdebug.session.start/stop.
"remdebug.engine.start" will only attach the debugger to your script and break execution. You then have to run the debugger controller manually on another computer. To do so, launch the remdebug.controller.lua file manually in a terminal:
First we start the debugger controller. To do so, open a command-line on your system and invoke the remdebug/controller.lua script. You should see something like:
lua RENOISE_RESOURCE_FOLDER/Scripts/Libraries/remdebug/controller.lua "Lua Remote Debugger" "Run the program you wish to debug with 'remdebug.engine.start()' now"
Now you can connect to this controller by running a script with
remdebug.engine.start(), configured to find the controller on another
machine (or the same one.)
require "remdebug.engine" -- default config is "localhost" on port 8171 remdebug.engine.configure { host = "some_host", port = 1234 } remdebug.engine.start()
When working with Renoise's Scripting Editor, saving a script will automatically reload the tool that belongs to the file. This way you can simply change your files and immediately see/test the changes. When changing any files that are part of the "Libraries" folder, all scripts will get reloaded.
When working with an external text editor, you can enable the following debug option somewhere in the tool's main.lua file:
_AUTO_RELOAD_DEBUG = function() -- do tests like showing a dialog, prompts whatever, or simply do nothing end
As soon as you save your script outside of Renoise, and then focus Renoise again (alt-tab to Renoise, for example), your script will instantly get reloaded and the notifier is called.
If you don't need a notifier to be called each time the script reloads, you can also simply set _AUTO_RELOAD_DEBUG to true:
_AUTO_RELOAD_DEBUG = true