xmake-scripting

Xmake Scripting, import, and Native Modules

xmake.lua is Lua, but "writing Lua" in xmake means working inside the script domain — hook bodies like on_load, on_build, after_build, on_install, on_run, on_test, or standalone modules loaded through import(). This skill covers how to write, organize, and load that code, including native (C/C++) Lua modules.

If you are looking for the description/script domain boundary and style rules, see xmake-style. This skill picks up once you are inside a script.

1. Where scripts live

Three idiomatic forms, from inline to fully external:

Inline (short logic)

target("app")
    set_kind("binary")
    add_files("src/*.cpp")
    after_build(function (target)
        os.cp(target:targetfile(), "$(buildir)/dist/")
    end)

Fine for anything under ~15 lines.

External file under modules/

target("app")
    on_load("modules.app.load")
    on_install("modules.app.install")

With a tree:

xmake.lua
modules/
  app/
    load.lua
    install.lua

Each external script file uses the module convention (see below) — no return, a main function is the entry point.

Standalone reusable module imported with import()

xmake.lua
scripts/
  codegen.lua
  utils.lua

-- inside some on_load / on_build
import("scripts.codegen")
codegen.generate(target)

2. The module convention

Xmake does not use Lua's native require / return pattern. Module files follow xmake's own convention:

-- scripts/foo.lua

-- private: prefixed with underscore, not exported
function _helper(x)
    return x * 2
end

-- public: any top-level function without leading underscore
function add(a, b)
    return _helper(a) + b
end

function greet(name)
    print("hello, %s!", name)
end

-- optional: `main` is the module's callable entry point
function main(a, b)
    return add(a, b)
end

Imported:

import("scripts.foo")

foo.add(1, 2)           -- public function
foo.greet("ruki")       -- public function
foo(1, 2)               -- calls main()
-- foo._helper(1)       -- ERROR: underscore-prefixed is private