Skip to content
Skills Library
Programming · Building & coding

xmake-addon-development

/xmake-addon-development

Use when writing an Xmake addon — the `addon.lua` manifest, the payload layout (plugins/rules/toolchains/modules/includes/templates), `@self` references, shipping package definitions with an addon, `add_globalmodules`, testing it locally, and publishing it to xmake-repo as an `addon` kind package.

Licence
Apache-2.0
Last repository change
24.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 24.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when writing an Xmake addon — the `addon.lua` manifest, the payload layout (plugins/rules/toolchains/modules/includes/templates), `@self` references, shipping package definitions with an addon, `add_globalmodules`, testing it locally, and publishing it to xmake-repo as an `addon` kind package.

Original author description

Use when writing an Xmake addon — the `addon.lua` manifest, the payload layout (plugins/rules/toolchains/modules/includes/templates), `@self` references, shipping package definitions with an addon, `add_globalmodules`, testing it locally, and publishing it to xmake-repo as an `addon` kind package.

How it works

  1. Layout
  2. The manifest
  3. Reference your own payloads with @self
  4. Ship package definitions
  5. Global modules
  6. Test it locally
  7. Publish to xmake-repo
  8. Gotchas
Original SKILL.md headings · 168 lines, 671 words
SKILL.md preview
---
name: xmake-addon-development
description: Use when writing an Xmake addon — the `addon.lua` manifest, the payload layout (plugins/rules/toolchains/modules/includes/templates), `@self` references, shipping package definitions with an addon, `add_globalmodules`, testing it locally, and publishing it to xmake-repo as an `addon` kind package.
---

# 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

```lua
-- 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:

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

```lua
-- 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:

```lua
-- src/includes/packages/xmake.lua
package("my-toolchain")
    set_kind("toolchain")
    add_urls("https://.../$(version).tar.gz")
    add_versions("1.0.0", "<sha256>")
    on_install(function (package)
        os.cp("*", package:installdir())
    end)
package_end()
```

```lua
-- src/includes/board/xmake.lua
includes("../packages")
option("board", {default = "uno", description = "Set the target board."})
set_defaultplat("cross")
add_requires("my-toolchain")
```

The project then only writes `includes("@addon/my-addon/board")`.

## Global modules

`add_globalmodules(...)` exposes a module under its plain name. Use it **only** for the
lookups xmake performs by a computed name:

```lua
addon("avr-devel")
    add_globalmodules("detect.tools.find_avrdude",  -- find_tool("avrdude")
                      "core.tools.avr_gcc")         -- the tool module of a compiler
```

```lua
-- src/modules/core/tools/avr_gcc.lua
inherit("core.tools.gcc")   -- avr-gcc is a gcc cross compiler
```

A global module that collides with a module of xmake or of another addon is rejected at
install time. Everything else stays namespaced (`@addon.<name>.<module>`).

::: tip
A finder also *names* the tool: shipping `detect.tools.find_avr_gcc` makes `find_toolname()`
resolve `avr-gcc` to `avr_gcc`, so the matching `core.tools.avr_gcc` module must exist too.
:::

## Test it locally

```bash
xmake addon --install .            # install from the working copy
xmake addon --list
xmake hello                        # exercise the payloads
xmake addon --remove my-addon
```

A `tests/test.lua` which installs, exercises and removes the addon is the standard shape —
it is exactly what a user does, and it runs unchanged in CI.

## Publish to xmake-repo

Addons live in `addons/<first-letter>/<name>/xmake.lua`, beside the C/C++ packages:

```lua
package("my-addon")
    set_kind("addon")
    set_homepage("https://github.com/me/my-addon")
    set_description("What this addon provides, one line.")
    set_license("Apache-2.0")

    add_urls("https://github.com/me/my-addon/archive/refs/tags/$(version).tar.gz",
             "https://github.com/me/my-addon.git")
    add_versions("v1.0.0", "<sha256>")

    add_deps("serial-tools", {kind = "addon"})

    on_test(function (package)
        assert(package:has_addon({rules = "app", toolchains = "mycc",
                                  plugins = "hello", templates = "c/foo"}))
    end)
```

Steps:

1. Tag a release in your addon repository.
2. Compute the sha256 of the tag archive: `xmake l hash.sha256 <file>` (or `shasum -a 256`).
3. Add the recipe, then test it the way the repo CI does:

```bash
xmake l scripts/test_addons.lua --addon my-addon
```

That installs it from your local xmake-repo checkout, runs `on_test`, and removes it again.

4. Send the pull request to [xmake-repo](https://github.com/xmake-io/xmake-repo).

`add_deps` is declared in both files on purpose: the recipe is what xmake reads *before*
downloading the sources, the manifest is what a local directory install reads. The repo test
script checks that the two agree.

## Gotchas

- Plugin task names and template ids are global — pick something unlikely to collide.
- Bump the version in the tag, not in `addon.lua`: the version comes from the package recipe.
- `set_sourcedir` is what keeps `tests/` out of the install; without it everything at the
  repo root that matches a payload name is installed.

Versions

The database has no other skills named xmake-addon-development.

Database snapshot: 13.11.2026 · package version 55328ce3fcb7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100xmake-addons
    Use when installing or using an Xmake addon — `xmake addon --install/--list/--remove/--upgrade/--search`, declaring `add_addons(...)` in a project, and referencing addon payloads with `@addon/<name>/<rule>`, `@addon.<name>.<module>` or `@self`. For writing and publishing one,…
  • 100xmake-repo-testing
    Use when adding or modifying a package recipe in the xmake-repo repository (github.com/xmake-io/xmake-repo) and you need to test-build it locally. Wraps the `xmake l scripts/test.lua` workflow with `--shallow`, platform/arch/mode/kind/configs flags so package changes can be…
  • 90gmod-addon-maker
    A tool for creating and managing Garry's Mod addons, including Lua scripting, content creation, and addon packaging. Use when: developing new addons, writing Lua scripts for GMod, organizing addon files, or when user mentions Garry's Mod, GMod, Lua scripting, or addon development.
  • 100write-addon
    Write, extend or fix a claude-ui addon: a folder with addon.json and sandboxed HTML views that adds a colour theme, a pane next to the chat, a band above the prompt box, a slash command `/<addon>:<cmd>` or a renderer for a code-fence language or a tool's result to the claude-ui…
  • 100blender-impl-addons
    Use when building a production Blender addon -- project structure, testing, CI/CD, or packaging for extensions.blender.org. Prevents the common mistake of hardcoding paths or skipping the extension manifest for Blender 4.2+. Covers multi-file addon structure, testing strategies,…
  • 98gmod-addon-structure
    Shows how a Garry's Mod addon folder is laid out (addon.json, lua/autorun, lua/entities, lua/weapons, materials, models, sound, maps, gamemodes), how to name files so they do not collide with other addons, how clients get custom content, and how to pack and publish to the Steam…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.