xcode-compilation-analyzer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode Compilation Analyzer

Use this skill when compile time, not just general project configuration, looks like the bottleneck.

当编译时间（而非仅仅是常规项目配置）成为瓶颈时，可使用此技能。

Core Rules

核心规则

Start from evidence, ideally a recent
```
.build-benchmark/
```
artifact or raw timing-summary output.
Prefer analysis-only compiler flags over persistent project edits during investigation.
Rank findings by expected wall-clock impact, not cumulative compile-time impact. When compile tasks are heavily parallelized (sum of compile categories >> wall-clock median), note that fixing individual hotspots may improve parallel efficiency without reducing build wait time.
When the evidence points to parallelized work rather than serial bottlenecks, label recommendations as "Reduces compiler workload (parallel)" rather than "Reduces build time."
Do not edit source or build settings without explicit developer approval.

从实证出发，优先使用最新的
```
.build-benchmark/
```
工件或原始时间摘要输出。
在调查期间，优先使用仅用于分析的编译器标志，而非对项目进行持久化修改。
根据预期的实际耗时影响对发现的问题进行排序，而非累计编译时间影响。当编译任务高度并行化时（编译类别总和远大于实际耗时中位数），需注意修复单个热点可能会提升并行效率，但不会减少构建等待时间。
当实证表明问题在于并行化工作而非串行瓶颈时，将建议标注为“减少编译器工作负载（并行）”，而非“减少构建时间”。
未经开发者明确批准，不得修改源码或构建设置。

What To Inspect

检查内容

```
Build Timing Summary
```
output from clean and incremental builds
long-running
```
CompileSwiftSources
```
or per-file compilation tasks
```
SwiftEmitModule
```
time -- can reach 60s+ after a single-line change in large modules; if it dominates incremental builds, the module is likely too large or macro-heavy
```
Planning Swift module
```
time -- if this category is disproportionately large in incremental builds (up to 30s per module), it signals unexpected input invalidation or macro-related rebuild cascading

ad hoc runs with:

-Xfrontend -warn-long-expression-type-checking=<ms>

-Xfrontend -warn-long-function-bodies=<ms>

deeper diagnostic flags for thorough investigation:
- ```
-Xfrontend -debug-time-compilation
```
  -- per-file compile times to rank the slowest files
- ```
-Xfrontend -debug-time-function-bodies
```
  -- per-function compile times (unfiltered, complements the threshold-based warning flags)
- ```
-Xswiftc -driver-time-compilation
```
  -- driver-level timing to isolate driver overhead
- ```
-Xfrontend -stats-output-dir <path>
```
  -- detailed compiler statistics (JSON) per compilation unit for root-cause analysis
mixed Swift and Objective-C surfaces that increase bridging work

纯净构建和增量构建的
```
Build Timing Summary
```
输出
长时间运行的
```
CompileSwiftSources
```
任务或单文件编译任务
```
SwiftEmitModule
```
耗时——在大型模块中修改一行代码后，该耗时可能达到60秒以上；如果它在增量构建中占主导地位，说明该模块可能过大或宏使用过多
```
Planning Swift module
```
耗时——如果该类别在增量构建中占比过高（每个模块最多可达30秒），则表明存在意外的输入失效或与宏相关的重建级联问题

使用以下标志进行临时运行：

-Xfrontend -warn-long-expression-type-checking=<ms>

-Xfrontend -warn-long-function-bodies=<ms>

用于深入调查的诊断标志：
- ```
-Xfrontend -debug-time-compilation
```
  —— 按单文件编译时间排序，找出最慢的文件
- ```
-Xfrontend -debug-time-function-bodies
```
  —— 按函数编译时间统计（无过滤，补充基于阈值的警告标志）
- ```
-Xswiftc -driver-time-compilation
```
  —— 驱动程序级别的时间统计，用于隔离驱动程序开销
- ```
-Xfrontend -stats-output-dir <path>
```
  —— 每个编译单元的详细编译器统计信息（JSON格式），用于根因分析
增加桥接工作的Swift与Objective-C混合交互部分

Analysis Workflow

分析流程

