xmake-addon-development

Writing an Xmake Addon

An addon packages xmake extensions — commands, rules, toolchains, templates, modules — so that a user installs them with one command instead of copying files into ~/.xmake. For using one, see the xmake-addons skill.

Layout

my-addon/
├── addon.lua              # the manifest, the only required file
├── README.md
├── tests/test.lua         # not installed
└── src/                   # the payload root, @see set_sourcedir
    ├── plugins/hello/     # xmake hello           (a new command)
    ├── rules/app/         # add_rules("@addon/my-addon/app")
    ├── toolchains/mycc/   # set_toolchains("@addon/my-addon/mycc")
    ├── modules/           # import("@addon.my-addon.foo") / @self
    ├── includes/board/    # includes("@addon/my-addon/board")
    └── templates/c/foo/   # xmake create -t foo

Only the payload directories are installed, so tests, CI files and the README never land in the user's ~/.xmake/addons/<name>/<version>/. Ship only what you actually provide.

The manifest

-- addon.lua
addon("my-addon")
    set_homepage("https://github.com/me/my-addon")
    set_description("What this addon provides, one line.")
    set_license("Apache-2.0")
    set_sourcedir("src")            -- omit if the payloads sit at the repo root
    add_deps("serial-tools")        -- other addons this one needs

The addon names itself here, so its name never depends on the repository or the package that distributes it.

Reference your own payloads with @self

An addon must never hardcode its own name — it can always ask for itself:

-- in a rule, a toolchain or a plugin of this addon
import("@self.private.board")

-- when you need the name (e.g. to bind your own toolchain to a target)
import("core.package.addon")
local addonname = assert(addon.owner(), "not in an addon!")
target:set("toolchains", "@addon/" .. addonname .. "/mycc")

Ship package definitions

A toolchain addon usually needs binaries. Carry the package recipes and let the project consume them through an includes file: