Developing

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

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.

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

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

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

     %USERPROFILE%\.vscode\extensions\sumneko.lua-VERSION\server

     ~/.vscode/extensions/sumneko.lua-VERSION/server

     ~/.vscode/extensions/sumneko.lua-VERSION/server
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 the above:

1. Install actboy168.lua-debug in Visual Studio Code.
2. Copy .vscode/launch.json into Debug Host at .vscode/launch.json
3. Copy the below settings into your settings.json for the Debug Target
   JSON

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

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

The server has supported multi-root workspaces since v2.6.0.

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. You can specify additional files to include using workspace.library.

When a Lua file is opened/created, the server will check all workspace scopes. If the file belongs to the working directory or a linked directory of the scope, it will be assigned to this scope. If all workspace scopes are not suitable, the file will be assigned to the <fallback> scope.

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

local state = {
    version = 'Lua 5.4',
    lua     = [[local x = 1]],
    ast     = { ... },
    errs    = { ... }, -- syntax errors
    comms   = { ... }, -- comments
    lines   = { ... }, -- map of offset and position
}

---@class myClass
local mt

vm.compileNode('mt')

-->

node: {
    [1] = {
        type = 'local',
        [1]  = 'mt',
    },
    [2] = {
        type = 'global',
        cate = 'type',
        name = 'myClass',
    },
}

---@type number|nil
local x

if x then
    print(x) --> `x` is number here
end

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

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