Back to Details

xc-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

xc-dev

xc-dev

xc-dev
is a Rust task runner for Xcode projects. It reads 
.xc-dev/project.toml
, 
.xc-dev/simulator.toml
, and 
.xc-dev/tasks.toml
and runs named tasks (
build
, 
run
, 
test
, 
test-package
, …) with 
{{scheme}}
/ 
{{bundle_id}}
/ 
{{sim_id}}
/ 
{{derived_data}}
/ 
{{git_branch}}
substituted in.
xc-dev
是一款用于Xcode项目的Rust任务运行器。它会读取
.xc-dev/project.toml
、
.xc-dev/simulator.toml
和
.xc-dev/tasks.toml
文件，并执行命名任务（如
build
、
run
、
test
、
test-package
等），同时替换其中的
{{scheme}}
/
{{bundle_id}}
/
{{sim_id}}
/
{{derived_data}}
/
{{git_branch}}
变量。

When to use this skill

何时使用该工具

Activate when all of these are true:
  • The user is doing iOS / Xcode work (build, run, test, install, launch, archive, log stream, clean DerivedData, etc.).
  • The project has a 
    .xc-dev/
    directory anywhere up from cwd (run 
    ls -d .xc-dev 2>/dev/null
    or walk up; an existing 
    tasks.toml
    is the dispositive signal).
Do not use this skill — fall back to generic Xcode tooling — when:
  • The project has no 
    .xc-dev/
    and the user isn't asking to set one up.
当所有以下条件都满足时启用：
  • 用户正在进行iOS/Xcode相关工作（构建、运行、测试、安装、启动、归档、日志流、清理DerivedData等）。
  • 项目中从当前工作目录向上的任意位置存在
    .xc-dev/
    目录（可运行
    ls -d .xc-dev 2>/dev/null
    或向上遍历目录；若存在
    tasks.toml
    则是明确信号）。
请勿使用该工具——转而使用通用Xcode工具——当：
  • 项目中没有
    .xc-dev/
    目录，且用户未要求创建该目录时。

Discovery first

先进行发现操作

Before assuming task names, list them:
sh
xc-dev               # bare form is shorthand for `xc-dev :list`
xc-dev :list
For variables (scheme, bundle id, sim id, derived data path, git branch, …):
sh
xc-dev :get scheme
xc-dev :get bundle_id
xc-dev :get sim_id
xc-dev :get derived_data
xc-dev :get sim.ipad.id      # qualified, non-default sim
xc-dev :get git_branch
To sanity-check the config and every task's variable references:
sh
xc-dev :doctor
在假设任务名称之前，先列出所有任务：
sh
xc-dev               # 裸命令是`xc-dev :list`的简写
xc-dev :list
查看变量（scheme、bundle id、sim id、DerivedData路径、git分支等）：
sh
xc-dev :get scheme
xc-dev :get bundle_id
xc-dev :get sim_id
xc-dev :get derived_data
xc-dev :get sim.ipad.id      # 指定非默认模拟器
xc-dev :get git_branch
检查配置及所有任务的变量引用是否正常：
sh
xc-dev :doctor

Running tasks

运行任务

sh
xc-dev build
xc-dev build Release           # positional override of `args = ["config=Debug"]`
xc-dev test-package Networking
xc-dev -v build                # echo expanded command to stderr (handy for debugging)
Exit codes:
  • 0
    — success
  • 1
    — task error (config invalid, command failed, variable unresolved, …)
  • 2
    — CLI parse error (unknown built-in, missing flag value, …)
sh
xc-dev build
xc-dev build Release           # 位置参数覆盖`args = ["config=Debug"]`配置
xc-dev test-package Networking
xc-dev -v build                # 将展开后的命令输出到stderr（便于调试）
退出码：
  • 0
    —— 成功
  • 1
    —— 任务错误（配置无效、命令执行失败、变量未解析等）
  • 2
    —— CLI解析错误（未知内置命令、缺少标志值等）

When the task you need doesn't exist

当所需任务不存在时

Prefer adding a task to 
.xc-dev/tasks.toml
 rather than constructing an 
xcodebuild
invocation yourself. Two reasons:
  1. The next person doing the same thing will benefit from the task being there.
  2. The variables are already wired up — 
    {{scheme}}
    , 
    {{derived_data}}
    , etc. all resolve correctly, so you don't have to re-derive them.
Show the user the proposed task and ask before editing.
优先向
.xc-dev/tasks.toml
中添加任务，而非自行构造
xcodebuild
调用。原因有二：
  1. 后续执行相同操作的人会受益于已存在的任务。
  2. 变量已配置完成——
    {{scheme}}
    、
    {{derived_data}}
    等均可正确解析，无需重新推导。
在编辑前，向用户展示拟添加的任务并征得同意。

Built-in verbs (cheat sheet)

