# Concepts

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.

## 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 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.

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 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:

- Description for globals and modules APIs with Lua Documentation Language which provides:
  - code assistance
  - documentation
- template files: Template of typical entry point for an application aiming this execution environment. Will be used to initialize new Lua projects.
- documentation: Environment documentation as HTML pages.

Manage Execution Environments
Get an Execution Environment
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 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

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 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

### Attach Debug

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.

- DBGp Server: In our case it is 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 LDT.

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

#### 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, 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 `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.

- 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.
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:

- 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

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.

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