xmake-build-optimization

Xmake Build Optimization & Best Practices

A roadmap for making an xmake build faster. Try them in order — each has a different cost/benefit. Measure before and after with XMAKE_PROFILE=perf:tag (or time xmake).

0. Measure first

Don't guess where the time goes:

XMAKE_PROFILE=perf:tag     xmake        # compile vs link vs other
XMAKE_PROFILE=perf:process xmake        # which subprocesses dominate
XMAKE_PROFILE=perf:call    xmake        # expensive Lua functions
XMAKE_PROFILE=trace        xmake f -c   # trace every subprocess in configure
time xmake --rebuild                    # total wall-clock

Profile before each change — "speedups" often turn out to be in the cache-hit, not the fix.

See xmake-troubleshooting for the full profiler reference.

1. Parallelism

xmake -j N                              # N parallel jobs
xmake -j $(nproc)
xmake -j $(sysctl -n hw.ncpu)           # macOS

Default is already ⌈3/2 × ncpu⌉. Override for:

• Huge machines where xmake's default is too conservative.
• Memory-limited builds where you need to reduce parallelism (big LTO links can OOM).

2. Local compile cache (on by default)

xmake f --ccache=y          # default
xmake f --ccache=n          # disable for debugging

Xmake ships a built-in cache since 2.6.6 — faster than external ccache, cross-platform (MSVC too). See xmake-build-cache.

Verify it's working — look for cache compiling.release in the output.

3. Unity builds

Compile multiple source files as one translation unit. Massive speedup (2–5×) for projects with hundreds of small files.

target("mylib")
    add_rules("c++.unity_build", {batchsize = 8})    -- 8 files per unit
    add_rules("c.unity_build")
    add_files("src/*.cpp")

Pitfalls (usual unity-build ones):

• File-local static symbols clash with same-named symbols in another file in the same unit. Rename or exclude.
• Anonymous namespaces collide similarly.
• Order-dependent macros leak across files in the same unit.