1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
# Lua Plugin
## Introduction
The Lua plugin provides support for writing plugins using the Lua scripting language.
## Usage
The plugin scans the folder `lua-plugins` folder inside the normal plugin folder of Qt Creator
`ExtensionSystem::PluginManager::pluginPaths()`. It loads scripts from any folder that contains
a .lua script named the same as the folder.
Whether or not the script is enabled is determined by the `disabledByDefault` field in the plugin
table and the settings configured via the "About Plugins" dialog in Qt Creator.
## Basic Lua plugin
A Lua script needs to provide the following table to be considered a plugin:
```lua
-- lua-plugins/myluaplugin/myluaplugin.lua
return {
name = "MyLuaPlugin",
version = "1.0.0",
compatVersion = "1.0.0",
vendor = "The Qt Company",
category = "Language Client",
setup = function() print("Hello World!") end,
--- The following fields are optional
description = "My first lua plugin",
longDescription = [[
A long description.
Can contain newlines.
]],
url = "https://www.qt.io",
license = "MIT",
revision = "rev1",
copyright = "2024",
experimental = true,
disabledByDefault = false,
dependencies = {
{ name="Core", version = "12.0.0" }
},
} --[[@as QtcPlugin]]
```
Your base file needs to be named the same as the folder its contained in.
It must only return the plugin specification table and not execute or require any other code.
Use `require` to load other files from within the setup function.
```lua
-- lua-plugins/myluaplugin/myluaplugin.lua
return {
-- ... required fields omitted ..
setup = function() require 'init'.setup() end,
} --[[@as QtcPlugin]]
-- lua-plugins/myluaplugin/init.lua
local function setup()
print("Hello from Lua!")
end
return {
setup = setup,
}
```
The `require` function will search for files as such:
```
my-lua-plugin/?.lua
```
## Lua <=> C++ bindings
The Lua plugin provides the [sol2](https://github.com/ThePhD/sol2) library to bind C++ code to Lua.
sol2 is well [documented here](https://sol2.rtfd.io).
## Lua Language Server
To make developing plugins easier, we provide a meta file [qtc.lua](meta/qtc.lua) that describes
what functions and classes are available in the Lua plugin. If you add bindings yourself
please add them to this file. The [.luarc.json](../../.luarc.json) file contains the configuration
for the [Lua Language Server](https://luals.github.io/) and will automatically load the `qtc.lua` file.
## Coroutines
A lot of Qt Creator functions will take some time to complete. To not block the main thread during
that time, we make heavy use of lua coroutines. Functions that need a coroutine to work are documented
as such, lets take for example `qtc.waitms(ms)`. This function will wait for `ms` milliseconds and
then return. To use it you need to call it using the async module from a running coroutine:
```lua
local a = require 'async'
local function myFunction()
a.wait(qtc.waitms(1000))
print("Hello from Lua!")
end
local function setup()
a.sync(myFunction)()
end
```
The waitms function will immediately yield, which will suspend the execution of `myFunction` **AND**
make the `a.sync(myFunction)()` return.
Once the internal timer is triggered, the C++ code will resume `myFunction` and it will continue to
print the message. `myFunction` will then return and the coroutine will be "dead", meaning it cannot
be resumed again. You can of course create a new coroutine and call `myFunction` again.
## Contributing
Contributions to the Lua plugin are welcome. Please read the contributing guide for more information.
|
