--[[============================================================================
Renoise Script Debugging HowTo
============================================================================]]--

Besides the usual print & trace stuff via the Renoise scripting console
(all 'print's will be dumped there), Renoise also offers a simple command-line
debugger which can even debug scripts remotely: scripts running on other
computers.

Please read the INTRODUCTION.txt first to get an overview about the complete
API, and scripting in Renoise in general...


--==============================================================================
-- Remdebug
--==============================================================================

Remdebug is a command-line based remote debugger for Lua, which is included in
Renoise. 


--------------------------------------------------------------------------------
-- 1. Prerequisites
--------------------------------------------------------------------------------

* 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
  (Windows: http://code.google.com/p/luaforwindows/)
  (OSX, Linux: http://luabinaries.luaforge.net/ and
               http://luaforge.net/projects/luasocket/) or
  (Linux: apt-get install lua5.1 liblua5.1-socket2)


--------------------------------------------------------------------------------
-- 2. Overview
--------------------------------------------------------------------------------

* The debugger will be controlled via a system 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. So this will 
work in a tools main.lua main body, just like in local function that you 
include. It also works in the TestPad.lua script that is used in Renoise's 
Scripting Editor. We will use this file now for the step by step guide: 


--------------------------------------------------------------------------------
-- 3. Step By Step Guide
--------------------------------------------------------------------------------

Let's debug the following small test script that we've pasted 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 in the editor to run the script.

  If Lua is correctly installed on your system, and remdebug was found, Renoise 
  should be frozen now, and a terminal window got 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.
  Lets 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 use it as usual 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...


--------------------------------------------------------------------------------
-- 4. 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.

This often is really hard to setup and configure, and thus might not be
worth the trouble. Try if this works for you...

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()


--==============================================================================
-- 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 a 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
