Renoise Script Debugging HowTo

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:


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.

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.

Step By Step Guide

Let's debug the following small test script, paste into RENOISE_PREFERENCES/Scripts/TestPad.lua:

local function sum(a, b)
  return a + b
local c = sum(1, 2)

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.

Remote and Lua Editor debugging

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:

Autoreloading Tool Scripts

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

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: