Extending Qt Creator with Lua

Qt Creator can be extended with Lua scripts. The included Lua engine is based on Lua 5.4.6.

Writing Lua Extensions

To create a new Lua extension, choose File > New Project > Library > Qt Creator Lua Plugin.

To test your new extension, start your project. Your Application Output should show Hello from Lua!.

Lua Extension Specification

A Lua extension consists of a Lua script with the same name as the folder it is in. This is necessary for the extension to be loaded.

This script defines the specification of the extension, such as its display name, vendor, copyright.

--- MyExtension.lua
return {
    Name = "MyExtension",
    Version = "1.0.0",
    CompatVersion = "1.0.0",
    Vendor = "My Company",
    Category = "Tests",
    Description = "Describe what your extension does in a sentence.",
    LongDescription = [[
        Tell users more about your extension.
    ]],
    Dependencies = {
        { Name = "Core", Version = "13.0.82", Required = true },
        { Name = "Lua",  Version = "13.0.82", Required = true }
    },
    setup = function() print("Hello from Lua!") end,
    printToOutputPane = true,
} --[[@as QtcPlugin]]

The Setup Function

The setup function is called when the extension is loaded. This is where you can set up the functionality of your extension. Since the specification file is parsed with very limited permissions, you need to require a module where you implement the actual functionality.

--- MyExtension.lua
return {
    Name = "MyExtension",
    Version = "1.0.0",
    ...,
    --- This is the setup function that is called when the extension is loaded.
    --- It requires the 'init' module and calls the setup function from the returned table.
    setup = function() require 'init'.setup() end,
}

--- init.lua
function setup()
    print("Hello from Lua!")
end

-- Returns a table with a single field 'setup' that points to the setup function.
return {
    setup = setup
}

Asynchronous Operations

Some of the built-in operations work asynchronously. To handle this, use the Async module.

local a = require 'async'
local u = require 'Utils'

a.sync(function()
    print("Lets wait for 5 seconds ...")
    a.wait(u.waitms(5000))
    print("... done!")
end)

Interactive Help

When you open a .lua file in the editor the first time, you are asked to download the Lua Language Server. This is extremely useful as it gives you context sensitive help and auto-completion.

Qt Creator API

The Qt Creator API is available to Lua extensions via a number of modules that you can import using the require function. C++ extensions may provide additional modules. One example of that is the LanguageServer Extension that provides a module for creating Language Server clients.

You can find the API documentation files for the Lua modules in your Qt Creator installation. On macOS you can find them in Qt Creator.app/Contents/Resources/lua/meta.

Core.lua	Access and interact with the core functionality of Qt Creator.
action.lua	Create user interface actions in Qt Creator.
async.lua	Handle asynchronouse operations with the async/await Lua API.
fetch.lua	Fetch data from the internet.
gui.lua	Create user interfaces.
lsp.lua	Register Language Server clients.
messagemanager.lua	Display messages to the user.
process.lua	Run external processes.
qt.lua	Access Qt functionality.
qtc.lua	Access and extend Qt Creator.
settings.lua	Read and write settings.
simpletypes.lua	Access simple types.
utils.lua	Common utility functions and classes.

Extending the Lua API with C++

To add functionality to the Lua Interface, you need to register a new module with the Lua Engine.

#include <lua/luaengine.h>

class MyCppExtension final : public ExtensionSystem::IPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "MyCppExtension.json")

public:
    MyCppExtension() {}

private:
    void initialize() final {
        // The registered function will be called when the Lua module 'MyCppExtension' is required.
        // The returned table will be returned from the require call in Lua.
        ::Lua::LuaEngine::registerProvider("MyCppExtension", [](sol::state_view lua) -> sol::object {
            sol::table result = lua.create_table();
            result["myFunction"] = [](int a, int b) { return a + b; };
            return result;
        });
     }
};

You can then access MyCppExtension.myFunction from your Lua scripts like this:

local MyCppExtension = require 'MyCppExtension'
--- MyCppExtension is now a table with a single field 'myFunction', as it is returned from the
--- C++ function registered via 'LuaEngine::registerProvider(...)'.
print(MyCppExtension.myFunction(1, 2))

For more information on how to register C++ functionality, see sol2.

Examples

Language Server

The Qt Creator LuaLanguageClient Plugin provides support for registering your own Language Server clients. You can find an example of how to use this in the Qt Creator Extension "Lua Language Server" and "Rust Language Server".

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.