xmake-skills

Use when switching xmake's output theme (colors, progress style, emoji) or fixing garbled/unreadable terminal output — `xmake g --theme=...`. Built-in themes: default, ninja, emoji, dark, light, plain, powershell.

Use when the user is starting a new Xmake project, installing Xmake, or needs the minimal xmake.lua structure. Covers installation, `xmake create`, the project layout, and the smallest valid xmake.lua.

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.

Use when creating a new xmake project from a built-in or third-party template (`xmake create -t <template>`), listing available templates, or authoring and distributing custom templates (built-in, user-global, or via xmake-repo). Covers template layout, `${TARGET_NAME}` / `${FAQ}` substitution, and language selection.

Use when invoking Xmake from the command line — configuring, building, running, cleaning, installing, packing, or inspecting a project. Covers the common flags for `xmake f`, `xmake`, `xmake run`, `xmake install`, `xmake pack`, and friends.

Use when exporting an xmake project to another build system or IDE — `compile_commands.json` for clangd/LSP, `CMakeLists.txt`, `build.ninja`, Visual Studio solution (`vsxmake`), or an Xcode project. Covers `xmake project -k <kind>` and how each generator is typically used.

Use when you want to build a third-party project that uses CMake, Autotools, Meson, Ninja, Bazel, Make, MSBuild, Xcodebuild, or NdkBuild — through xmake, so you inherit xmake's cross-compilation and toolchain detection. Covers `xmake` auto-detection, `--trybuild=<system>`, `--tryconfigs="..."`, and cross-compile recipes for Android / iOS / MinGW / custom SDKs.

Use when building C# projects with xmake — `.cs` sources with the Mono `mcs` or .NET `dotnet` toolchain, binary / library output, adding references, and mixing with native code via P/Invoke.

Use when building CUDA projects with xmake — `.cu` sources, `--cuda=` / `--cuda_sdkver=` SDK pinning, GPU architecture selection, device linking (`build.cuda.devlink`), and mixing CUDA with C++ targets.

Use when building D projects with xmake — binary/library targets with `.d` sources, DUB package integration via `add_requires("dub::...")`, and selecting DMD / LDC / GDC compilers.

Use when building Fortran projects with xmake — binary/library targets with `.f`/`.f90`/`.for` sources, gfortran or Intel Fortran (`ifort`) toolchain selection, and mixing Fortran with C interoperability.

Use when building Go projects with xmake — binary/library targets with `.go` sources, go module integration, cross-compiling Go programs for other OS/arch, and mixing Go with C via cgo.

Use when building Kotlin/Native projects with xmake — `.kt` sources for native (not JVM) targets, using the `kotlin-native` toolchain, producing executables and static/shared libraries.

Use when building Nim projects with xmake — binary/library targets with `.nim` sources, choosing the C backend (the default) vs C++, and mixing Nim with C.

Use when building Objective-C or Objective-C++ projects with xmake — `.m` / `.mm` sources, Cocoa / Foundation frameworks via `add_frameworks`, mixing with C++, and targeting macOS / iOS / tvOS.

Use when building Pascal projects with xmake — `.pas`/`.pp`/`.lpr` sources, FreePascal (`fpc`) / Delphi toolchain, binary and shared-library targets.

Use when building Rust projects with xmake — binary/library targets with `.rs` sources, Cargo package integration via `add_requires("cargo::...")` or full `Cargo.toml` management, C↔Rust interop with `cxxbridge`, `rustc` edition / toolchain selection, and cross-compile.

Use when building Swift projects with xmake — binary/library targets with `.swift` sources, Swift ↔ C++/Objective-C interop (`swift.interop` value), Swift module name configuration, and iOS/macOS builds.

Use when building Vala projects with xmake — `.vala` sources with the `add_rules("vala")` rule, glib dependency, declaring used VAPI packages with `add_values("vala.packages", ...)`, and producing executables or shared/static libraries with exported headers/VAPIs.

