Concepts | ||
---|---|---|
![]() |
![]() |
|
Getting started | Tasks |
Before diving into concepts of 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.
It is a set of folder paths which contains sources and libraries accessible from your project. There are several kinds of them:
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 and .doclua files.
About runtime , source folders of current project and the ones of projects on which it depends will be appended to LUA_PATH at-once. At runtime, only .lua files are taken in account.
About tooling, all .lua and .doclua files 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
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.
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 and global variables available to the application out of the box, as in Lua 5.1 or MOAI SDK. Only one Execution Environment is expected per project.
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.
An Execution Environment can contains:
Manage Execution Environments
Get an Execution Environment
Create an Execution Environment
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 Lua standalone interpreter. It is possible to run Lua application using interpreters from 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 that you have luasocket installed and available from your interpreter.
Manage interpreters
Debug an application using interpreters
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.
This is the typical use case, you monitor a program running on your desktop. Your application will be executed by an interpreter referenced in LDT. 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
You want to monitor an application running in a specific context that makes it impossible to be launched by 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.
This way is more flexible, but you are on your own to manage the whole runtime configuration (LUA_PATH, debugger bootstrap, ...).
Configure an Attach Debug session
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, LDT comes with several policies, each of them having its own pros and cons:
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.
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:
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
In that case the debugger will use the shorter one. Ideally ambiguous LUA_PATH shall be avoided when this policy is chosen.
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.
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.
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:
In all cases, if a file is not found in the workspace, the source code is sent through the DBGp protocol
Configure an Attach Debug session
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.
LDT will copy all the files in the project buildpath in 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
![]() |
![]() |
![]() |
Getting started | Tasks |