xmake-troubleshooting

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.