[Flutter] Error (Xcode): Undefined symbol - iOS 빌드 시 링커 에러 해결

문제 상황

Flutter iOS 빌드 중 다음과 같은 링커 에러가 발생했습니다:

Error (Xcode): Undefined symbol: _GULIsLoggableLevel
Error (Xcode): Undefined symbol: _GULOSLogBasic
Error (Xcode): Undefined symbol: _GULOSLogError
Error (Xcode): Undefined symbol: _GULOSLogInfo
Error (Xcode): Undefined symbol: _GULOSLogWarning
Error (Xcode): Undefined symbol: _GULSetLoggerLevel
Error (Xcode): Undefined symbol: *OBJC*CLASS_$_GULAppDelegateSwizzler
...

Undefined Symbol 에러란?

링커 단계에서 발생하는 이 에러는 컴파일된 코드가 참조하는 심볼(함수, 클래스, 변수 등)을 찾지 못할 때 발생합니다. 이 경우는 Google Utilities Library(GUL) 관련 심볼들을 찾지 못해 발생한 문제입니다.

원인 분석

1. 라이브러리 링킹 실패
2. 빌드 설정의 부적절한 구성
3. Framework 검색 경로 문제
4. Swift 표준 라이브러리 포함 설정 문제

해결 과정

1. Framework 검색 경로 확인

Xcode에서 Framework 검색 경로가 올바르게 설정되어 있는지 확인:

• Build Settings > Framework Search Paths
• Pod 설치 경로가 올바르게 포함되어 있는지 확인

2. 링커 플래그 설정

OTHER_LDFLAGS에 필요한 플래그들이 포함되어 있는지 확인:

Build Settings > Other Linker Flags > $(inherited)

3. Swift 표준 라이브러리 설정

ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES 설정 확인:

Build Settings > Always Embed Swift Standard Libraries > $(inherited)

4. 최종 해결: Xcode 빌드 설정 수정

1. Xcode에서 Runner.xcworkspace 열기
2. Runner 프로젝트의 Runner 타겟 선택
3. Build Settings 탭에서:

   ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES = $(inherited)
   OTHER_LDFLAGS = $(inherited)

   모든 빌드 구성(Debug, Release, Profile)에 대해 적용

기술적 이해

$(inherited) 설정의 중요성

• $(inherited)는 상위 설정(예: CocoaPods 설정)의 값을 상속받도록 지정
• 이 설정이 없으면 필수적인 링커 플래그나 프레임워크 설정이 무시될 수 있음
• 특히 CocoaPods를 사용할 때 중요한 설정

링커 작동 방식

1. 컴파일러가 소스 코드를 목적 파일로 변환
2. 링커가 목적 파일들을 하나의 실행 파일로 결합
3. 이 과정에서 모든 심볼 참조가 해결되어야 함
4. 해결되지 않은 심볼이 있으면 Undefined Symbol 에러 발생

Framework 검색 과정

1. 링커는 지정된 Framework 검색 경로를 순서대로 검색
2. 필요한 심볼이 포함된 Framework를 찾으면 링킹
3. 검색 경로에서 필요한 Framework를 찾지 못하면 에러 발생

참고 자료

• Xcode Build System Guide
• Link-Time Issues
• Working with Frameworks and Weak Linking