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(...)andfor _, 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. Neverprint()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.getenvis read-only; most mutatingos.*calls are blocked. - If logic is not a trivial
iforfor, 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. Putadd_files/add_headerfilestogether; putadd_includedirs/add_definestogether; putadd_packages/add_depstogether. - 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 withenable_/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-reporecipes): exactly the upstream name, lowercase,--separated. Match whatadd_requiresusers 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