# Xmake Build Cache

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-xmake-io-xmake-skills-xmake-build-cache`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xmake-io](https://agentstack.voostack.com/s/xmake-io)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [xmake-io](https://github.com/xmake-io)
- **Source:** https://github.com/xmake-io/xmake-skills/tree/master/skills/performance/xmake-build-cache

## Install

```sh
agentstack add skill-xmake-io-xmake-skills-xmake-build-cache
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Xmake Build Cache (Local & Remote)

Xmake has a built-in compile cache that speeds up rebuilds by reusing object files. Two flavors:

- **Local cache** — on by default, per-machine, cross-platform (GCC/Clang/MSVC). Replaces ccache for most users.
- **Remote cache** — a shared server that machines can push/pull objects from. Like Mozilla sccache but cross-platform.

Both use the same `--ccache` name on the CLI — `--ccache=` is xmake-speak for "C/C++ build cache", not the ccache tool specifically.

## 1. Local cache (default)

Enabled automatically. No setup required. Since v2.6.6, xmake uses its own built-in local cache; before that it shelled out to the system `ccache`.

### Toggle

```bash
xmake f --ccache=n           # disable for this project
xmake f --ccache=y           # re-enable
```

### Use external ccache instead

If you specifically want the third-party `ccache` tool (e.g. for CI cache sharing with non-xmake builds):

```bash
xmake f --ccache=n --cxx="ccache g++" --cc="ccache gcc"
xmake
```

Note the `--ccache=n` — disables xmake's built-in cache so the two don't stack.

### Benefits of the built-in cache over external ccache

- **Cross-platform.** Works on Windows/MSVC; ccache doesn't.
- **No subprocess overhead.** Xmake does the lookup in-process — no per-file `ccache` fork.
- **Integrated state.** Xmake already tracks dependencies, so cache keys are tighter.

### Cache location

- Local cache directory: `~/.xmake/cache/` (cross-project shared).
- Clean it:
  ```bash
  xmake g --clean                # nuclear: wipe global cache
  ```

## 2. Remote cache service

Shared cache server. First developer to compile uploads objects; everyone else downloads them. Big win for CI + team setups.

### Start the server

```bash
xmake service --ccache                     # foreground
xmake service --ccache -vD                 # verbose
xmake service --ccache --start             # daemonize
xmake service --ccache --stop
xmake service --ccache --restart
```

First run creates `~/.xmake/service/server.conf` and prints a generated token.

### Server config (`~/.xmake/service/server.conf`)

```
{
    remote_cache = {
        listen = "0.0.0.0:9692",
        workdir = "/Users/ruki/.xmake/service/server/remote_cache"
    },
    known_hosts = { },
    logfile = "/Users/ruki/.xmake/service/server/logs.txt",
    tokens = {
        "590234653af52e91b9e438ed860f1a2b"
    }
}
```

- `listen` — host:port to bind.
- `workdir` — cache storage on the server.
- `tokens` — list of allowed client tokens. Generate more with `xmake service --gen-token`.
- `known_hosts` — optional IP allowlist (harden access).

### Client config (`~/.xmake/service/client.conf`)

```
{
    remote_cache = {
        connect = "cache.internal:9692",
        token   = "590234653af52e91b9e438ed860f1a2b"
    }
}
```

### Connect and use

```bash
cd myproject
xmake service --connect --ccache          # just the cache service
xmake service --connect --distcc --ccache # combine with distributed compile
xmake                                      # builds as usual, cache hits are transparent
```

Cache hits show up in output as the normal "cache compiling" line — xmake pulls from the remote server instead of compiling.

### Disconnect / clean

```bash
xmake service --disconnect --ccache
xmake service --clean --ccache             # wipe this project's cache on the server
xmake clean --all                          # (connected) also cleans remote cache
```

### Timeouts

If the server network is flaky, add timeouts so clients fall back to local compilation instead of hanging:

```
{
    remote_cache = {
        connect_timeout = 5000,
        send_timeout    = 5000,
        recv_timeout    = 5000,
    }
}
```

Unit: milliseconds. Works on both server and client sides.

## 3. Inspecting cache behavior

```bash
xmake -v                         # verbose: shows `cache compiling` vs normal lines
xmake --rebuild                  # force full rebuild, bypass cache
xmake -rv                        # rebuild verbose
```

In the build log:

- `cache compiling` — served from cache (local or remote).
- `compiling` (plain) — cache miss, actually compiled.
- `distcc compiling` — delegated to a distcc server (see `xmake-distributed-compilation`).

## Pitfalls

- **`--ccache=n` but cache still active.** You disabled the xmake built-in, but if `CXX=ccache g++` is in the env, ccache is still interposing. `unset CXX CC` or point at the raw compiler.
- **Remote cache hanging the build.** Add `connect_timeout` / `send_timeout` / `recv_timeout` so the client degrades to local on network trouble.
- **Token mismatch.** Every server restart does **not** regenerate tokens, but the first run does. If you nuke `~/.xmake/service/`, all clients need the new token.
- **Cache is project-scoped on the server.** Cleaning "the cache" cleans only the current project (by workdir hash). `xmake service --clean --ccache` inside a different project only affects that project.
- **Compiler version must match.** Cache keys include the compiler identity. A cache filled by gcc-11 on one box won't hit for gcc-12 on another — that's correct, not a bug.

## When to branch out

- Distributing the actual compile jobs across machines (not just caching) → `xmake-distributed-compilation`
- Remotely compiling a project on a single server (no distribution) → `xmake-remote-compilation`
- Every other build-speed knob (parallelism, unity build, PCH, etc.) → `xmake-build-optimization`

## 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](https://github.com/xmake-io)
- **Source:** [xmake-io/xmake-skills](https://github.com/xmake-io/xmake-skills)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xmake-io-xmake-skills-xmake-build-cache
- Seller: https://agentstack.voostack.com/s/xmake-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.