Swift中import详解

// lib/ClangImporter/ClangImporter.cpp 第543-547行
// Enable modules.
invocationArgStrs.insert(invocationArgStrs.end(), {
    "-fmodules",
    "-Xclang", "-fmodule-feature", "-Xclang", "swift"
});

framework module MyFramework {
  umbrella header "MyFramework.h"
  export *
  module * { export * }
}

// 当你写：
import Foundation

// 实际上加载了两个模块：
// 1. Foundation (Clang 模块) - 底层 Objective-C 实现
// 2. Swift.Foundation (Swift Overlay) - Swift 扩展和包装

// lib/Sema/ImportResolution.cpp 第549-553行
// 3. 隐式导入底层 Clang 模块（用于 overlay）
if (importInfo.ShouldImportUnderlyingModule) {
  // @_exported self-import
}

import MyObjCFramework  // 通过 module.modulemap 导入

// MyProject-Bridging-Header.h
#import "LegacyObjCClass.h"
#import "CUtilities.h"

// lib/Sema/ImportResolution.cpp 第601-613行
// Implicitly import the bridging header module if needed.
auto bridgingHeaderPath = importInfo.BridgingHeaderPath;
if (!bridgingHeaderPath.empty() &&
    !clangImporter->importBridgingHeader(bridgingHeaderPath, module)) {
  auto *headerModule = clangImporter->getImportedHeaderModule();
  // 将 bridging header 作为一个模块添加到隐式导入中
}

// 需要启用 C++ 互操作
// Build Settings -> C++ and Objective-C Interoperability -> C++ / Objective-C++

import CxxModule  // 导入 C++ 模块

// lib/ClangImporter/ClangImporter.cpp 第549-565行
bool EnableCXXInterop = LangOpts.EnableCXXInterop;
if (LangOpts.EnableObjCInterop) {
  invocationArgStrs.insert(invocationArgStrs.end(), {
    "-x", EnableCXXInterop ? "objective-c++" : "objective-c",
  });
} else {
  invocationArgStrs.insert(invocationArgStrs.end(), {
    "-x", EnableCXXInterop ? "c++" : "c",
  });
}

// FileA.swift (属于 MyApp 模块)
class NetworkManager {  // 默认 internal 访问级别
    func fetchData() { }
}

// FileB.swift (属于 MyApp 模块)
class ViewController {
    let manager = NetworkManager()  // ✅ 直接使用，无需 import
    
    func load() {
        manager.fetchData()  // ✅ 可以访问 internal 方法
    }
}

源文件A.m  →  [预处理: 展开 #import]  →  编译单元A  →  目标文件A.o
源文件B.m  →  [预处理: 展开 #import]  →  编译单元B  →  目标文件B.o
                                                          ↓
                                                      [链接器]
                                                          ↓
                                                      最终二进制

源文件A.swift ─┐
源文件B.swift ─┼→  [Swift 编译器: 整体分析模块]  →  模块产物
源文件C.swift ─┘         ↑
                    所有文件共享命名空间

// Swift 编译器中的访问控制检查（简化示意）
// 如果一个实体的访问级别 >= internal，且查找上下文在同一模块内
// 则该实体对查找上下文可见，无需 import

// lib/Serialization/Serialization.cpp 第7345-7370行
void Serializer::writeToStream(...) {
  Serializer S{SWIFTMODULE_SIGNATURE, DC, options};
  
  S.writeBlockInfoBlock();
  {
    BCBlockRAII moduleBlock(S.Out, MODULE_BLOCK_ID, 2);
    S.writeHeader();
    S.writeInputBlock();
    S.writeSIL(SILMod);  // 写入 SIL（Clang 不需要这个）
    S.writeAST(DC);
    // ...
  }
  S.writeToStream(os);
}

// swift-interface-format-version: 1.0
// swift-compiler-version: Apple Swift version 5.9
// swift-module-flags: -enable-library-evolution -module-name MyModule
import Swift
import Foundation

@frozen public struct Point {
  @_hasStorage public var x: Double { get set }
  @_hasStorage public var y: Double { get set }
  public init(x: Double, y: Double)
}

@inlinable public func distance(from a: Point, to b: Point) -> Double {
  let dx = b.x - a.x
  let dy = b.y - a.y
  return (dx * dx + dy * dy).squareRoot()
}

// docs/Generics/chapters/compilation-model.tex 第507-512行
// Textual interface files use the ".swiftinterface" file name extension.
// They are generated by the AST printer, which prints declarations in a
// format that looks very much like Swift source code, with a few exceptions:
// 1. Non-@inlinable function bodies are skipped
// 2. Synthesized declarations are written out explicitly
// 3. Opaque result types require special handling

// lib/Serialization/Deserialization.cpp
// 声明和类型只在被引用时才反序列化
// 未使用的部分不会占用编译时间

// lib/Frontend/Frontend.cpp 第776-783行（注释）
// 1. ExplicitSwiftModuleLoader: 显式指定的模块路径
// 2. MemoryBufferSerializedModuleLoader: 内存缓冲区加载
// 3. ExplicitCASModuleLoader: CAS 缓存加载
// 4. ModuleInterfaceLoader: .swiftinterface 文件加载
// 5. ImplicitSerializedModuleLoader: 隐式搜索路径加载
// 6. ClangImporter: Clang 模块加载（必须最后）

// lib/Frontend/Frontend.cpp 第781-783行
// ClangImporter: This must come after all the Swift module loaders because
// in the presence of overlays and mixed-source frameworks, we want to prefer
// the overlay or framework module over the underlying Clang module.

// lib/Frontend/CompilerInvocation.cpp 第2439-2455行
std::vector<SearchPathOptions::SearchPath> ImportSearchPaths(...);
for (const Arg *A : Args.filtered(OPT_I, OPT_Isystem)) {
  ImportSearchPaths.push_back(
      {resolveSearchPath(A->getValue()),
       /*isSystem=*/A->getOption().getID() == OPT_Isystem});
}

std::vector<SearchPathOptions::SearchPath> FrameworkSearchPaths(...);
for (const Arg *A : Args.filtered(OPT_F, OPT_Fsystem)) {
  FrameworkSearchPaths.push_back(
      {resolveSearchPath(A->getValue()),
       /*isSystem=*/A->getOption().getID() == OPT_Fsystem});
}

1. 检查是否是 Builtin 模块
2. 检查是否是当前模块自身（用于导入 Clang 子模块）
3. 遍历模块加载器，依次尝试加载
   └── 在每个搜索路径中查找：
       ├── $PATH/SomeModule.swiftmodule/{arch}.swiftmodule
       ├── $PATH/SomeModule.swiftmodule/{arch}.swiftinterface  
       ├── $PATH/SomeModule.swiftmodule
       ├── $PATH/SomeModule.framework/...
       └── 最后尝试 Clang 模块（通过 ClangImporter）

// lib/Serialization/SerializedModuleLoader.cpp 第186-210行
case ModuleSearchPathKind::Import: {
  // Look for:
  // $PATH/{name}.swiftmodule/{arch}.{extension} or
  // $PATH/{name}.{extension}
  forEachDirectoryEntryPath(searchPath, [&](StringRef path) {
    auto pathExt = llvm::sys::path::extension(path);
    if (pathExt != moduleSuffix && pathExt != suffix)
      return;
    // ...
  });
}

SomeFramework.framework/
├── Modules/
│   ├── SomeFramework.swiftmodule/
│   │   ├── arm64-apple-ios.swiftmodule
│   │   ├── arm64-apple-ios.swiftinterface
│   │   └── ...
│   └── module.modulemap  ← Clang 模块定义（如果有 OC 代码）
├── Headers/
│   └── SomeFramework.h
└── SomeFramework (二进制)

// 1. 导入整个模块
import Foundation

// 2. 导入特定类型的声明
import struct Darwin.size_t
import class UIKit.UIViewController

// 3. 导入子模块
import Foundation.NSObject

// 4. 带属性的导入
@testable import MyModule

decl-import:
    'import' attribute-list import-kind? import-path
import-kind:
    'typealias' | 'struct' | 'class' | 'enum' | 'protocol' | 'var' | 'func'
import-path:
    any-identifier ('.' any-identifier)*

// include/swift/AST/Import.h 第47-56行
enum class ImportKind : uint8_t {
  Module = 0,  // 导入整个模块
  Type,        // typealias
  Struct,      // struct
  Class,       // class
  Enum,        // enum
  Protocol,    // protocol
  Var,         // var/let
  Func         // func
};

// 导入整个模块
import Foundation

// 仅导入特定类型
import class Foundation.NSObject
import struct Darwin.size_t
import func Darwin.C.strlen
import protocol Swift.Equatable

// 导入类型别名（会被转换为实际类型的 ImportKind）
import typealias Foundation.TimeInterval  // 实际按 struct 处理（因为 TimeInterval 是 Double）

// 假设 ModuleA 和 ModuleB 都有 Config 类型
import class ModuleA.Config  // 显式导入 ModuleA.Config
import ModuleB

let config = Config()  // 使用 ModuleA.Config（因为显式导入优先级更高）

源码 → [词法分析] → Token 流 → [语法分析/Parser] → AST → [语义分析] → 类型检查的 AST

// lib/Parse/ParseDecl.cpp 第6735-6867行
ParserResult<ImportDecl> Parser::parseDeclImport(ParseDeclOptions Flags,
                                                 DeclAttributes &Attributes) {
  SourceLoc ImportLoc = consumeToken(tok::kw_import);
  
  // 解析 import-kind（可选）
  ImportKind Kind = ImportKind::Module;
  SourceLoc KindLoc;
  if (Tok.isKeyword()) {
    switch (Tok.getKind()) {
    case tok::kw_typealias: Kind = ImportKind::Type; break;
    case tok::kw_struct:    Kind = ImportKind::Struct; break;
    case tok::kw_class:     Kind = ImportKind::Class; break;
    case tok::kw_enum:      Kind = ImportKind::Enum; break;
    case tok::kw_protocol:  Kind = ImportKind::Protocol; break;
    case tok::kw_var:
    case tok::kw_let:       Kind = ImportKind::Var; break;
    case tok::kw_func:      Kind = ImportKind::Func; break;
    // ...
    }
    KindLoc = consumeToken();
  }
  
  // 解析 import-path
  ImportPath::Builder importPath;
  do {
    importPath.push_back(Identifier(), Tok.getLoc());
    parseAnyIdentifier(importPath.back().Item, ...);
    HasNext = consumeIf(tok::period);
  } while (HasNext);
  
  // 创建 ImportDecl
  auto *ID = ImportDecl::create(Context, CurDeclContext, ImportLoc, Kind,
                                KindLoc, importPath.get());
  return ID;
}

// include/swift/AST/Import.h 第63-99行
enum class ImportFlags {
  Exported = 0x1,           // @_exported
  Testable = 0x2,           // @testable
  PrivateImport = 0x4,      // @_private
  ImplementationOnly = 0x8, // @_implementationOnly（已废弃）
  SPIAccessControl = 0x10,  // @_spi
  Preconcurrency = 0x20,    // @preconcurrency
  WeakLinked = 0x40,        // @_weakLinked
  SPIOnly = 0x100           // @_spiOnly
};

// MyModuleTests.swift
@testable import MyModule

func testInternalFunction() {
    // 可以访问 MyModule 中的 internal 声明
    let result = internalHelper()
}

// lib/Sema/ImportResolution.cpp 第676-677行
if (ID->getAttrs().hasAttribute<TestableAttr>())
  import.options |= ImportFlags::Testable;

// MyFramework.swift
@_exported import Foundation  // Foundation 对 MyFramework 的使用者也可见

// Client.swift
import MyFramework
// 无需再 import Foundation，可以直接使用 Foundation 的类型
let date = Date()

public import Foundation      // 公开导入，对模块使用者可见
internal import HelperLib     // 内部导入，仅模块内可见（默认）
fileprivate import SecretLib  // 文件私有导入
private import InternalImpl   // 私有导入

@_implementationOnly import InternalHelper

public struct MyStruct {
    // 错误：不能在公开 API 中使用 @_implementationOnly 导入的类型
    // public var helper: InternalHelper.Type
    
    // 正确：仅在实现中使用
    private var helper: InternalHelper.Type
}

// lib/Sema/ImportResolution.cpp 第924-926行
// Encourage replacing `@_implementationOnly` with `internal import`.
if (!topLevelModule.get()->isNonSwiftModule()) {
  ctx.Diags.diagnose(import.importLoc, diag::implementation_only_deprecated);
}

@preconcurrency import LegacyModule

// LegacyModule 中的类型会被假定为 Sendable
// 相关的并发警告会被降级或抑制

@_spi(Internal) import MyFramework

// 可以访问 MyFramework 中标记为 @_spi(Internal) 的声明

// lib/Sema/ImportResolution.cpp 第299-330行
void swift::performImportResolution(SourceFile &SF) {
  // 如果已经解析过，直接返回
  if (SF.ASTStage == SourceFile::ImportsResolved)
    return;

  ImportResolver resolver(SF);

  // 解析每个 import 声明
  for (auto D : SF.getTopLevelDecls())
    resolver.visit(D);
  for (auto D : SF.getHoistedDecls())
    resolver.visit(D);

  SF.setImports(resolver.getFinishedImports());
  SF.ASTStage = SourceFile::ImportsResolved;
}

// lib/Sema/ImportResolution.cpp 第381-426行
void ImportResolver::bindImport(UnboundImport &&I) {
  // 1. 检查是否是自导入（tautological import）
  if (!I.checkNotTautological(SF)) {
    return;
  }

  // 2. 加载模块
  ModuleDecl *M = getModule(I.import.module.getModulePath());
  if (!I.checkModuleLoaded(M, SF)) {
    return;  // 模块加载失败
  }

  // 3. 处理 @testable 导入
  if (I.import.options.contains(ImportFlags::Testable)) {
    for (auto file: M->getFiles())
      file->loadDependenciesForTestable(diagLoc);
  }

  // 4. 获取顶层模块（处理子模块情况）
  auto topLevelModule = I.getTopLevelModule(M, SF);
  
  // 5. 验证 import 选项
  I.validateOptions(topLevelModule, SF);

  // 6. 添加导入
  addImport(I, M);
  if (topLevelModule && topLevelModule != M) {
    addImport(I, topLevelModule.get());
  }

  // 7. 处理 Cross-import overlays
  crossImport(M, I);
}

// lib/Sema/ImportResolution.cpp 第563-626行
ImplicitImportList ModuleImplicitImportsRequest::evaluate(...) {
  // 1. 隐式导入标准库
  switch (importInfo.StdlibKind) {
  case ImplicitStdlibKind::Stdlib:
    stdlib = ctx.getStdlibModule(/*loadIfAbsent*/ true);
    break;
  // ...
  }
  
  // 2. 隐式导入 Bridging Header 模块
  if (!bridgingHeaderPath.empty()) {
    clangImporter->importBridgingHeader(bridgingHeaderPath, module);
    // ...
  }

  // 3. 隐式导入底层 Clang 模块（用于 overlay）
  if (importInfo.ShouldImportUnderlyingModule) {
    // @_exported self-import
  }
}

import Foundation
import Combine

// 编译器自动导入 _FoundationCombine overlay
// 该 overlay 为 Foundation 类型添加 Combine 相关的扩展
// 例如：URLSession.dataTaskPublisher(for:) 等

// lib/Sema/ImportResolution.cpp 第1487-1510行
void ImportResolver::crossImport(ModuleDecl *M, UnboundImport &I) {
  // 例如：同时导入 Foundation 和 Combine 时
  // 自动导入 _FoundationCombine overlay
  
  for (auto &newImport : newImports) {
    // 查找声明了 cross-import 的模块
    // 如果找到匹配的 bystander 模块，加载 overlay
  }
}

#if canImport(UIKit)
  import UIKit
  typealias PlatformView = UIView
#elseif canImport(AppKit)
  import AppKit
  typealias PlatformView = NSView
#else
  #error("Unsupported platform")
#endif

// ❌ 传统方式：基于平台宏
#if os(iOS)
  import UIKit
#elseif os(macOS)
  import AppKit
#endif

// ✅ 更好：基于模块可用性
#if canImport(UIKit)
  import UIKit
#elseif canImport(AppKit)
  import AppKit
#endif

#if canImport(MyModule, _version: 2.0)
  // MyModule 版本 >= 2.0
#endif

#if canImport(MyModule, _underlyingVersion: 1.5)
  // 底层 Clang 模块版本 >= 1.5
#endif

// lib/ASTGen/Sources/ASTGen/CompilerBuildConfiguration.swift 第55-91行
func canImport(
  importPath: [(TokenSyntax, String)],
  version: CanImportVersion
) throws -> Bool {
  var importPathStr = importPath.map { $0.1 }.joined(separator: ".")
  
  // 调用编译器检查模块是否存在
  return ctx.canImport(
    importPath: bridgedImportPathStr,
    location: ...,
    versionKind: cVersionKind,
    versionComponents: ...
  )
}

import Foundation  // 导入 Foundation 模块（包含 OC 代码）
import MyObjCFramework  // 导入自定义的 OC Framework

let array = NSMutableArray()
let obj = MyObjCClass()

// MyProject-Bridging-Header.h
#import "LegacyObjCClass.h"
#import "InternalHelper.h"

// Swift 代码中无需显式 import，可以直接使用
let legacy = LegacyObjCClass()
let helper = InternalHelper()

// lib/PrintAsClang/PrintAsClang.cpp 第609-651行
bool swift::printAsClangHeader(raw_ostream &os, ModuleDecl *M, ...) {
  // 1. 写入前言（宏保护、pragma 等）
  writePrologue(os, M->getASTContext(), computeMacroGuard(M));
  
  // 2. 写入 C 内容
  printModuleContentsAsC(cModuleContents, imports, *M, ...);
  
  // 3. 写入 Objective-C 内容
  printModuleContentsAsObjC(objcModuleContents, imports, *M, ...);
  
  // 4. 写入 C++ 内容（如果启用）
  // ...
}

// MyModule-Swift.h
#if __has_attribute(external_source_symbol)
# pragma clang attribute push(...)
#endif

SWIFT_CLASS("_TtC8MyModule7MyClass")
@interface MyClass : NSObject
- (nonnull instancetype)init OBJC_DESIGNATED_INITIALIZER;
- (void)doSomething;
@end

#if __has_attribute(external_source_symbol)
# pragma clang attribute pop
#endif

#import "ProjectName-Swift.h"  // 文件名格式：TargetName-Swift.h

MySwiftClass *obj = [[MySwiftClass alloc] init];

@import MyFramework;  // 导入包含 Swift 代码的模块

MySwiftClass *obj = [[MySwiftClass alloc] init];

framework module MyFramework {
    umbrella header "MyFramework.h"
    export *
    module * { export * }
}

module MyFramework.Swift {
    header "MyFramework-Swift.h"
    requires objc
}

// ✅ 可以被 OC 调用
class MyClass: NSObject {
    @objc func doSomething() { }
}

// ✅ 可以被 OC 调用（@objc 隐式继承）
@objc class AnotherClass: NSObject {
    func anotherMethod() { }  // 自动 @objc
}

// ❌ 不能被 OC 调用
struct MyStruct { }

// PodA 中的 Swift 代码

// ❌ 错误：不能导入自己所在的模块
// import PodA

// ✅ 正确：通过 Bridging Header 或 module.modulemap 访问同模块的 OC 代码
// OC 类型自动可见，无需显式 import
let obj = MyObjCClass()

// PodA 中的 OC 代码

// ✅ 正确：使用生成的头文件（不走模块系统）
#import "PodA-Swift.h"

// ❌ 错误：不能导入自己所在的模块
// @import PodA;