Izrada proširenja temeljenih na Lua

Qt Creator se može proširiti Lua skriptama. Uključeni Lua motor temelji se na Lua 5.4.6.

Pisanje Lua ekstenzija

Za stvaranje nove Lua ekstenzije odaberite File > New Project > Library > Qt Creator Lua Plugin.

Za testiranje vaše nove ekstenzije pokrenite svoj projekt. Vaš Application Output trebao bi prikazati Hello from Lua!.

Lokacije dodataka

Lua ekstenzije mogu se nalaziti u bilo kojoj od uobičajenih lokacija dodataka za Qt Creator. Da biste saznali koje mape Qt Creator pretražuje u potrazi za dodacima, postavite varijablu okruženja QT_LOGGING_RULES na qtc.extensionsystem*=true. To omogućuje ispis za otklanjanje pogrešaka iz upravitelja dodataka, koji prikazuje putanje za pretraživanje dodataka kada se pokrene Qt Creator.

Za dodavanje putanja za pretraživanje upotrijebite argument -pluginpath na naredbenom retku pri pokretanju Qt Creator.

Specifikacija Lua ekstenzije

Lua ekstenzija se sastoji od Lua skripte s istim imenom kao i mapa u kojoj se nalazi. To je potrebno da bi se ekstenzija učitala.

Ovaj skript definira specifikaciju ekstenzije, kao što su njezino prikazano ime, proizvođač i autorska prava.

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

Postavna funkcija

Funkcija postavljanja se poziva kada se ekstenzija učita. Ovdje možete postaviti funkcionalnost svoje ekstenzije. Budući da se specifikacijska datoteka parsira s vrlo ograničenim dozvolama, potrebno je zahtijevati modul u kojem implementirate stvarnu funkcionalnost.

--- 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
}

Asinkrone operacije

Neke ugrađene operacije rade asinkrono. Za to koristite modul Async.

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)

Interaktivna pomoć

Kada prvi put otvorite .lua datoteku u uređivaču, od vas se traži da preuzmete Lua Language Server. To je izuzetno korisno jer vam pruža pomoć osjetljivu na kontekst i automatsko dovršavanje.

Qt Creator Lua API

Qt Creator ov Lua API dostupan je Lua ekstenzijama putem niza modula koje možete uvesti pomoću funkcije require. C++ ekstenzije mogu pružiti dodatne module. Jedan primjer toga je LanguageServer Extension koji pruža modul za stvaranje klijenata Language Servera.

Datoteke API dokumentacije za Lua module možete pronaći u svojoj instalaciji Qt Creator. Na macOS-u ih možete pronaći u Qt Creator.app/Contents/Resources/lua/meta.

Proširivanje Lua API-ja pomoću C++-a

Da biste dodali funkcionalnost Lua sučelju, morate registrirati novi modul kod Lua motora.

#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::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;
        });
     }
};

Zatim možete pristupiti MyCppExtension.myFunction iz svojih Lua skripti na sljedeći način:

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

Za više informacija o tome kako registrirati C++ funkcionalnost, pogledajte sol2.

Primjeri

Language Server

Plugin Qt Creator LuaLanguageClient pruža podršku za registraciju vlastitih klijenata Language Servera. Primjer upotrebe možete pronaći u ekstenzijama "Lua Language Server" i "Rust Language Server" za Qt Creator.