agentsclimarketplace

Xmake troubleshooting

Skill xmake-io/xmake-skills/skills/ops/xmake-troubleshooting

Use when xmake is misbehaving — hangs/stuck, mysterious errors, slow configure/build, regressions after upgrade — and you need to diagnose it. Covers `-vD` verbose traces, `XMAKE_PROFILE=stuck/trace/perf:*` profiling env var, git bisect via `xmake l cli.bisect`, and debugging the Lua + C core. Do NOT use for everyday build errors — use the relevant per-topic skill first.From its SKILL.md

Install
npx -y skills add xmake-io/xmake-skills --skill xmake-troubleshooting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

9.6 KB, as published. Nobody here has run it

Troubleshooting Xmake

When xmake itself (not your project) is misbehaving, work from the cheapest tool to the most invasive: verbose output → profiling env → bisect → debugger.

1. First: verbose and diagnosis output

xmake -v               # verbose: show every sub-command
xmake -vD              # verbose + diagnosis: full Lua tracebacks on error
xmake f -vD            # same but for configure
xmake l -vD path/to/script.lua

-D is the single most important flag when something goes wrong — any Lua error comes back with a full stack into xmake/core/..., which usually tells you exactly which module is unhappy.

Project cache can also mask bugs. If something seems sticky:

xmake f -c             # re-run configure, dropping cached state
xmake clean --all
rm -rf .xmake          # nuclear: drop the whole local cache

2. Stuck / hang diagnosis (XMAKE_PROFILE=stuck)

Xmake has a built-in stuck-process debugger. Set XMAKE_PROFILE=stuck and it will (a) log every subprocess it spawns and (b) on Ctrl+C print the current Lua stack traceback — so you can see exactly where it was blocked.

Enable it

Linux / macOS:

XMAKE_PROFILE=stuck xmake              # one-shot
export XMAKE_PROFILE=stuck && xmake    # whole session

Windows PowerShell:

$env:XMAKE_PROFILE="stuck"; xmake

Windows CMD:

set XMAKE_PROFILE=stuck && xmake

Reading the output

Subprocess trace (configure stuck probing a compiler):

$ XMAKE_PROFILE=stuck xmake f -c
<subprocess: sysctl>: /usr/sbin/sysctl -n machdep.cpu.vendor ...
checking for platform ... macosx
<subprocess: which>: which "xcrun -sdk macosx clang"
^C[xmake]: [engine]: stack traceback:
        @programdir/core/base/scheduler.lua:429: in function 'base/scheduler.co_suspend'
        .../lib/detect/find_program.lua:266: in function ...
        @programdir/modules/detect/tools/find_clang.lua:44: ...

This tells you:

  • Which subprocess was running when it hung (which "xcrun -sdk macosx clang" here).
  • The Lua call stack that led there — e.g. find_clang → find_program → scheduler.co_suspend, so xmake was waiting on a spawned process that never returned.

Typical root causes this surfaces:

  • A compiler probe running against a broken/hung binary (e.g. a corrupt clang, a misconfigured wrapper).
  • A package download from a slow/unreachable URL.
  • A lock held by another xmake process (check with ps/Task Manager).

Report the trace verbatim when filing issues — it is far more useful than "xmake is stuck".

3. Performance / profiling

Same env var, different values. All enable per-phase timing and print a report at the end of the run.

XMAKE_PROFILE=...What it measures
stuckSubprocess trace + Ctrl+C backtrace (see above)
traceTrace every sub-command xmake runs
perf:callPer-Lua-function call count and total time
perf:tagTime spent in named profiler tags (e.g. compile, link)
perf:processTime spent in spawned subprocesses

Examples:

XMAKE_PROFILE=perf:call    xmake                # hot Lua functions
XMAKE_PROFILE=perf:tag     xmake                # compile/link phase timing
XMAKE_PROFILE=perf:process xmake -j1            # which child processes dominate
XMAKE_PROFILE=trace        xmake f -c           # log everything configure does

Typical performance findings

  • xmake f -c is slow → perf:process usually shows tool-detection probes dominating. Look for custom on_check / find_* modules that re-probe on every configure.
  • Incremental builds are slow → perf:tag shows whether time is in compile, link, or elsewhere (dep-scan, codegen rules).
  • xmake.lua parsing is slow → perf:call reveals expensive work done in the description phase. Move it to on_load / on_config.

Also useful:

xmake -j N              # parallel jobs
xmake build --jobs=N
xmake build --verbose   # show actual compile invocations

4. Bisecting a regression (xmake l cli.bisect)

When a feature stopped working between two xmake versions (or two commits of your xmake.lua), use xmake's built-in bisect wrapper. It runs git bisect under the hood and runs your test command at each step.

Basic form

xmake l cli.bisect \
  -g <good>                        \
  -b <bad>                         \
  --gitdir=<path-to-xmake-checkout> \
  -c "<test command>"
  • -g, --good — known-good tag or commit
  • -b, --bad — known-bad tag or commit
  • --gitdir= — path to the xmake source checkout to bisect
  • -c, --commands — shell commands to run at each step; multiple commands separated by ;. Non-zero exit → bad commit.
  • -s, --script — Lua script instead of -c
  • -- — everything after is a raw command to execute

Example: regression between v2.9.1 and v2.9.2

xmake l cli.bisect \
  -g v2.9.1 -b v2.9.2 \
  --gitdir=/path/to/xmake \
  -c "xrepo remove --all -y; xmake f -a arm64 -cvD -y"

Output on completion:

aa278bc7fc0b723a315120bb95531991b7939229 is the first bad commit
    improve to system/find_package
    xmake/modules/package/manager/system/find_package.lua | 16 +++++++++++++---

You now have the exact commit, author, and diff — paste into the bug report.

Using a Lua test script (for non-trivial checks)

xmake l cli.bisect -s /tmp/test.lua -g v2.9.1 -b v2.9.2 --gitdir=/path/to/xmake
-- /tmp/test.lua
function main()
    os.exec("xrepo remove --all -y")
    os.exec("xmake f -a arm64 -cvD -y")
    os.exec("xmake build")
    -- for custom checks, use raise() to mark the commit as bad
    local output = os.iorun("xmake run hello")
    if not output:find("expected output") then
        raise("test output mismatch")
    end
end

Semantics: os.exec failures automatically mark the commit bad. Use raise(...) for custom assertions (output matching, file existence, …).

Raw-command form

xmake l cli.bisect -g 90846dd -b ddb86e4 --gitdir=/path/to/xmake -- xmake -rv

Everything after -- is executed verbatim. Good for one-liners.

Tips

  • Keep each test step fast (seconds, not minutes). Bisect runs it log2(N) times.
  • Start from a clean state in the test command (xrepo remove --all -y; xmake f -c) so cached state from a previous step does not contaminate the next.
  • Use a minimal reproduction project, not your real repo. Huge projects make every bisect step slow.
  • If the good/bad ends are across a tbox submodule bump, run git submodule update --init --recursive inside the test script.

5. Debugging xmake source itself

If bisect points at a specific change and you want to dig in further, switch to source-level debugging. The full flow (build from source, srcenv.profile, editing Lua live, GDB/LLDB on the C core) has its own skill — see xmake-dev. A one-paragraph summary:

cd xmake && ./configure && make -j
source scripts/srcenv.profile
xmake l xmake.programdir          # verify you are running the local tree
xmake -vD                         # reproduce the issue; errors now point into your checkout

From there, edit xmake/... Lua files directly (no rebuild needed) and drop print/utils.vprint/cprint where the traceback points.

For native-side issues (core/src/xmake/*.c), ./configure --mode=debug && make -j, then gdb --args core/build/xmake ... — see xmake-dev.

EmmyLua debugger (step-through for Lua)

For interactive step-through of the Lua layer inside VS Code:

xrepo env -b emmylua_debugger -- xmake build

Then in VS Code (with the EmmyLua extension), open the xmake Lua source, go to Run and Debug → Emmylua New Debug to attach. The first breakpoint hits inside debugger:_start_emmylua_debugger; step out to land in main.lua. Swap xmake build for any other subcommand to debug it.

6. Filing a useful bug report

When escalating to maintainers, include:

  1. Xmake version: xmake --version
  2. Platform and host: xmake l 'print(os.host(), os.arch(), os.subhost())'
  3. Minimal xmake.lua that reproduces the issue
  4. Full -vD output (or at least the traceback)
  5. If hang → XMAKE_PROFILE=stuck subprocess trace + Ctrl+C backtrace
  6. If regression → the commit from xmake l cli.bisect
  7. What you already tried (xmake f -c, xmake clean --all, deleting .xmake/)

Diagnostic decision tree

Something is wrong with xmake
│
├── It just errors
│     └─ xmake -vD → read the Lua traceback
│
├── It hangs
│     └─ XMAKE_PROFILE=stuck xmake ... → Ctrl+C → read trace
│
├── It's slow
│     ├─ XMAKE_PROFILE=perf:process  → which subprocesses dominate?
│     ├─ XMAKE_PROFILE=perf:tag      → compile vs link vs other?
│     └─ XMAKE_PROFILE=perf:call     → expensive Lua functions?
│
├── It used to work, now it doesn't
│     └─ xmake l cli.bisect -g <old> -b <new> --gitdir=... -c "..."
│
└── I need to step through the source
      └─ see the `xmake-dev` skill (build + srcenv + gdb/emmylua)

When to branch out

  • Building xmake from source / Lua + C debugging in depth → xmake-dev
  • Package install fails specifically → xmake-packages, xmake-repo-testing
  • Toolchain-detection hangs → xmake-toolchains

Keep looking

Skills are one crate of 613,531. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.