Unreal Engine IWYU Include What You Use

📘 Unreal Engine 4 - IWYU (Include What You Use)

---

🏷 什么是 IWYU？

• IWYU = Include What You Use

• 这是 Epic 在 UE4.15 起引入的头文件依赖管理规范。

• 核心思想：

  👉 只 include 你实际需要用到的头文件，避免不必要的依赖。

---

🔍 为什么需要 IWYU？

1. 减少编译时间
   • 传统 UE4 项目常用 Engine.h / UnrealEngine.h，会导致巨量无用头文件被编译。
   • IWYU 强制精简依赖，只编译所需。
2. 降低耦合度
   • 避免类间不必要的硬依赖，保持模块独立性。
3. 提升可维护性
   • 明确每个类/函数所需的头文件，方便迁移和重构。

---

⚙️ IWYU 的规则

1. 禁止使用大一统头文件
   • ❌ Engine.h
   • ❌ UnrealEngine.h
   • ✅ 改为只 include 必需模块的头文件。
2. 前置声明（Forward Declaration）优先
   • 如果只在 .h 中使用指针/引用 → 用 class XXX; 前置声明即可。
   • 只有需要完整定义时，才 include 对应的头文件。
3. .cpp 中 include 完整定义
   • 如果类成员或函数需要调用方法、访问成员 → 在 .cpp 里 include 头文件。
4. 使用 Minimal.h
   • 在 UE4.15+，推荐 #include "CoreMinimal.h"
   • 包含最常用的类型（FString、TArray、UObject 基础等）。

---

📝 示例

传统写法（未启用 IWYU）

#include "Engine.h"class AMyActor : public AActor
{UPROPERTY()UStaticMeshComponent* Mesh;
};

⚠️ 问题：Engine.h 引入了大量无关的头文件。

---

IWYU 写法（推荐）

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"class UStaticMeshComponent;class AMyActor : public AActor
{UPROPERTY()UStaticMeshComponent* Mesh;
};

✅ 优点：

• .h 文件只前置声明 UStaticMeshComponent。
• .cpp 中再引入完整头文件：

#include "MyActor.h"
#include "Components/StaticMeshComponent.h"

---

📦 常见替换表

旧写法 (废弃)	新写法 (推荐)
#include "Engine.h"	#include "CoreMinimal.h"
#include "UnrealEngine.h"	#include "CoreMinimal.h"
#include "GameFramework/Actor.h"	保留（需要用到 AActor 时）
#include "Engine/World.h"	只在需要 UWorld 时引入

---

🚀 IWYU 的好处

• 编译速度快：减少不必要的 include。
• 模块化清晰：依赖关系一目了然。
• 跨平台友好：降低编译器处理压力。
• 易于维护：减少冗余依赖，避免循环引用问题。

---

📚 参考

• 官方文档：Unreal Engine IWYU Guide
• Epic 论坛讨论：Why IWYU Matters

---