LuaLS / LuaLS/lua-language-server

Add documentation for the plugin environment

Open
#2,092 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation feat/plugin
Dominant language
Lua
Stars
4.4k
Forks
442
PR merge metrics
No merged PRs in 30d

Description

Plugins have a surprisingly large amount of flexibility when the surrounding environment is considered. Unfortunately, most of the environment is undocumented, which means there's a good chance plugin developers don't know how much their plugin can really do.

Currently, printing out `package.path` and `package.cpath` gives these directories

`package.path`
```sh
# directories provided by the extension
$LSP/script/?.lua
$LSP/script/?/init.lua

# access to the plugin's directory
$PLUGIN/?.lua
```

`package.cpath`
```sh
$LSP/bin/?.dll
```

where:

* `$LSP` is the path to this project's folder, and
* `$PLUGIN` is a path to the plugin's current directory. `~/project/config/plugin.lua` would make `$PLUGIN` point to `~/project/config`

Along with giving plugins the ability to have sub-modules, the LSP has some very useful utilities in its `script` folder like:

* `vm` for inspecting types (or so it seems)
* `parser.compile` for getting an AST
* `inspect` which looks like [kikito/inspect.lua](https://github.com/kikito/inspect.lua)
* `config` for reading LSP settings like `Lua.runtime.version`

> I don't work with Visual Studio enough to understand the DLLs in `$LSP/bin`, or at least not enough to work with them in Lua.

`...` has some useful information too.

```lua
local inspect = require("inspect")

print(inspect({ ... }))
--[[-->
{
, -- this plugin loaded as a chunk using `load()`
"file:///$WORKSPACE_FOLDER", -- a URI pointing to the workspace folder
{} -- arguments provided by the setting `Lua.runtime.pluginArgs`
}
]]
```

I think this information is useful enough to be documented in the wiki. I can contribute to it if need be.

It would be even more useful and accessible if there was a meta-addon that adds the `$LSP/script` directory to `Lua.workspace.library` or a boolean option that adds the directory internally. I can try to contribute to that as well.

I understand that `$LSP/script` may be updated often for bugfixes and other things. If this is the case, I think it would at least be useful to provide a directory for plugin utilities.

> I'm not sure about what to do when the VS Code extension gets updated since it changes directory. Maybe, more generally, the LSP can warn you about missing libraries.

> Also, if `$LSP/script` updates too frequently to be mentioned in the wiki, I think the meta-addon route would be more fruitful.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the plugin environment details in the issue, including package.path, package.cpath, the $LSP/script utilities, and the plugin arguments passed through .... Confirm which behavior is stable enough to document in the wiki, then make the environment and available utilities clear to plugin authors without relying on speculative DLL or meta-addon changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.