Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "LDT/User Area/User Guides/User Guide 0.9"
(→Remote session) |
(→Debugging a Lua program) |
||
Line 501: | Line 501: | ||
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. | 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. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
[[Image:Dbg-variables.png|center]] | [[Image:Dbg-variables.png|center]] |
Revision as of 10:23, 29 October 2012
Contents
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!
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, notice that completion is already available for Lua built in functions.
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.
The Run As menu creates a default launch configuration for the selected file and launch it.
Debug a Lua script
Simply define a breakpoint 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.
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 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 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.
About runtime , source folders of current project and the ones of projects on which it depends will be appended to LUA_PATH at-once.
About tooling, all elements from buildpath are parsed to unleash the power of tooling with features such as code completion, code navigation and TODO / Tasks.
You can require files from your source folders as modules. Lets say in a
src/
source path you have a foo.lua
file, you can
write:
require 'foo'
This logic applies to sub directories, with a bar.lua
file in
folder src/sub/
, you can use:
require 'sub.bar'
The init.lua
formalism is also handled. If you have an
init.lua
file under directory src/bar/
, 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.
Execution Environment
An Execution Environment, 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 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 APIs with Lua Documentation Language which provides:
- code assistance
- documentation
Manage Execution Environments
Get an Execution Environment
Create an Execution Environment
Interpreters
In our case, an interpreter is a program which executes instructions of your program. The most used in the Lua world might be 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 debug with you own interpreter, you have to ensure two things:
- Your interpreter has -e option.
- You have luasocket installed and available from your interpreter.
Manage interpreters
Debug an application using interpreters
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. Your application will be executed by an interpreter referenced in Koneki LDT. Koneki LDT will manage the LUA_PATH setting to allow the interpreter to access to all files in your buildpath.
Concepts Buildpath
Concepts Interpreters
Configure a Local Debug session
Attach Debug
You want to monitor a an application running in a specific context, this application can not be launched from Koneki LDT. There is a solution for you. Your application can connect to the IDE at startup and 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 all about runtime configuration (LUA_PATH, debugger bootstrap, ...).
Configure an Attach Debug session
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, Koneki 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 files 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 as 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 pathes. 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
Configure an Attach Debug session
Remote Debug
Remote Debug enables to monitor an application running on a remote system. This system must have the following installed:
- SFTP
- SSH
- Unix-like
Koneki LDT will copy all files in your buildpath on the remote directory of your choice (default is /tmp
), and will also manage the LUA_PATH setting allow the remote interpreter to access to those files.
Configure a Remote Debug session
Tasks
Configuring Build paths
See 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
Adding project dependencies
On the project o which you want to add a dependency, right click and selectBuild Path > Configure Build Path ....
Then select the Projects tab and use the Add button to create the dependency.
Managing Execution Environments
To find preferences related to Execution Environments, go to Window > Preferences > Lua > Execution Environments and you will have the following interface.
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 list of available Execution Environments or create your one Execution Environment. Then, back to the Execution Environments preference page, push Add button and select an Execution Environment file.
The Execution Environment is now available to use.
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 ....
You will have to choose between several libraries types, choose Lua Execution Environment.
You can now choose among installed Execution Environments and press Finish.
It is now linked to selected project.
Managing Interpreters
Interpreters are used by Koneki LDT to run scripts on local computers, see 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 support debug, the interpreter have to support -e option and have luasocket in the path.
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:
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.
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.
Configuring debug sessions
See the explanation about the three way to debug in Koneki LDT.
Local session
Create a Lua Application launch configuration in the Debug Configuration menu.
In the Main tab, you can select the project, the script you want to launch and a Lua interpreter.
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.
In the Environment tab, you can specify environment variables for runtime. Environment variable defined can be append
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.
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.
It runs on Unix-like OS and Windows (XP and later). It is written in Lua and depends on lua-socket.
You can get Lua at http://www.lua.org/download.html and install lua-socket thanks to luarocks, or via your official OS repositories.
If, for some reasons, you cannot use lua-socket, you could implement your own transport interface based on your own library (see the interface and the transport parameter)
To use it, you must have the debugger.lua file in your Lua path.
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 idehost is nil, the DBGP_IDEHOST environment variable is used.
- if the environment variable is nil, the default value '127.0.0.1' is used.
- if idehost is nil, the DBGP_IDEHOST environment variable is used.
- ideport: the port of the DBGp server (must be configured in the IDE).
- if ideport is nil, the DBGP_IDEPORT environment variable is used.
- if the environment variable is nil, the default value '10000' is used.
- if ideport is nil, the DBGP_IDEPORT environment variable 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.
- if idekey is nil, the DBGP_IDEKEY environment variable is used.
Advanced optional parameters :
- transport: 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 transport is nil, the DBGP_TRANSPORT environment variable is used.
- if the environment variable is nil, the default value 'debugger.transport.luasocket' 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 platform is nil, the DBGP_PLATFORM environment variable is used.
- if the environment variable is nil, 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 workingdir is nil, the DBGP_WORKINGDIR environment variable is used.
- if the environment variable is nil, 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 DBGP_* environment variable).
Setup DBGp Server
The DBGp Server is integrated in Koneki 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: 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 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 one is more or less adapted to a specific use case. For better understanding, read the 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.
If needed, you can change the server port, in Window > Preferences > Dynamic Languages > Debug.
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...
On the Koneki LDT update site select the remote feature in the list and install it. (see Koneki update sites documentation)
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 its IP address.
If needed, configure 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 default will be used.
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 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 in favorite menu the launch conf is displayed.
- 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 to continue.
Debugging a Lua program
See how to launch debug in previous section called Configuring debug sessions.
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:
- 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.
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.
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.
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.