Created page with "=Overview= The ''Koneki Lua Development Tools (LDT)'' project provides plug-ins that implement a Lua IDE supporting the development of Lua scripts and applications. It adds a..."
New page
=Overview=
The ''Koneki Lua Development Tools (LDT)'' project provides plug-ins that implement a Lua IDE supporting the
development of Lua scripts and applications.
It adds a dedicated Lua perspective to the Eclipse Workbench, which, together
with features such as ''syntax highlighting'', ''scope-aware code completion'',
''code folding'', etc. which allows to structure Lua application better
(project-based organization), and boosts the productivity of Lua developers.
=Getting started=
==Create a project==
For your code to be manipulated correctly by ''Lua Development Tools'', it must be
contained into an Eclipse project having a ''Lua'' flavor. In order to do this,
you have to create a Lua Project, which will add '''Lua nature''' to your code.
In ''File > New > Lua Project'', enter a valid name and voila!
[[Image:NewLuaProject0.9.png|center]]
==Edit a Lua file==
Now that your project is created, you are ready to start working on your Lua
scripts. In every project, there is a default '''source folder''', named
''src/''. You can edit the ''main.lua'' file in it, notice that completion is
already available for Lua built in functions.
[[Image:EditingFile0.9.png|center]]
==Run a Lua script==
To run your Lua script, the file has to be contained in a Lua project.
If it is the case, you can simply right click on the file and select
''Run As > Lua Application''.
[[Image:RunAs0.9.png|center]]
[[Image:Console0.9.png|center]]
The ''Run As'' menu creates a default launch configuration for the selected file and launch it.
[[Image:RunShortcut0.9.png|center]]
==Debug a Lua script==
Simply define a ''breakpoint'' in a Lua file by right or double clicking in the first column at the beginning of the line.
Select your project in favorite debug sessions and your breakpoint should be hit.
[[Image:ToggleBreakpoint0.9.png|center]]
[[Image:DebugShortcut0.9.png|center]]
[[Image:DebugPerspective0.9.png|center]]
= Concepts =
Before diving into concepts of ''Koneki LDT'', you may need more information
about the concepts of Lua itself. In this case, you are highly encouraged to
refer to the [http://www.lua.org/manual/ Lua manual].
== Buildpath ==
It is a set of ''folder paths'' which contains sources and libraries accessible
from your project. There are several kinds of them:
* Project dependencies
* Source folders
* [[#Execution_Environment|Execution Environments]]
Some elements like ''source folders'' and ''project dependencies'' are used for
''tooling'' and ''runtime'' purposes. Some others, are used only for ''tooling''
purposes, such as [[Execution_Environments|Execution Environments]].
About ''runtime'' , source folders of ''current'' project and the ones of
projects on which it depends will be appended to
[http://www.lua.org/manual/5.1/manual.html#pdf-LUA_PATH LUA_PATH] at-once.
About ''tooling'', all elements from buildpath are parsed in order to enable some features of the IDE
such as ''code completion'', ''code navigation'' and ''TODO / Tasks''.
You can require files from your source folders as modules. Lets say in a
<code>src/</code> source path you have a <code>foo.lua</code> file, you can
write:
require 'foo'
This logic applies to sub directories, with a <code>bar.lua</code> file in
folder <code>src/sub/</code>, you can use:
require 'sub.bar'
The <code>init.lua</code> formalism is also handled. If you have an
<code>init.lua</code> file under directory <code>src/bar/</code>, you can write:
require 'bar'
'''Note''': ''Source folders'' are important, as they are processed for tooling
information. That is to say, if you write a module
'''outside of a source folder''' , it will '''not be accessible''' from another
module or script; thus, its content will not be available in e.g.
''code completion'', ''documentation'' nor ''TODO/Tasks''.
[[#Configuring_Build_paths|Configure Buildpaths]].
== Execution Environment ==
An ''Execution Environment'', is a file
containing information about the environment where a Lua application is supposed
to be run. An ''environment'' is a set of libraries available to the application
out of the box, as in ''Lua 5.1'' or ''MOAI SDK''.
The idea is to provide a file which describe elements of an environment.
Provided information allows ''Koneki LDT'' to offer better code completion, code navigation
and documentation layout.
An Execution Environment may contain:
* '''bootstrap file''': template of typical entry point for an application aiming this execution environment, so far named ''main.lua''.
* Description for '''globals''' and '''modules API'''s with [http://wiki.eclipse.org/Koneki/LDT/User_Area/Documentation_Language Lua Documentation Language] which provides:
** '''code assistance'''
** '''documentation'''
[[#Managing_Execution_Environments|Manage Execution Environments]]<br/>
[http://wiki.eclipse.org/Koneki/LDT/User_Area/Available_Execution_Environments Get an Execution Environment]<br/>
[http://wiki.eclipse.org/Koneki/LDT/User_Area/Execution_Environment_file_format Create an Execution Environment]
== Interpreters ==
In our case, an interpreter is a program, a Lua Virtual Machine, that runs your Lua
program. The most used in the Lua world might be
[http://www.lua.org/manual/5.1/manual.html#6 Lua standalone interpreter]. It
is possible to run Lua application using interpreters from Koneki LDT. There is
a JNLua based implementation available ''out of the box'', but you can use your
own.
'''Note''': if you intent to [[#Local_session|debug]] with you own
interpreter, you have to '''ensure''' that you have ''luasocket'' installed and
available from your interpreter.
[[#Managing_Interpreters|Manage interpreters]]<br/>
[[#Local_session|Debug an application using interpreters]]
== Debug ==
Debug is a common way to monitor how your program behave at runtime, step by
step. You can debug both programs that are running locally on your pc or on a remote one.
===Local Debug===
This is the typical use case, you monitor a program running on your desktop.
Your application will be executed by an interpreter referenced in Koneki LDT.
Koneki LDT will manage the [http://www.lua.org/manual/5.1/manual.html#pdf-LUA_PATH LUA_PATH]
setting to allow the interpreter to access to all files in your buildpath.
[[#Buildpath|Concepts Buildpath]]<br/>
[[#Interpreters|Concepts Interpreters]]<br/>
[[#Local_session|Configure a Local Debug session]]
===Attach Debug===
You want to monitor an application running in a specific context that makes it impossible to be launched by ''Koneki LDT''
(for instance a Lua VM embedded in a larger C/C++ application). In that case, your
application can connect to the IDE at startup and then be monitored.
This way of debugging is called ''attached debug'', uses DBGp and is composed of two parties.
* '''DBGp Server''': In our case it is ''Koneki LDT'' waiting for an application to connect.
* '''DBGp Client''': In our case, it is the ''debugger.lua'' file executed in your debugged application which sends information about its run to ''Koneki LDT''.
This way is more flexible, but you are on your own to manage the whole runtime configuration (LUA_PATH, debugger bootstrap, ...).
[[#Attach_session|Configure an Attach Debug session]]
==== Source Mapping ====
The DBGp Server (IDE) has to know where to find the source files related to the debug information shared with the DBGp client (debugged application).
''E.g. When you set a breakpoint, the IDE need to say to the running application on which file the breakpoint must be added.''
''E.g. When the running application stops on a breakpoint of a file, the IDE must retrieve the file and open it.''
The problem is that the file executed in your Lua VM could be physically different than the source file in your IDE (in your workspace).
For instance, the code may be executed on a different host or even just duplicated in another folder on the same desktop.
To solve this problem, ''Koneki LDT'' comes with several policies, each of them having its own pros and cons:
* '''Local Resolution'''
This way to resolve the source mapping is the simplest and the most reliable. Indeed the client and the server share the same absolute path for a given resource.
This means that executed files should be in your workspace (more exactly, in the build path of your project) and you cannot use this policy to debug code running on a remote host.
* '''Module Resolution'''
In this case both the IDE and the application have their own way to retrieve a module from its name. The module name, and not an absolute path, is then used as the file ID.
This policy can be used for a remote debugging session without having to set a list of path mapping.
However it comes with some restrictions:
* Modules have to be loaded thanks to the LUA_PATH environment variable.
* Some conflicts in module name resolution may occur on the client side. Indeed module names are built from source paths returned by the Lua debug API (debug.getinfo) and the LUA_PATH that may be ambiguous.
''E.g: with <code>package.path = "/foo/bar/?.lua;/foo/?.lua"</code> and <code>debug.getinfo="@/foo/bar/baz.lua"</code> the possible module name is bar.baz or baz ''<br/>
In that case the debugger will use the shorter one. Ideally ambiguous LUA_PATH shall be avoided when this policy is chosen.
* '''Replace path Resolution'''
This policy shall be used as a fallback in case the two previous ones do not fit.
In this mode absolute paths are used on the client side and relative (to the project's build path) ones on the server (IDE) side.
In order to achieve the translation between the two kinds of paths, the client resources root path has to be set in the launch configuration.
''e.g: The root path "/foo/bar/" is set.<br/>
when an absolute file path is sent from the client (/foo/bar/baz/qux.lua), the root path is removed and a file with the resulting relative path (baz/qux.lua) is searched in the buildpath.<br/>
On the contrary, when a relative file path is sent from the server (baz/qux.lua),the root path is prepended to the path and the resulting absolute path (/foo/bar/baz/qux.lua) is used on the client side.
However this policy has some restrictions:
* The launch configuration is restricted to a single root path that has to be shared by all resources.
* All paths are case sensitive even on Windows operating systems.
* On Windows, root path has to be prefixed with "/" (e.g. /C:/foo/bar/).
'''In all cases, if a file is not found in the workspace, the source code is sent through the DBGp protocol'''
[[#Attach_session|Configure an Attach Debug session]]
===Remote Debug===
The ''Remote Debug'' launch configuration enables the debugging of applications that run on remote systems.
However these systems '''have to be''' Unix-like and allow SSH connections.
Koneki LDT will copy all the files in the project buildpath in the remote directory of your choice (default is <code>/tmp</code>), and will also manage the LUA_PATH setting allow the remote interpreter to access to those files.
[[#Remote_session|Configure a Remote Debug session]]
= Tasks =
==Configuring Build paths==
See [[#Buildpath|Buildpath]].
=== Adding source folder ===
You can add a folder in the source path by right clicking on it and select ''BuildPath > Use as Source Folder''
[[Image:AddFolderToSourcePath0.9.png|center]]
=== Adding project dependencies ===
On the project o which you want to add a dependency, right click and select''Build Path > Configure Build Path ...''.
[[Image:BuildPath.png|center]]
Then select the ''Projects'' tab and use the ''Add'' button to create the dependency.
[[Image:AddProjectDependency0.9.png|center]]
== Managing Execution Environments ==
See [[#Execution Environment|Execution Environment]].
To find preferences related to Execution Environments, go to
''Window > Preferences > Lua > Execution Environments'' and you will have the following interface.
[[Image:EePref_10.png|center]]
As you can see in previous screenshot, ''Koneki LDT'' is shipped with a ''Lua 5.1 Execution Environment''.
All Execution Environments shipped with Koneki LDT are suffixed by ''(embedded)''.
From here, is it possible to add an Execution Environment to current workspace.
First, download an Execution Environment from the [http://wiki.eclipse.org/Koneki/LDT/User_Area/Available_Execution_Environments list of available Execution Environments] or [http://wiki.eclipse.org/Koneki/LDT/User_Area/Execution_Environment_file_format create your one Execution Environment].
Then, back to the ''Execution Environments'' preference page, push ''Add'' button and select an Execution Environment file.
[[Image:EePrefAdd0.9.png|center]]
The Execution Environment is now available to use.
[[Image:EePrefAdded10.png|center]]
''If you need to override an installed embedded Execution Environment, create a new Execution Environment with the same name and add it.
All the projects using the embedded Execution Environment will automatically use the new one.''
=== Link an existing project to an Execution Environment ===
If you have created a project without Execution Environment, you can add it afterwards. Right click on a project
and select ''Build Path > Add Libraries ...''.
[[Image:EeContextSelection.png|center]]
You will have to choose between several libraries types, choose ''Lua Execution Environment''.
[[Image:EeAddLib.png|center]]
You can now choose among installed Execution Environments and press ''Finish''.
[[Image:SelectEE10.png|center]]
It is now linked to selected project.
[[Image:EeAddedToProject.png|center]]
== Managing Interpreters ==
Interpreters are used by ''Koneki LDT'' to run scripts on local computers, see [[#Interpreters|Interpreters]].
=== Embedded Interpreters ===
An embedded interpreter is an interpreter shipped with ''Koneki LDT''.
You can recognize them on the interpreter preference page, their location is mentioned as ''(embedded)''.
Currently, ''Koneki LDT'' is shipped with the JNLua (Lua 5.1) embedded interpreter, JNLua is Java binding of Lua interpreter and APIs.
=== Local Interpreters ===
To run Lua scripts in ''Koneki LDT'' using the Lua Local Application launch configuration with a locally installed Lua interpreter, you have to configure a local interpreter.
To configure an interpreter you just need the path of the interpreter executable, then you can set interpreter
arguments and some environment variables.
See below how to reference a Lua interpreter installed on your machine, and use it in ''Koneki LDT''.
To open the Interpreters preference page go to
''Window > Preferences > Lua > Interpreters'':
[[Image:InterpreterPreferencePage_1.0.png|center]]
Then, press the ''Add...'' button to configure a new interpreter and fill in the fields as described here:
* Leave the ''Interpreter type'' as ''Generic Lua''.
* You can browse your file system and locate your interpreter executable, or if the executable is in your PATH environment variable, just type its name here (e.g. <code>lua</code>).
* Give a name to the interpreter (this is mandatory).
* Add extra interpreter's arguments if needed, the same way you would on a regular command line.
* Set environment variables for this interpreter. You can modify existing variables, or create new ones. Environment variables can be exported and imported using properties files.
* Set interpreter capabilities:
** Uncheck ''Accept -e [code] as argument'' if your interpreter doesn't accept the ''-e [code]'' option which execute the given code before the rest as the official Lua interpreter do. This option is used by the ide to launch the debugger, so if this option is unchecked your are responsible to launch the debugger by your own as explain in the [[#Configuring_debug_sessions|configure debug session]] part.
** Uncheck ''Accept file as argument'' if your interpreter doesn't take the file to run as argument, this means that your interpreter have to run the Lua files by himself.
[[Image:AddInterpreter_1.0.png|center]]
[[Image:Idea.png|left]] '''Buffer configuration:'''
::Some console output problems could happen because of buffer configuration. To force the stdout buffer to be flush at each call of print your should add this argument to your interpreter:
::''-e "io.stdout:setvbuf('no')"''. For better performance you can also set the buffer policy to '''line''', see [http://www.lua.org/manual/5.1/manual.html#pdf-file:setvbuf Lua documentation].
Once you press the ''Ok'' button, the created interpreter appears in the Interpreters page. The checkbox in front of each interpreter allows to check the default interpreter used in launch configurations.
[[Image:InterpreterAdded_1.0.png|center]]
== Configuring debug sessions ==
See the [[#Debug|explanation about the three way to debug]] in ''Koneki LDT''.
=== Local session ===
According to your interpreter capabilities set in the interpreter preference if your interpreter
doesn't handle the "-e" option. You have to launch the debugger by adding the following code :
<source lang="lua">
if os.getenv('DEBUG_MODE') then require "debugger"() end
</source>
'''Note:''' The ''<code>DEBUG_MODE</code>'' environment variable is set only for ''debug'', to avoid to start the debugger for a regular ''run''.
Create a Lua Application launch configuration in the ''Debug Configuration'' menu.
[[Image:DebugConfiguration.png|center]]
In the ''Main'' tab, you can select the project, the script you want to launch and a Lua interpreter.
[[Image:MainLocalLaunchConfig.png|center]]
In the ''Arguments'' tab, you can specify interpreter arguments and script arguments.
The interpreter arguments will be merged to the ones specified at the interpreter level (in the interpreter preference page) at runtime.
[[Image:ArgumentsLocalLaunchConfig.png|center]]
In the ''Environment'' tab, you can specify environment variables for runtime.
Environment variable defined can be append
[[Image:EnvironmentLocalLaunchConfig.png|center]]
In the ''Common'' tab, you can set some settings related to launch configurations:
*Save current launch configuration in a specified file.
*See in favorite menu the launch configuration is displayed.
*Change the encoding of the launch configuration file.
*Allocate standard input/output in a console and/or redirect standard output in a file.
=== Attach session ===
The Debugger of Lua Development Tools is based on the DBGp protocol, and the IDE implements a DBGp server.<br> To connect to this server, and start remote/attach debugging, you need to use a DBGp Lua client.
==== Launching DBGp Client ====
The DBGp Lua client is a Lua file which can be downloaded through the '''Lua Attach to Application''' launch configuration UI.<br>
[[Image:DownloadDebuggerClient0.9.png|center]]
It runs on Unix-like OS and Windows (XP and later). It is written in '''Lua''' and '''depends on lua-socket'''.<br>
''You can get Lua at 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>
''If, for some reasons, you cannot use lua-socket, you could implement your own transport interface based on your own library (see the [http://git.eclipse.org/c/koneki/org.eclipse.koneki.ldt.git/tree/libraries/luadbgpclient/debugger/transport/fake.lua interface] and the [[#transport_parameter|transport parameter]])''<br>
To use it, you must have the <tt>debugger.lua</tt> file in your Lua path.<br>
To begin the connection, you must execute this Lua code :
> local initconnection = require("debugger")
> initconnection(idehost, ideport, idekey,)
which can be shortened like this:
> require("debugger")(idehost, ideport, idekey)
*'''idehost''': the host name or the IP address of the DBGp server (thus, of your IDE).
**if <tt>idehost</tt> is <tt>nil</tt>, the <tt>DBGP_IDEHOST</tt> environment variable is used.
***if the environment variable is <tt>nil</tt>, the default value '127.0.0.1' is used.
*'''ideport''': the port of the DBGp server (must be configured in the IDE).
**if <tt>ideport</tt> is nil, the <tt>DBGP_IDEPORT</tt> environment variable is used.
***if the environment variable is <tt>nil</tt>, the default value '10000' is used.
*'''idekey''': a string which is used as session key (must be configured in the IDE).
**if <tt>idekey</tt> is <tt>nil</tt>, the <tt>DBGP_IDEKEY</tt> environment variable is used.
***if the environment variable is <tt>nil</tt>, the default value '<tt>luaidekey</tt>' is used.
Advanced optional parameters :
*<span id="transport_parameter">'''transport'''</span>: the name of the module which implements the transport interface used to communicate with the server.
** by default the debugger use an internal implementation based on luasocket, but if you cannot use it, you can implement or use another transport layer implementation.
** if <tt>transport</tt> is <tt>nil</tt>, the <tt>DBGP_TRANSPORT</tt> environment variable is used.
*** if the environment variable is <tt>nil</tt>, the default value '<tt>debugger.transport.luasocket</tt>' is used : this is the default implementation based on luasocket.
*'''platform''': 'unix' or 'win32' string which define the kind of platform on which the program to debug is executed.
** by default the debugger will try to guess it and often succeed. If for some reason it fails, you can help it by precising the execution platform.
** if <tt>platform</tt> is <tt>nil</tt>, the <tt>DBGP_PLATFORM</tt> environment variable is used.
*** if the environment variable is <tt>nil</tt>, the debugger will try to guess it.
*'''workingdir''': the working directory in which the program to debug is executed.
** by default the debugger will try to guess it and often succeed. If for some reason it fails, you can help it by precising the working directory.
** if <tt>workingdir</tt> is <tt>nil</tt>, the <tt>DBGP_WORKINGDIR</tt> environment variable is used.
*** if the environment variable is <tt>nil</tt>, the debugger will try to guess it.
So, to debug any Lua script, you can do:
lua -e "require('debugger')('idehost', 'ideport');" MyApp.lua
or even just go with:
lua -e "require('debugger')();" MyApp.lua
If you want to rely on default values for the debug host and port (which should be 127.0.0.1:10000 if you didn't tweak any <tt>DBGP_*</tt> environment variable).
[[Image:Idea.png|left]] '''Console output'''
::Some console output problems could happen because of buffer configuration. To force the stdout buffer to be flush at each call of print your should add this line:
::<tt>io.stdout:setvbuf("line");</tt> or <tt>io.stdout:setvbuf("no");</tt> see [http://www.lua.org/manual/5.1/manual.html#pdf-file:setvbuf Lua documentation]
::The full line should look like that:
::<tt>lua -e "io.stdout:setvbuf('line'); require('debugger')();" MyApp.lua</tt>
==== Setup DBGp Server ====
The DBGp Server is integrated in ''Koneki LDT''.<br> In order to accept incoming debug sessions, you must create a new '''Lua Attach to Application''' launch configuration, then launch it.
Go in '''Run/Debug Configurations...'''.
[[Image:LuaAttachToApplication0.9.png|center]]
*'''Project''': select the ''Koneki LDT'' project in your workspace which includes the Lua source file(s) of the application you want to debug.
*'''IdeKey''': default value is <tt>luaidekey</tt>, if you need to debug more than one application at the same time, you should change it to associate a launch configuration with only one application to debug.
*'''Source Mapping''': Define a common way for DBGp Server (IDE) and DBGp Client (running application) to identify source file. There are several strategy, each one is more or less adapted to a specific use case. For better understanding, read the [[#Source Mapping |advanced documentation]] about it.
Now you can start your debug session by clicking '''Debug'''. IDE will wait for an incoming connection from the debugger client, on the port you can see in the debug view. By default, the port used is 10000, but if it is taken, another one may be used.<br>
[[Image:LuaAttachToApplicationDebugView0.9.png|center]]
If needed, you can change the server port, in ''Window > Preferences > Dynamic Languages > Debug''.
[[Image:ConfigureDebuggerPort0.9.png|center]]
=== Remote session ===
As the remote debugging is an advanced feature and is not required by most Lua developers. The remote debugging is not shipped with
''Koneki LDT'' and have to be downloaded and installed afterwards.
To install the ''Koneki LDT'' remote feature, first select the top menu ''Help / Install New Software...''
[[Image:InstallSoftware.png|center]]
On the ''Koneki LDT'' update site select the remote feature in the list and install it. (see [http://wiki.eclipse.org/Koneki/updatesites Koneki update sites documentation])
[[Image:remoteFeature.png|center]]
In the Remote System Explorer perspective, in the new wizard, create a new ''Connection'' and select the ''Lua SSH System'' kind of system.
[[Image:createConnexion.png|center]]
On the next page, enter the network name of your remote system, or directly its IP address.
[[Image:createConnexionEnterIP.png|center]]
If needed, configure the runtime paths in ssh-lua sub-system advanced properties. If paths are not configured, the remote sytems's environment variables will be used. To change the properties, select the SSH Lua node of your connection. Then, in the property view bellow push the ''show advanced properties'' button. You can edit properties values by selecting the appropriate cell. If you let some properties empty, the remote system Lua defaults will be used.
[[Image:warning2.png|left]]'''User environment variable limitation:'''
::''Koneki LDT'' is not able to retrieve environement variables specified in the user scope. For exemple, if the variable LUA_PATH is modified in the .profile or .bashrc files of the remote user, on runtime theses modifications may not be taken into account.
[[Image:remoteConnection.png|center]]
In the top menu, select ''Run/Debug Configuration...''.
[[Image:DebugConfiguration.png|center]]
Then, create a ''Remote Lua Application'' launch configuration.
Configure the project and the script to run, also select the remote system.
[[Image:RemoteLaunchConf.png|center]]
The following tabs are also provided to configure your launch configuration:
*''Arguments'': you can here specify script and remote interpreter arguments, type the arguments as you would in command line. At the bottom of the tab, you can also edit the location where Lua files will be copied on the remote system, an absolute path is mandatory.
*''Environment'': Specify here some environement variables for runtime. Theses variables will be added to remote system's existing environement variables. As explained above, ''Koneki LDT'' is not able to retrieve environement variables values specfied in the user scope.
*''Common'': Some common launch configuration related settings.
**Save current launch configuration in a specified file.
**See current launch configuration displayed in favorite menu.
**Change the encoding of the launch configuration file.
**Allocates standard input/output in a console and/or redirects standard output in a file.
Launch the debug session, see how [[#Debugging_a_Lua_program|Debugging a Lua program]] to continue.
== Debugging a Lua program ==
See how to launch debug in previous section called ''[[#Configuring_debug_sessions|Configuring debug sessions]]''.
=== Breakpoints, code navigation ===
You can set breakpoints at a particular file or line, you can do it with the regular double-click on margin:
[[Image:Dbg-setbreakpoint.png|center]]
You can optionally indicate conditions to stop execution only under specific circumstances:
[[Image:Dbg-openproperties.png|center]]
[[Image:Dbg-properties.png|center]]
#Enables or disables breakpoint globally.
#Condition on hit count (stop only after the 3rd hit, every 4 hits, etc.).
#Conditional breakpoint: you can put any expression, it will be evaluated using the local scope every time the breakpoint is hit, and stop only when the expression evaluates to true.
Once a breakpoint has been hit, and the execution has actually stopped, you can use the '''Step Into''', '''Step Over''' and '''Step Return''' commands.
[[Image:Idea.png|left]]'''Coroutine handling:'''
::When the current instruction is a <tt>coroutine.yield</tt> or a <tt>coroutine.resume</tt> step over will jump over the coroutine until the next resume or yield whereas step into will go into the coroutine and re-break as soon as possible.}}
=== Environment inspection ===
When a breakpoint is reached, you can see any variable visible from any stack frame (local, upvalue and global variables). You can also edit values.
[[Image:Dbg-variables.png|center]]
[[Image:Idea.png|left]]'''New values are expressions:'''
::When you set a new value, it is evaluated as an expression, so <tt>math.sqrt</tt> will be evaluated to a function, if you want to put a literal string, use Lua syntax: <tt>"math.sqrt"</tt>. In particular you can change an entire table by another table expression. This is sometimes powerful and sometimes dangerous, '''be careful'''.
Some ''special'' values can also be displayed such as metatables or function environments (if it is different from global environment). You can also edit them.
=== Interactive console and expressions ===
In addition to variable view, you have two other useful tools to evaluate some code snippets: ''expressions view'' and ''interactive console''.
[[Image:Dbg-expressions.png|frame|center|The expressions view allows you to re-evaluate complex expressions at each step]]
[[Image:Dbg-repl.png|frame|center|The interactive console allows you to type statements under the local scope]]
[[Image:warning2.png|left]]'''Always on top level:'''
::Due to a limitation in the DBGp protocol, the interactive console and expressions are always mapped to the top stack frame.
=== Unsupported features ===
The '''dynamic code''' is not supported, it means that any code that is loaded with <tt>load</tt>, <tt>loadstring</tt> will not be supported. The debugger will step over it just like a C function.
== Improve cdata display ==
If you are working with LuaJIT's ''cdata'' and want to improve their display during debug, simply add this line at the top of your application entry point (by default ''main.lua''):
<source lang="lua">
require 'plugins.ffi'
</source>
We implemented a [[Koneki/LDT/User_Area/Debugger/ValueDisplay|custom inspector]] for ''cdata'' display, it will enable you to browse their structure and values.