Xmake Repo Testing

Testing Packages in xmake-repo

xmake-repo is the official package recipe repository. Each recipe is a packages///xmake.lua describing how to fetch, build, and install a library. The repo ships a test script at scripts/test.lua that drives a full install + test build of a recipe exactly like CI does.

Always run it from the xmake-repo checkout root.

The core command

xmake l scripts/test.lua -vD --shallow 

• xmake l — run a Lua script in the xmake environment.
• -v — verbose (show each sub-command).
• -D — diagnosis (full tracebacks on failure; essential when debugging a broken recipe).
• --shallow — only install the package you asked for, not its dependencies. Dependencies are pulled from the remote binary cache instead of rebuilt locally. This is the single most important flag for iterating quickly.
• ` — the package name, e.g. fmt, zlib, boost`.

Example — test the fmt recipe:

cd xmake-repo
xmake l scripts/test.lua -vD --shallow fmt

Common variations

Version / branch

Append the version to the package name, same syntax as add_requires:

xmake l scripts/test.lua -vD --shallow "fmt 10.2.1"
xmake l scripts/test.lua -vD --shallow "cmake master"

Quote it — the space matters.

Static vs shared

xmake l scripts/test.lua -vD --shallow -k shared fmt
xmake l scripts/test.lua -vD --shallow -k static fmt

Debug / release

xmake l scripts/test.lua -vD --shallow -m debug  fmt
xmake l scripts/test.lua -vD --shallow -m release fmt

Platform / arch

xmake l scripts/test.lua -vD --shallow -p linux   -a x86_64 fmt
xmake l scripts/test.lua -vD --shallow -p macosx  -a arm64  fmt
xmake l scripts/test.lua -vD --shallow -p mingw   -a x86_64 --mingw=/opt/llvm-mingw fmt
xmake l scripts/test.lua -vD --shallow -p android -a arm64-v8a --ndk=~/android-ndk-r26 fmt
xmake l scripts/test.lua -vD --shallow -p iphoneos -a arm64 fmt
xmake l scripts/test.lua -vD --shallow -p wasm --toolchain=emcc fmt

Package configs (recipe options)

Recipes declare options via add_configs(...). Pass them with -f:

xmake l scripts/test.lua -vD --shallow -f "shared=true,pic=true" openssl
xmake l scripts/test.lua -vD --shallow -f "header_only=false" fmt
xmake l scripts/test.lua -vD --shallow -f "regex=true,system=true" boost

MSVC runtime / toolset

xmake l scripts/test.lua -vD --shallow --runtimes=MD  fmt
xmake l scripts/test.lua -vD --shallow --runtimes=MT  fmt
xmake l scripts/test.lua -vD --shallow --vs=2022 --vs_toolset=14.38 fmt

Fetch-only (no build)

Verify URL, hash, and unpack work without actually compiling:

xmake l scripts/test.lua -vD --shallow --fetch fmt

Try the precompiled artifact

xmake l scripts/test.lua -vD --shallow --precompiled fmt

Debugging the source build

Point at a local source tree to iterate on patches without re-downloading:

xmake l scripts/test.lua -vD --shallow -d /path/to/fmt-source fmt

What the script actually does

1. Reads packages///xmake.lua.
2. Runs xmake f -c with your flags.
3. Installs the package (with --shallow, deps come from the remote cache).
4. Builds and runs the recipe's on_test(...) block against the installed package.

A successful run ends with passed!. A failure prints the command that failed — rerun it with -vD if you didn't already.

Iteration workflow

1. xmake l scripts/list.lua — see recipe metadata.
2. Edit packages///xmake.lua.
3. xmake l scripts/test.lua -vD --shallow — test.
4. Adjust add_configs, on_install, on_test until green.
5. Repeat on other platforms if the recipe is cross-platform.

For a brand-new package, scaffold it first:

xmake l scripts/new.lua 

Useful flags reference

| Flag | Purpose | | --- | --- | | -v / -D | verbose / diagnosis | | --shallow | only install the target package, not its deps | | -k static\|shared | library kind | | -m debug\|release | build mode | | -p / -a | target platform / architecture | | -f "k=v,k=v" | package configs (recipe options) | | --runtimes=MD\|MT\|MDd\|MTd | MSVC runtime | | --vs=, --vs_toolset=, --vs_sdkver= | VS version pinning | | --ndk=, --ndk_sdkver= | Android NDK | | --sdk=, --mingw= | cross-toolchain roots | | --toolchain= | force a toolchain | | --fetch | fetch/unpack only, no build | | --precompiled | install from binary cache | | --remote | run test on the remote server | | -d | use a local source directory (debug patches) |

Common pitfalls

• Forgetting --shallow. Without it, the script rebuilds every transitive dependency from source — turning a 10-second iteration into 30 minutes.
• Running from the wrong directory. The script must be invoked from the xmake-repo checkout root so scripts/test.lua and packages/ resolve correctly.
• Stale cache hiding your change. Force a clean build with xmake require --force or delete ~/.xmake/packages//// between runs if a recipe change does not seem to take effect.
• Quoting version strings. fmt 10.2.1 must be one quoted argument, otherwise the shell splits it and 10.2.1 is parsed as a separate flag.

When to branch out

• Consuming packages from a project → xmake-packages
• Cross-compilation setup → xmake-toolchains

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xmake-io
• Source: xmake-io/xmake-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.