Identify whether the main issue is broad compilation volume or a few extreme hotspots.
Parse timing-summary categories and rank the biggest compile contributors.
Run the diagnostics script to surface type-checking hotspots:
bash
```
python3 scripts/diagnose_compilation.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --threshold 100 \
  --output-dir .build-benchmark
```
This produces a ranked list of functions and expressions that exceed the millisecond threshold. Use the diagnostics artifact alongside source inspection to focus on the most expensive files first.
Map the evidence to a concrete recommendation list.
Separate code-level suggestions from project-level or module-level suggestions.

确定主要问题是广泛的编译量过大还是存在少数极端热点。
解析时间摘要类别，并对最大的编译耗时贡献项进行排序。

运行诊断脚本以找出类型检查热点：

bash

python3 scripts/diagnose_compilation.py \
  --project App.xcodeproj \
  --scheme MyApp \
  --configuration Debug \
  --destination "platform=iOS Simulator,name=iPhone 16" \
  --threshold 100 \
  --output-dir .build-benchmark

这会生成一个超过毫秒阈值的函数和表达式的排序列表。结合诊断工件和源码检查，优先关注耗时最长的文件。

将实证映射到具体的建议列表中。
将代码级建议与项目级或模块级建议分开。

Apple-Derived Checks

Apple 衍生检查项

Look for these patterns first:

missing explicit type information in expensive expressions
complex chained or nested expressions that are hard to type-check
delegate properties typed as
```
AnyObject
```
instead of a concrete protocol
oversized Objective-C bridging headers or generated Swift-to-Objective-C surfaces
header imports that skip framework qualification and miss module-cache reuse
classes missing
```
final
```
that are never subclassed
overly broad access control (
```
public
```
/
```
open
```
) on internal-only symbols
monolithic SwiftUI
```
body
```
properties that should be decomposed into subviews
long method chains or closures without intermediate type annotations

耗时表达式中缺少显式类型信息
难以进行类型检查的复杂链式或嵌套表达式
委托属性被声明为
```
AnyObject
```
而非具体协议
过大的Objective-C桥接头文件或生成的Swift到Objective-C交互部分
跳过框架限定的头文件导入，导致无法复用模块缓存
从未被继承但缺少
```
final
```
修饰的类
仅内部使用的符号使用了过于宽泛的访问控制（
```
public
```
/
```
open
```
）
应拆分为子视图的单体SwiftUI
```
body
```
属性
没有中间类型注解的长方法链或闭包

Reporting Format

报告格式

For each recommendation, include:

observed evidence
likely affected file or module
expected wait-time impact (e.g. "Expected to reduce your clean build by ~2s" or "Reduces parallel compile work but unlikely to reduce build wait time")
confidence
whether approval is required before applying it

If the evidence points to project configuration instead of source, hand off to

xcode-project-analyzer

by reading its SKILL.md and applying its workflow to the same project context.

每个建议应包含：

观察到的实证
可能受影响的文件或模块
预期的等待时间影响（例如：“预计可将纯净构建时间减少约2秒”或“减少并行编译工作，但不太可能减少构建等待时间”）
置信度
应用前是否需要批准

如果实证表明问题在于项目配置而非源码，请将任务移交给

xcode-project-analyzer

，阅读其SKILL.md并将其工作流应用于相同的项目上下文。

Preferred Tactics

优先策略

Suggest ad hoc flag injection through the build command before recommending persistent build-setting changes.
Prefer narrowing giant view builders, closures, or result-builder expressions into smaller typed units.
Recommend explicit imports and protocol typing when they reduce compiler search space.
Call out when mixed-language boundaries are the real issue rather than Swift syntax alone.

在建议持久化修改构建设置之前，建议通过构建命令临时注入标志。
优先将大型视图构建器、闭包或结果构建器表达式拆分为更小的带类型单元。
当显式导入和协议类型可以减少编译器搜索空间时，推荐使用。
当真正的问题是混合语言边界而非单纯的Swift语法时，需明确指出。

Additional Resources

额外资源

For the detailed audit checklist, see references/code-compilation-checks.md
For the shared recommendation structure, see references/recommendation-format.md
For source citations, see references/build-optimization-sources.md

详细的审核清单，请参阅references/code-compilation-checks.md
通用建议结构，请参阅references/recommendation-format.md
来源引用，请参阅references/build-optimization-sources.md