Use when building Zig projects with xmake — binary/library targets with `.zig` sources, cross-compilation (one of Zig's strengths), and mixing Zig with C.

Use when hacking on Xmake itself — building the `xmake` binary from source, loading the local source tree so your changes take effect without reinstalling, and debugging either the Lua scripts under `xmake/` or the native C core under `core/src/xmake`.

Use when configuring xmake via environment variables — `XMAKE_PROGRAM_DIR`/`XMAKE_PROGRAM_FILE` (local source debug), `XMAKE_GLOBALDIR`/`XMAKE_CONFIGDIR` (config locations), `XMAKE_COLORTERM`/`XMAKE_PROFILE`, `XMAKE_RCFILES` (global defaults), `XMAKE_ROOT`, and how to list/inspect them with `xmake show -l envs`.

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.

Use when a package from `add_requires` / xmake-repo fails to build or misbehaves, and you need to debug its source — editing the upstream files in place without patches, running the recipe against a local source tree with `-d <dir>`, stepping through `on_install`, extracting the patch once fixed, and remote debugging via `--remote`.

Use when package downloads are slow, failing, or blocked — especially in China or behind corporate networks. Covers HTTP/SOCKS5 proxies (`xmake g --proxy`), host allow-lists, `pac.lua` routing, `mirror()` URL rewriting for GitHub acceleration, manual download directories, and recommended mirror setups for domestic network environments.

Use when distributing C/C++ libraries *inside a company or team* — packaging a library with `xmake package`, creating a private package repository (local directory or git), writing package recipes for source/binary distribution, and consuming them via `add_repositories` + `add_requires`. For shipping end-user installers (zip/nsis/deb), see `xmake-xpack`.

Use when adding or modifying a package recipe in the xmake-repo repository (github.com/xmake-io/xmake-repo) and you need to test-build it locally. Wraps the `xmake l scripts/test.lua` workflow with `--shallow`, platform/arch/mode/kind/configs flags so package changes can be verified quickly before submitting a PR.

Use when installing, inspecting, or exporting C/C++ packages from the command line with `xrepo` — xmake's standalone package manager. Covers install/search/info/fetch/export/download, repository management, and package virtual environments (`xrepo env`).

Use when the user wants a virtual environment of C/C++ libraries and CLI tools managed by xrepo — dropping into a shell with python/luajit/cmake/etc. on PATH, pinning per-project tool versions via `xmake.lua`, or registering named global environments. Conceptually similar to conda/venv but for C/C++ and native CLI tools.

Use when producing distributable packages from an xmake project — zip/tar.gz/deb/rpm/nsis/wix/srpm/pacman/runself/zst etc. — via `xpack(...)` in `xmake.lua` and the `xmake pack` CLI. Covers package metadata, format selection, install layout, components, custom install commands, and CLI flags.

Use when configuring or debugging xmake's local build cache (built-in, replaces ccache) or the remote compile cache service (shared across machines via `xmake service --ccache`). Covers enabling/disabling, fallbacks to external ccache, remote cache server/client setup, and cache cleaning.

Use when a project builds slowly and you want to make it faster — parallel jobs, unity build, precompiled headers, build cache, LTO, link-time improvements, binary package cache, and profiling with `XMAKE_PROFILE=perf:*`. Covers idiomatic xmake speedups and the order to try them.

Use when setting up or using xmake's built-in distributed compilation (distcc-equivalent) to offload compile jobs to a cluster of servers. Covers `xmake service --distcc`, server/client config, token auth, job control, combining with local/remote cache, and distributed cross-compilation (Android/iOS).

Use when compiling and running a project on a remote machine transparently — edit locally, build/run/debug on a Linux/macOS/Windows server. Covers `xmake service` (remote build server), multi-host client config, token/password auth, `--sync`/`--pull`, and the difference from distributed compilation.

Use when probing the host/toolchain for capabilities inside `xmake.lua` — `has_cfuncs` / `has_cxxtypes` / `has_features`, `check_csnippets`, `check_cflags` / `check_cxxflags`, option auto-probes (`add_cxxincludes` / `add_cfuncs`), and `lib.detect.find_*`. Covers how to gate target config on whether a symbol/header/flag is actually usable on the target platform.

Use when fixing linker errors caused by symbol-order or circular-dependency issues in static libraries — `add_linkorders`, `add_linkgroups` (GNU ld `--start-group`/`--end-group`), whole-archive (`-Wl,--whole-archive`), weak linking, and library strip-off problems. Covers macOS, Linux, MSVC specifics.

Use when defining user-configurable build options (`option(...)`), reading them from targets, or exposing them on the `xmake f` command line. Covers showmenu, default, values, and option-driven config.h generation.

Use when adding third-party C/C++ dependencies to an Xmake project — via `add_requires` / `add_packages`, configuring package options, pinning versions, or using `xrepo` from the command line.

Use when setting build policies via `set_policy("name", value)` — named feature toggles that control sanitizers, LTO, warnings, C++ modules, ccache, module-reuse, rpath, preprocessor behavior, package download strict mode, and many others. Covers the common policies grouped by purpose, how to scope them (project vs target), and where to find the full list.

Use when applying built-in rules (e.g. `mode.debug`, `mode.release`, `qt.widgetapp`, `c++.unity_build`) or writing a custom rule to handle a new file extension or codegen step.