Jump to: navigation, search

Difference between revisions of "Koneki/LDT/User Guide/Concepts/Debugger"

< Koneki‎ | LDT‎ | User Guide‎ | Concepts
(Windows)
Line 1: Line 1:
 
=Lua Development Tools Debugger=
 
=Lua Development Tools Debugger=
The debugger is an interesting feature, but enabling it require a little explanation. The require steps allowing to run debugger are explained below.
+
==Remote Debug==
==Install Lua==
+
The Debugger of Lua Development Tools is based on DBGP protocol.<br/>
The debugger client is written in '''Lua 5.1''' as I'm writing. In order to be able to run it, Lua is required. You can [http://www.lua.org/download.html download Lua here].
+
The IDE contains a DBGP server. To connect to this one and begin remote/attach debugging, you need to get our [[Media:Debugger_lua.zip|DBGP lua client]].
Under OSX and Linux Lua is available in software manager repositories.
+
==Install LuaRocks==
+
We need LuaSocket in order to get it, the nicer way is to install it through LuaRocks. LuaRocks is a component manager for Lua such as Pear for PHP or Gems for Ruby. Here is the [http://luarocks.org/en/Download link to install it].
+
Under OSX and Linux LuaRocks is available in software manager repositories.
+
==Install LuaSocket==
+
Once you installed LuaRocks, just ask for LuaSocket. On my Linux it looks like
+
% sudo luarocks install luasocket
+
==Install debugger==
+
Beforehand, you must download provided archive: [[Media:Debugger_lua.zip]].
+
===Linux ( OSX compatible ) ===
+
Then, decide where you want to install it. In my case it is ''/home/kkinfoo/.bin/''.
+
* Extract archive
+
* Edit ''run'' script
+
* Update the '''INSTALL_DIR''' variable to meet installation directory, in my case ''"/home/kkinfoo/.bin/debugger_lua"''
+
* Move '''debugger_lua''' directory to install directory. In my case:
+
% cp -r debugger_lua/ /home/kkinfoo/.bin/
+
* Create symbolic link to make command available anywhere
+
% sudo ln -s  /path/to/debugger_lua/run /usr/bin/debugger_lua
+
# In my case
+
% sudo ln -s  /home/kkinfoo/.bin/debugger_lua/run /usr/bin/debugger_lua
+
* It is all set
+
% debugger_lua
+
No input file given
+
Command usage:
+
    /usr/bin/debugger_lua <filename.lua> Launches debugger on specified file
+
    /usr/bin/debugger_lua --help This help
+
===Windows===
+
Windows is not fully supported yet, you can try to edit provided ''.bat'' script.
+
  
==Finally, how to start a debugger session==
+
===DBGP Client===
===Create and run launch configuration===
+
The DBGP Lua client is composed of two lua files ([http://git.eclipse.org/c/koneki/org.eclipse.koneki.ldt.git/plain/plugins/org.eclipse.koneki.ldt.debug.core/script/debugger.lua debugger.lua] and [http://git.eclipse.org/c/koneki/org.eclipse.koneki.ldt.git/plain/plugins/org.eclipse.koneki.ldt.debug.core/script/debugintrospection.lua debugintrospection.lua]).<br/>
In IDE side everthing is set up to allow debugging. You just learnt about setting up debugger client. You just need few configuration tips.
+
It runs on unix like OS and windows (XP and later). It is written in '''Lua 5.1''' and '''was dependant of lua-socket'''.<br/>
====IDE side configuration====
+
''You could get lua on http://www.lua.org/download.html and install lua-socket thanks to [http://luarocks.org/en/Download luarocks] or via your official OS repositories.''<br/>
Go to ''Window > Preferences > Dynamic Languages > Debug'', you will have the UI below. Make sure that selected port is of ''Custom'' type and is the same as in '''DBGP_IDEPORT''' from '''previous run script'''. This post is used for communication between IDE and Lua debugger client. If those ports differ, '''debugger won't work'''.
+
[[Image:DebugUI.png|center]]
+
====Launch configuration====
+
Creating a '''Remote Lua Application''', you will have following window. '''Working directory''' field is to specify path difference when you are debugging a remote target. It allow debugger to strip this part of the path and match distant files with workspace ones.
+
[[Image:LaunchConfiguration.png|center]]
+
  
===Run command===
+
To use it, you must have this two files in your lua path.<br/>
Once you clicked '''Debug''', IDE will wait for debugger client response. In order to provide it, you must run provided debugger code with debugged file as parameter.
+
To begin the connection, you must execute this lua code :
====Linux (OSX compatible)====
+
> local initconnection = require("debugger")
If you installed the command as described above, you just have to run:
+
> initconnection(host, port, idekey)
  % debugger_lua fileToDebug.lua
+
or shortly
====Windows====
+
> require("debugger")(host, port, idekey)
In provided archive, edit ''test.bat'', replace ''myapp.lua'' with your application source path. Save and execute it.
+
 
 +
* '''host''': the host name or the ip address of the DBGP server (so of your ide).
 +
** if host is nil, the DBGP_IDEHOST env var is used.
 +
** if the env var is nil, the default value '127.0.0.1' is used.
 +
* '''port''': the port of the DBGP server (must be configured in the IDE).
 +
** if port is nil, the DBGP_IDEPORT env var is used.
 +
** if the env var is nil, the default value '10000' is used.
 +
* '''idekey''': a string which is used as session key (must be configured in the IDE).
 +
** if IDEKEY is nil, the DBGP_IDEKEY env var is used.
 +
** if the env var is nil, the default value 'luaidekey' is used.
 +
 
 +
So, To debug your application you could do :  
 +
  lua -e "require('debugger')("idehost","ideport");" MyApp.lua  
 +
 
 +
===GBGP Server===
 +
The DBGP Server is integrated in LDT.<br/>
 +
To allow it to accept debug session, you must create a new '''Remote Lua Application''' launch configuration, then launch it. 
 +
 
 +
Go in '''Run/Debug Configurations...'''.
 +
[[Image:LaunchConfiguration.png|center]]<br/>
 +
* '''Project''' : Set the ldt project in your workspace which include the lua source file of the application you want to debug. <br/> 
 +
* '''IdeKey''' : Default value is luaidekey, if you need to debug more than one application at the same time, you should change it to associate a launchconfiguration to only one application to debug.<br/>
 +
* '''Remote Source Mapping''' : use to make the mapping between the source file used at runtime and the source file in your ide workspace.
 +
For exemple if your run your application like this :
 +
$cd /my/runtime/path
 +
$lua -e "require('debugger')();" MyApp.lua
 +
You should define <code>/my/runtime/path</code> as working directory. ('''On Windows''' : you should use this notation <code>/x:/myruntime/path</code>)
 +
 
 +
<br/>
 +
Now you can launch it by clicking '''Debug'''. IDE will wait for debugger client connection on the port you could see in the debug view.<br/>
 +
[[Image:DebugView.png|center]]
 +
 
 +
You could change the server port, in ''Window > Preferences > Dynamic Languages > Debug''.
 +
[[Image:DebugUI.png|center]]

Revision as of 12:30, 14 November 2011

Lua Development Tools Debugger

Remote Debug

The Debugger of Lua Development Tools is based on DBGP protocol.
The IDE contains a DBGP server. To connect to this one and begin remote/attach debugging, you need to get our DBGP lua client.

DBGP Client

The DBGP Lua client is composed of two lua files (debugger.lua and debugintrospection.lua).
It runs on unix like OS and windows (XP and later). It is written in Lua 5.1 and was dependant of lua-socket.
You could get lua on http://www.lua.org/download.html and install lua-socket thanks to luarocks or via your official OS repositories.

To use it, you must have this two files in your lua path.
To begin the connection, you must execute this lua code :

> local initconnection = require("debugger")
> initconnection(host, port, idekey)

or shortly

> require("debugger")(host, port, idekey)
  • host: the host name or the ip address of the DBGP server (so of your ide).
    • if host is nil, the DBGP_IDEHOST env var is used.
    • if the env var is nil, the default value '127.0.0.1' is used.
  • port: the port of the DBGP server (must be configured in the IDE).
    • if port is nil, the DBGP_IDEPORT env var is used.
    • if the env var is nil, the default value '10000' is used.
  • idekey: a string which is used as session key (must be configured in the IDE).
    • if IDEKEY is nil, the DBGP_IDEKEY env var is used.
    • if the env var is nil, the default value 'luaidekey' is used.

So, To debug your application you could do :

lua -e "require('debugger')("idehost","ideport");" MyApp.lua 

GBGP Server

The DBGP Server is integrated in LDT.
To allow it to accept debug session, you must create a new Remote Lua Application launch configuration, then launch it.

Go in Run/Debug Configurations....

LaunchConfiguration.png

  • Project : Set the ldt project in your workspace which include the lua source file of the application you want to debug.
  • IdeKey : Default value is luaidekey, if you need to debug more than one application at the same time, you should change it to associate a launchconfiguration to only one application to debug.
  • Remote Source Mapping : use to make the mapping between the source file used at runtime and the source file in your ide workspace.

For exemple if your run your application like this :

$cd /my/runtime/path
$lua -e "require('debugger')();" MyApp.lua 

You should define /my/runtime/path as working directory. (On Windows : you should use this notation /x:/myruntime/path)


Now you can launch it by clicking Debug. IDE will wait for debugger client connection on the port you could see in the debug view.

DebugView.png

You could change the server port, in Window > Preferences > Dynamic Languages > Debug.

DebugUI.png