跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

xmake-style

Use when writing or reviewing an `xmake.lua` (project, package recipe, or toolchain) and you want to follow idiomatic xmake style — description vs script domain separation, naming, indentation, `set_` vs `add_`, option/config organization, and common conventions used across xmake-repo and the xmake project itself. Apply this alongside `xmake-targets`/`xmake-packages`/etc. as a stylistic overlay.

xmake-io · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add xmake-io/xmake-skills --skill xmake-style

技能说明


name: xmake-style description: Use when writing or reviewing an xmake.lua (project, package recipe, or toolchain) and you want to follow idiomatic xmake style — description vs script domain separation, naming, indentation, set_ vs add_, option/config organization, and common conventions used across xmake-repo and the xmake project itself. Apply this alongside xmake-targets/xmake-packages/etc. as a stylistic overlay.

Xmake Configuration Style & Conventions

xmake.lua is Lua, but idiomatic xmake code looks less like Lua and more like a declarative configuration. Following the conventions below keeps files readable, fast to parse, and consistent with the style used throughout xmake and xmake-repo.

1. The description / script split (the single most important rule)

xmake.lua has two domains and they have very different rules.

Description domain — keep it declarative

This is the top-level body of target(), option(), package(), task(), rule(), and their set_xxx/add_xxx calls.

target("app")
    set_kind("binary")
    add_files("src/*.cpp")
    add_defines("DEBUG")
    add_syslinks("pthread")

Rules for the description domain:

  • Treat it as config, not code. Basic if is_plat(...) and for _, x in ipairs({...}) are fine; complex logic is not.
  • It is parsed multiple times. Every set_/add_ call may run more than once as xmake re-enters the file at different configuration stages. Never print() here (you will see it twice), and never do expensive work (I/O, git, network, shell).
  • Many APIs are forbidden or read-only here. os.getenv is read-only; most mutating os.* calls are blocked.
  • If logic is not a trivial if or for, move it to the script domain.

Script domain — put complex logic here

Anything inside on_load, on_config, before_build, after_build, on_install, on_test, etc., is the script domain. It runs once per lifecycle hook and has the full xmake Lua environment.

target("app")
    set_kind("binary")
    add_files("src/*.cpp")
    on_load(function (target)
        if is_plat("linux", "macosx") then
            target:add("links", "pthread", "m", "dl")
        end
    end)
    after_build(function (target)
        import("core.project.config")
        os.cp(target:targetfile(), path.join(config.buildir(), "dist"))
    end)

Use on_load for dynamic per-target configuration that would be ugly as nested if blocks at description level.

Extract long scripts to separate files

Once a hook body exceeds ~15 lines, move it out:

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

With files at modules/app/load.lua and modules/app/install.lua, each exporting a main function. Keeps the main xmake.lua scannable.

2. Indentation and layout

The conventions used throughout the xmake project itself:

-- 4 spaces, never tabs
add_rules("mode.debug", "mode.release")

-- blank line between top-level blocks
add_requires("fmt 10.x", "spdlog")

-- everything inside a target() is indented one level
target("mylib")
    set_kind("static")
    add_files("src/lib/*.cpp")
    add_includedirs("include", {public = true})
    add_packages("fmt")

target("app")
    set_kind("binary")
    add_files("src/app/*.cpp")
    add_deps("mylib")
  • 4 spaces per level. No tabs. The xmake CONTRIBUTING guide makes this explicit.
  • No explicit target_end() unless you have to. A new top-level call (target, option, package, rule, task) implicitly closes the previous one.
  • Blank line between blocks. Makes visual scanning easier when a file has many targets.
  • Related add_* calls stay grouped. Put add_files / add_headerfiles together; put add_includedirs / add_defines together; put add_packages / add_deps together.
  • Comments use --. Use -- for single-line comments. Avoid --[[ ]] blocks unless you are commenting out several lines temporarily.

Parentheses are optional for single-arg string calls

Both of these are valid:

target("test")
    set_kind("binary")
    add_files("src/*.c")
target "test"
    set_kind "binary"
    add_files "src/*.c"

Pick one and stick with it per file. The xmake and xmake-repo codebases predominantly use parentheses — match that style unless you have a reason.

3. Naming conventions

  • Target names: lowercase, - or _ for word separators. mylib, my-lib, my_lib. Match the produced binary name when it makes sense.
  • Options: same — lowercase with _. Prefix with enable_ / with_ / has_ to signal intent (enable_foo, with_openssl, has_avx2).
  • Rules: dotted namespaces for grouping (mycompany.codegen, mycompany.protobuf). Match how built-in rules are named (mode.debug, c++.unity_build, plugin.compile_commands.autoupdate).
  • Custom toolchains: short, lowercase, no prefix. myclang, arm-muslgcc.
  • Packages (in xmake-repo recipes): exactly the upstream name, lowercase, --separated. Match what add_requires users will type.

4. set_ vs add_: pick the right one

  • set_xxx — replaces. Use for single-valued properties: set_kind, set_version, set_languages, set_optimize, set_symbols, set_default, set_toolchains.
  • add_xxx — appends. Use for list-valued properties: add_files, add_includedirs, add_defines, add_links, add_deps, add_packages, add_cxflags.

If you call set_xxx twice for the same key, the second wins. If that is what you want, fine — but it is almost always a mistake.

-- ✗ wrong: second set_languages replaces the first
set_languages("c++17")
set_languages("c++20")

-- ✓ just set it once, at the level you want
set_languages("c++20")

5. Scope & visibility ({public = true})

Use {public = true} for **anything a depen

阅读完整来源 ↗