Addons Introduction

An addon extends xmake itself. Where a package provides libraries for your program, an addon provides new abilities for the build tool: commands, build rules, toolchains, project templates and lua modules.

NOTE

Addons are supported since v3.1.1. Use v3.1.2 or later for fixes to local-repository paths and installed-version selection.

What an addon can carry

An addon ships one or more payloads, and every one of them is optional:

Payload	What it becomes	Used as
plugins/	a new xmake command	xmake monitor
rules/	a build rule	add_rules("@addon/esp32-devel/app")
toolchains/	a toolchain	set_toolchains("@addon/esp32-devel/esp32")
templates/	a project template	xmake create -t esp32.blink
modules/	importable lua modules	import("@addon.serial-tools.serial")
includes/	includable configuration	includes("@addon/esp32-devel/board")

So one addon can be a complete development kit: the esp32-devel addon carries the cross toolchain, the build rules, the flashing logic and a blink template — installing it turns xmake into an ESP32 SDK.

Same-name payload shorthand

Development builds allow omitting a payload name that matches the addon name. The full form remains supported:

Payload	Shorthand	Full form
Toolchain	@addon/xclang	@addon/xclang/xclang
Rule	@addon/demo	@addon/demo/demo
Include	@addon/demo	@addon/demo/demo
Module	@addon.demo	@addon.demo.demo

For example, select the xclang addon's same-name toolchain and bind its SDK package:

add_addons("xclang")
add_requires("xclang")

target("hello")
    set_kind("binary")
    set_toolchains("@addon/xclang", {packages = "xclang"})
    add_files("src/main.cpp")

Toolchain configurations such as @addon/xclang[sdkdir=/path/to/sdk] and package suffixes such as @addon/xclang@xclang still work. An omitted payload name always expands to the addon name. Use the full path to reference a differently named payload.

Architecture

                       xmake-repo                     github / local dir
                     addons/e/esp32-devel/xmake.lua   github:user/my-addon
                                    │
                     xmake addon --install <name>
                                    ↓
     ~/.xmake/addons/<name>/<version>/{plugins,rules,toolchains,templates,modules,includes}
     ~/.xmake/addons/addons.conf     ← the registry xmake reads on startup
                                    ↓
                    a project references the payloads it needs
             add_addons("esp32-devel")  +  @addon/esp32-devel/app

Three properties follow from this layout:

Installed once, per user. An addon lives in ~/.xmake/addons, not in the project. Several projects share the same installation, and the registry file means xmake does not scan the directory on every run.

Payloads are namespaced. Rules, toolchains, includes and modules are always referenced through @addon/<name>/..., so two addons never collide. Plugins and templates are the exception — a command name is global, so xmake rejects an install which would shadow another addon's command.

An addon names itself. The addon.lua manifest in the addon repository declares its name, description and payload root, so the name never depends on the repository or on the package that distributes it.

-- addon.lua
addon("esp32-devel")
    set_homepage("https://github.com/xmake-addons/esp32-devel")
    set_description("The ESP32 development addon.")
    set_license("Apache-2.0")
    set_sourcedir("src")
    add_deps("serial-tools")

Addons vs plugins vs packages

	Installed with	Lives in	Extends
Package	add_requires / xrepo install	~/.xmake/packages	your program (libs, headers, tools)
Plugin (legacy)	xmake plugin --install	~/.xmake/plugins	xmake, commands only
Addon	xmake addon --install / add_addons	~/.xmake/addons	xmake, all payload kinds

An addon is distributed as a package with set_kind("addon"), so it reuses the whole package infrastructure: repositories, versions, sha256 verification, dependencies and the xrepo download logic.

Next

• Installation and Usage — the xmake addon subcommands and add_addons
• Writing an Addon — the manifest, the payloads and publishing to xmake-repo
• xmake-harness — the AI agent addon, xmake ai