Developing

⚠️ Warning

This wiki has been replaced by the wiki on our website. This wiki will be removed in the future.

Developing

Hello! Thank you for taking an interest in helping improve the language server.

You can explore the file structure page for info on what files are doing what.

Enable Developer Mode

In Visual Studio Code, add --develop=true to Lua.misc.parameters.

In other clients, use --develop=true as a flag from the command line.

Debugging

Debugging can be performed in a few ways. You can do a quick print(), write to the log file, or attach a debugger to get all the info you need.

Quick Print

You can quickly print() to the OUTPUT panel (Ctrl + Shift + U) in Visual Studio Code.

Below is an example of how a plugin can be debugged.

local util   = require 'utility'
local client = require 'client'

function OnSetText(uri, text)
    print(uri, #text, util.dump(client.info.clientInfo))
end

Append to Log File

You can add an entry to the log file. Below is an example of how a plugin can be debugged.

local util   = require 'utility'
local client = require 'client'

function OnSetText(uri, text)
    log.debug(uri, #text, util.dump(client.info.clientInfo))
end

Attach Debugger

This is the most advanced method, but provides all kinds of useful info and is the most "proper" way to debug the language server.

You will need two Visual Studio Code instances open:

1. The Debug Host
   • This instance has the language server open which can be found in one of these locations:
     • Windows: %USERPROFILE%\.vscode\extensions
     • Linux: ~/.vscode/extensions
     • MacOS: ~/.vscode/extensions
2. The Debug Target
   • This instance is where you will test the language server. It should have a folder opened where you can write Lua to test the various features of the language server and use it as normal.

The below steps guide you through setting up Lua debugging:

1. Install actboy168.lua-debug from the extension marketplace for Lua debugging
2. Copy .vscode/launch.json into Debug Host
3. Copy the below settings into your settings.json for the Debug Target

   "Lua.misc.parameters": [
    "--develop=true",
    "--dbgport=11428"
   ],

4. Restart the Debug Target (F1 -> Reload Window)
5. Open the Run and Debug sidepanel (Ctrl + Shift + D) and select 🍄 attach
6. Press F5 to begin debugging

ℹ️ Note: If you got the server through git you will need to change the debug port in settings.json to "--dbgport=XXXXX" and address to "address": "127.0.0.1:XXXXX" in launch.json.

Multiple Workspace Support

The server has supported multi-workspace environments since v2.6.0. This works when the client starts up one instance of the language server and then sends all Lua files to it (even if they are not included in the current workspaces).

ℹ️ Note: The server does not support dynamically adding or removing workspaces. If the workspaces change, the client should restart the server. The server has supported dynamically adding or removing workspaces since v3.5.1.

The server creates a <fallback> scope by default. If you start the server while in "single file mode", this <fallback> scope is what is being used.

Should the server be started in "workspace mode", each workspace will be given its own scope.

Linking to other files/directories outside the scope of your workspace(s) is also possible. Built-in Lua libraries are linked using the API definition files from meta/ that correspond to the runtime.version you have selected. You can also specify additional files to include using workspace.library.

When a Lua file opened/created, the server will check all workspace scopes:

• If the file belongs to the working directory or linked directory of the scope, it will be assigned to this scope
• If all workspace scopes are not compliant, the file will be assigned to the <fallback> scope.

Every scope has an independent environment for separating global variables, classes, settings, requires, etc.

Theming

Here you can find the names of the various tokens in Visual Studio Code to highlight and colour the various semantic items of Lua.

Syntax Tokens

These tokens are being previewed in Dark+ of Visual Studio Code as it has great support for the various tokens used by the extension.

token	preview
keyword.local.lua
keyword.control.lua
entity.name.class.lua
entity.name.function.lua
punctuation.definition.parameters.begin.lua
punctuation.definition.parameters.finish.lua
variable.parameter.function.lua
punctuation.separator.arguments.lua
constant.numeric.integer.lua
constant.numeric.float.lua
constant.numeric.integer.hexadecimal.lua
constant.numeric.float.hexadecimal.lua
punctuation.definition.string.begin.lua
punctuation.definition.string.end.lua
string.quoted.single.lua
string.quoted.double.lua
string.quoted.other.multiline.lua
constant.character.escape.lua
constant.character.escape.byte.lua
constant.character.escape.unicode.lua
invalid.illegal.character.escape.lua
punctuation.definition.comment.lua
comment.line.double-dash.lua
punctuation.definition.comment.begin.lua
punctuation.definition.comment.end.lua
comment.block.lua
keyword.control.goto.lua
string.tag.lua
punctuation.section.embedded.begin.lua
punctuation.section.embedded.end.lua
variable.language.self.lua
support.function.lua
support.function.library.lua
keyword.operator.lua
variable.other.lua

Semantic Tokens

semantic token	fallen syntax token	preview
namespace.static	support.function.lua
namespace.readonly	constant.language.lua
namespace.deprecated	entity.name.label
parameter.declaration	variable.parameter
property.declaration	entity.other.attribute
variable	variable.other.lua
interface.declaration	entity.name.function.lua