xmake-custom-plugins

Authoring Custom Plugins & Tasks

A task is a named function reachable via xmake <taskname> on the CLI. A plugin is just a task packaged for reuse / distribution. Same API — the only difference is where the code lives.

This skill focuses on writing plugins. For using built-in plugins (xmake project -k compile_commands, etc.), see xmake-plugins.

1. Minimal task in xmake.lua

task("hello")
    set_menu {
        usage       = "xmake hello [options]",
        description = "Print a greeting",
        options     = {
            {"n", "name", "kv", "world", "Name to greet"},
            {nil, "loud", "k",  nil,     "Shout it"}
        }
    }
    on_run(function ()
        import("core.base.option")
        local name = option.get("name")
        if option.get("loud") then
            cprint("${bright red}HELLO, %s!", name:upper())
        else
            cprint("${green}hello, %s", name)
        end
    end)

xmake hello                  # hello, world
xmake hello --name=ruki      # hello, ruki
xmake hello -n ruki --loud   # HELLO, RUKI!
xmake hello --help           # menu auto-generated

2. set_menu schema

set_menu {
    usage       = "xmake <task> [options]",     -- one-line usage string
    description = "Short description",          -- listed in `xmake --help`
    options     = {
        -- { short, long, kind, default, description [, extra] }
        {"n", "name",    "kv", "world", "Name to greet"},
        {"v", "verbose", "k",  nil,     "Verbose output"},
        {nil, "files",   "vs", nil,     "Input files"},
        {},                                      -- separator in help output
        {nil, "mode",    "kv", "release", "Build mode",
                          {"debug", "release"}}, -- restricted values
    }
}

Option kinds: