LDT/User Area/User Guides/User Guide 0.9

Overview

The 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. 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 flavour. In order to do this, you have to create a Lua Project, it will add Lua nature to your code.

In "File > New > Project...", select the right project type: Lua Project.

Enter a valid name, choose your Execution Environment, press "Finish", and voila!

Note: You might want to configure an Execution Environment.

Edit some Lua

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.

Source folders are important, as they are the ones processed for tooling information. That is to say, if you write a module outside of a source folder, it will not be part of the accessible scope when you will try to reference it from another module or script ; thus, its content will not be available in e.g. code completion.

Run/Debug 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 add select Run As/Lua Application.

The Run As menu creates a default launch configuration for the selected file and launch it.

Concepts

Before diving into the concepts of LDT, if you need more information about the concepts of Lua itself, you are highly encouraged to refer to the Lua manual (http://www.lua.org/manual/5.1/).

Buildpath

It is a set of folder pathes which contains source and libraries enabling to run an application, there are several kind of them:

• Project path
• Runtime path

Project path

This path is used by Koneki LDT to find sources, it is composed of the content of all the sources folders of your project. Source folder pathes of your poject will be appended to $LUA_PATH before running your project.

So, you can require files from your source folder as modules. Lets say in a src/ source path you a foo.lua file, you can write:

   require 'foo'

This logic applies to sub directories, with a bar.lua in folder src/sub, you can use:

   require 'sub.bar'

Project path is also used for helping you writing code. Setting your project path accordingly will unleash the power of tooling with features such as code completion and code navigation.

(http://www.foo.org "Manage project paths")

Runtime path

This path describe the source and libraries available to your program at runtime. It is composed of (http://www.lua.org/manual/5.1/manual.html#pdf-LUA_PATH $LUA_PATH) and each source parth of your project.

(http://www.foo.org "Manage runtime path")

Execution Environment

An Execution Environment, which may also be referred to as EE, is a file containing information about the environment where a Lua application is supposed to run. An environment is a set of libraries available to the application out of the box, as in Lua 5.1 or Corona SDK.

The idea is to provide a file which describe elements of an environment. Provided information allows LDT to offer better code completion, code navigation and documentation layout.

Interpreters

In our case, an interpreter is a program which executes the instructions of your program. The most used in the Lua world might be (http://www.lua.org/manual/5.1/manual.html#6 "Lua standalone interpreter").

Debug

Debug is a common way to monitor how your program behave at runtime, step by step. You might be interested to do so when your application in not even running on your computer.

Local Debug

It is the typical case, you monitor a program running on your desktop.

(http://www.foo.org "Debug a local application")

Attach Debug

You want to monitor a an application running in a specific context, this application is not launched from Koneki LDT. There is a solution for you. Your application can connect to the IDE at startup and be monitored.

This way is called attached debug, uses DBGp and is composed of two parties.

(http://www.foo.org "Configure an attach debug session")

DBGp Client

In our case it is Koneki LDT waiting for an application to connect.

DBGp Server

In our case, it is the debugged application sending information about its run to Koneki LDT.

Remote Debug

Remote Debug enables to monitor an application running on a remote system, it rely on the same components as Attached Debug but automatize some configuration aspects.

Tasks

Configurig Build paths

In order to run propoperly your scripts, you must care about paths. In our case, there are several kind of them to consider:

• Project path, used by the IDE to perform tooling, can be also called source path
• Runtime path, used to run the script

Project path

Project path is the one set using the Build Path > Configure Build Path ... UI. From there you can specify dependency to other project from current workspace. As a result, will enjoy completion and navigation between your project and the ones configured in Build Path.

Runtime paths

The runtime paths are composed of the system variables LUA_PATH, LUA_CPATH, LD_LIBRARY and LUA binary path in the PATH variable. Theses paths can be set on the target computer where the lua script will run. Theses paths can also set by the launch configurations on the process or target where the script will run. The runtime path is dependent on witch kind of launch configuration you use. The configuration of theses paths is not detailed here since it is highly dependent on how you are managing paths in your own environment.

Managing Execution Environments

To find preferences related to EE, go to Window > Preferences > Lua > Execution Environments and you will have following interface.

From there, is it possible to add an EE to current workspace by pressing Add, then select an Execution Environment.

The EE is now available.

Link an existing project to an Execution Environment

Once you have manage to install Execution Environments in your workspace, it is time to use them in a project. Right click a project and select Build Path >> Add Libraries ....

You will have to choose between several libraries types, choose Lua Execution Environment.

You can now choose among installed EEs and press OK.

It is now linked to selected project.

Managing Interpreters

Interpreter are use by LDT to run scripts on the local computer.

Embedded Interpreters

An embedded interpreter is an interpreter deliver with LDT. You can reconize the interpreter preference page, the location is set as (embedded). Currently, LDT is deliver with the JNLua embedded interpreter, JNLua is Java implementation of Lua.

You can override an embedded interpreter by creating a new one with the same name.

Local Interperters

To run Lua scripts in LDT using the Lua Local Application launch configuration using a local installed Lua interpreters, you have to configure an interpreter. To configure an interpreter you just need the path of the interpreter executable, then you can set interpreter arguments and set some environment variables.

See below how to reference a Lua interpreter installed on your machine, and use it in LDT.

To open the Interpreters preference page go to Window > Preferences > Lua > Interpreters:

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. Currently it is the only type available,
• 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. lua),
• 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.

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.

Local session

Create a Lua Application launch configuration in the debug configuration menu.

In the Main tab, you can select the project and the script you want to launch.

In the Interpreter tab, you can select your own interpreter.

In the "Arguments" tab, you can specify interpreter arguments and script arguments. The interperter arguments will be merged to the ones specified at the interpreter level (in the interpreter preference page) at runtime.

Attach session

The Debugger of Lua Development Tools is based on the DBGp protocol, and the IDE implements a DBGp server.
To connect to this server, and begin remote/attach debugging, you need to use a DBGp Lua client. TODO verify links

DBGp Client

The DBGp Lua client is composed of two Lua files and can be downloaded here.
It runs on Unix-like OS and Windows (XP and later). It is written in Lua 5.1 and depends on lua-socket.
You can 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 these two files in your Lua path.
To begin the connection, you must execute this Lua code :

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

which can be shortened like this:

> require("debugger")(host, port, idekey)

• host: the host name or the IP address of the DBGp server (thus, of your IDE).
  • if host is nil, the DBGP_IDEHOST environment variable is used.
  • if the environment variable 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 environment variable is used.
  • if the environment variable 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 environment variable is used.
  • if the environment variable is nil, the default value 'luaidekey' is used.

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 DBGP_* environment variable).

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 io.stdout:setvbuf("line");

The full line should look like that :

lua -e "io.stdout:setvbuf('line'); require('debugger')();" MyApp.lua

DBGp Server

The DBGp Server is integrated in LDT.
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....

• Project : Set the LDT project in your workspace which includes the Lua source file(s) 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 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 more or less adapted to a specific used case. To better understand it, see the advanced documentation on 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.

If needed, you can change the server port, in Window > Preferences > Dynamic Languages > Debug.

Remote session

To perform remote debugging, you have to install the LDT remote feature. Select the top menu Help/Install New Software...

Enter the LDT update site url, it should be http://download.eclipse.org/koneki/releases/stable for the stable release, but nighly or millestone update site url can be used. Select the remote feature in the list and install it.

In the Remote System Explorer perspective, in the new wizard, create a new Connection and select the Lua Ssh System kind of system.

On the next page, enter the network name of your remote system, or directly the IP address.

If needed, configure runtime paths in ssh-lua sub-system advanced properties, if paths are not configured, the remote environement variables will be used. To change the properties, select the ssh lua node of you connection, then in the property view bellow push the show advanced properties button. You can edit properties values by slecting the appropriate cell. If you let some properties empty, the remote system lua default will be used. Warning, LDT is not able to retrieve environement variables specfied 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 modification will not be taken in account.

In the top menu, select Run/Debug Configuration....

Then, create a Remote Lua Application launch configuration. Configure the project and the script to run, select also the remote system.

Following tab are also provided to configure your launch configuration:

• Arguments: you can here specify script and remote interpreter arguments, type the argument as you do it in normal shell. At the bottom on the tab, you can also custom the location where file will be copied on the remote target, it's hightly recommanded to specify an absolute path.
• Environement: Specify here some environement variable for the runtime. If the variable already exist on the remote system, the specifed value in the launch configuration will be append to the existing variable. Warning, as explain above, 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 in favorite menu the launch conf is displayed.
  • Change the encoding of the launch configuration file.
  • Allocate sandard input/output in a console and/or redirect standard output in a file.

Launch the debug session, see how to [Debugging a Lua program] to continue.

Debugging a Lua program

Breakpoints, code navigation

You can set breakpoints at a particular file/line, you can do it with the regular double-click on margin:

You can optionally indicate conditions to stop execution only under specific circumstances:

1. Enable or disable breakpoint globally.
2. Condition on hit count (stop only after the 3rd hit, every 4 hits, etc.).
3. 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.

Coroutine handling
When the current instruction is a coroutine.yield or a coroutine.resume 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 change values to another.

New values are expressions
When you set a new value, it is evaluated as an expression, so math.sqrt will be evaluated to a function, if you want to put a literal string, use Lua syntax: "math.sqrt". In particular you can change an entire table by another table expression. This is sometimes powerful and sometimes dangerous, be careful with that.

Some special values can also be displayed such as metatables or function environments (if it is different from global environment). You can also change these values.

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.

The expressions view allows you to re-evaluate complex expressions at each step

The interactive console allows you to type statements under the local scope

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

Source Mapping

The DBGp Server (IDE) and the DBGp client (running application) need to communicate about source files.

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 example, in the case where your code is executed on a different host or just if your executed code is duplicated in another folder.

To resolve this problem, LDT proposes to you different strategies, each with advantages and drawbacks :

• Local Resolution

This way to resolve the source mapping is the more simple and the more reliable. Both client and server works with absolute path. The IDE will search only in its buildpath a file which have the given absolute path. This means that executed file should be in your workspace (in your buildpath more exactly). So you can not use it to debug code on a remote host.

• Module Resolution

Both IDE and application have their own way to retrieve a module from its name. So we could use the module name has file ID instead of path. With this mode, you could do remote debugging without setting a list of path mapping. The limitation is that you should use the standard lua_path way to load module. Another problem is that we could not really retrieve the module name at client side, because the Lua debug api uses source path. The module name is retrieved from the path (from debug.getinfo) and the lua_path (package.path), so with ambiguous lua_path you could have insolvable conflict.
E.g: with package.path = "/foo/bar/?.lua, /foo/?.lua" and debug.getinfo="@/foo/bar/baz.lua" the possible module name is bar.baz or baz
There are no way to know the real module name, in this case the debugger will use the shorter one, but the ideal is to avoid ambiguous lua_path with this mode.

• Replace path Resolution

This mode is a fallback. If the two previous one don't fit your needs, you could try it. In this mode, client talks with absolute path and server (IDE) uses relative path (relative to the buildpath). A path must be set in launchconfiguration to move from one world to another.

e.g: You set path with "/foo/bar/".
when file path is sent from client (/foo/bar/baz/qux.lua), path will be removed (baz/qux.lua) and a file with this relative path will be searched in your buildpath.
when file path is sent from server (baz/qux.lua), path will be add (/foo/bar/baz/qux.lua) and the absolute path will be sent to the client

The problem is that you could set only one path.
The path comparison is case sensitive (even on windows).
On windows, you should prefix your path with "/" (e.g. /C:/foo/bar/)

In all case, if file is not found in the workspace, the source code is sent via the DBGp protocol

Unsupported features

The dynamic code is not supported, it means that any code that is loaded with load, loadstring will not be supported. The debugger will step over it just like a C function.

The debugger is officially supported for Lua VM 5.1. Any other implementation (Lua 5.2, LuaJIT, ...) is not guaranteed to work at this time.