内置命令速查表

VerbWhat
xc-dev :proj init
Scaffold 
.xc-dev/
(autodetects scheme/bundle_id via 
xcodebuild
)
xc-dev :list
List all tasks with their 
desc
xc-dev :get <key>
Print one variable
xc-dev :doctor
Sanity-check config + every task's vars + depends
xc-dev :clean
Dry-run: list local + system DerivedData for this project
xc-dev :clean --yes
Delete them (Packages under the root included; skips 
*.noindex
)
xc-dev :sim bake
Resolve simulator UDIDs into 
simulator.toml
命令功能
xc-dev :proj init
快速搭建
.xc-dev/
目录（通过
xcodebuild
自动检测scheme/bundle_id）
xc-dev :list
列出所有任务及其
desc
描述
xc-dev :get <key>
打印指定变量的值
xc-dev :doctor
检查配置、所有任务的变量及依赖是否正常
xc-dev :clean
试运行：列出该项目的本地及系统DerivedData
xc-dev :clean --yes
删除上述DerivedData（包含根目录下的Packages；跳过
*.noindex
）
xc-dev :sim bake
将模拟器UDID解析到
simulator.toml
中

Common patterns

常见使用模式

Boot + launch the default sim:
sh
xc-dev run     # if the user has set up the example `run` task
启动默认模拟器并运行应用：
sh
xc-dev run     # 若用户已配置示例`run`任务

else manually:

否则手动执行：

xcrun simctl boot $(xc-dev :get sim_id) 2>/dev/null || true xcrun simctl install $(xc-dev :get sim_id) $(xc-dev :get app_path) xcrun simctl launch $(xc-dev :get sim_id) $(xc-dev :get bundle_id)

**Inspect the app bundle that the build produced:**

```sh
ls "$(xc-dev :get app_path)"
Per-worktree DerivedData:
{{derived_data}}
defaults to 
{{xc_dev_dir}}/DerivedData
, so each git worktree has its own build cache and they don't fight each other.
Clean DerivedData (local + system):
Prefer the builtin — do not only 
rm -rf
local DerivedData or hand-scan 
~/Library/Developer/Xcode/DerivedData
by folder name:
sh
xc-dev :clean          # dry-run
xc-dev :clean --yes    # delete local {{derived_data}} + system entries whose
                       # info.plist WorkspacePath is under this project root
                       # (main .xcodeproj and Packages/*)
If the project has a 
clean
task, prefer 
xc-dev clean
when it wraps 
:clean
(and optionally 
sim-delete
). Simulator deletion is not part of 
:clean
.
xcrun simctl boot $(xc-dev :get sim_id) 2>/dev/null || true xcrun simctl install $(xc-dev :get sim_id) $(xc-dev :get app_path) xcrun simctl launch $(xc-dev :get sim_id) $(xc-dev :get bundle_id)

**查看构建生成的应用包：**

```sh
ls "$(xc-dev :get app_path)"
每个工作树独立的DerivedData：
{{derived_data}}
默认值为
{{xc_dev_dir}}/DerivedData
，因此每个git工作树都有自己的构建缓存，不会互相干扰。
清理DerivedData（本地+系统）：
优先使用内置命令——不要仅通过
rm -rf
删除本地DerivedData，或手动遍历
~/Library/Developer/Xcode/DerivedData
文件夹：
sh
xc-dev :clean          # 试运行
xc-dev :clean --yes    # 删除本地{{derived_data}}及系统中info.plist的WorkspacePath位于该项目根目录下的条目
                       # （包含主.xcodeproj和Packages/*）
若项目中有
clean
任务，当该任务封装了
:clean
（可选包含
sim-delete
）时，优先使用
xc-dev clean
。模拟器删除不属于:clean的功能。

Reference docs

参考文档

If you need more detail than this skill provides, point the user at:
  • crates/xc-dev/docs/tasks.md
    — full Task DSL reference
  • crates/xc-dev/docs/variables.md
    — every built-in variable + resolution order
  • crates/xc-dev/docs/config.md
    — TOML schemas
  • crates/xc-dev/docs/examples.md
    — example task recipes
如果需要比本工具提供的更多细节，请引导用户查看：
  • crates/xc-dev/docs/tasks.md
    —— 完整的Task DSL参考文档
  • crates/xc-dev/docs/variables.md
    —— 所有内置变量及解析顺序
  • crates/xc-dev/docs/config.md
    —— TOML配置 schema
  • crates/xc-dev/docs/examples.md
    —— 任务示例

Relationship to other skills

与其他工具的关系

  • xcodebuildmcp-cli
     — reserved for UI automation, log streaming, and interactive debugging that xc-dev doesn't cover.
  • xcodebuildmcp-cli
     —— 用于xc-dev未覆盖的UI自动化、日志流及交互式调试场景。