링커가 심볼을 찾는 순서는 어떻게 되나요?

구현·버전마다 다르지만, 일반적으로 명령줄에 나온 오브젝트·아카이브 순서와 검색 경로를 따라 미해결 참조를 채웁니다. 정적 라이브러리(.a)는 흔히 왼쪽에서 오른쪽으로 한 번 스캔하며 필요한 .o만 끌어옵니다.

약한 심볼(weak)은 언제 쓰이나요?

동일 이름에 기본 구현을 제공하고, 다른 단위에서 강한 정의로 덮어쓸 수 있게 할 때입니다. 예: 컴파일러가 생성한 약한 심볼, 또는 GNU 확장 __attribute__((weak)).

SIOF는 링커 에러로 잡히나요?

대부분 링크 오류가 아니라 런타임 미정의 동작입니다. 전역·정적 객체 초기화 순서가 번역 단위 간에 보장되지 않아 생깁니다.

duplicate symbol과 multiple definition은 같은가요?

메시지 표현만 다르고, 흔히 동일 계열입니다. 동일 링커 가시 심볼이 둘 이상의 입력에 강하게 정의되어 충돌할 때 납니다.

[2026] C++ 링커 에러 심화 가이드 — 심볼 해석·약한 심볼·SIOF·중복 진단

2026년 4월 7일 · 26분 읽기 · 수정 2026년 4월 7일 중급 튜토리얼

이 글의 핵심

컴파일은 되는데 링크에서 터질 때, 링커가 오브젝트와 라이브러리를 어떻게 합치는지 이해하면 원인 추적이 빨라집니다. 심볼 해석, 약/강 심볼, SIOF, 중복 정의, 프로덕션 진단까지 정리합니다.

들어가며

C++ 빌드에서 컴파일은 성공하고 링크에서만 실패하는 경우는, 소스가 “문법적으로” 맞아도 오브젝트 파일·라이브러리를 합치는 규칙(심볼 해석, ODR, 링크 순서)을 어겼을 때 발생합니다. 이 글은 “에러 메시지 읽는 법”을 넘어, 링커가 입력을 어떻게 보는지와 실무·운영에서 쓰는 진단 절차에 초점을 둡니다.

다루는 내용:

심볼 해석(symbol resolution) 과정의 개념적 단계
약한 심볼(weak) 과 강한 심볼(strong) 의 차이와 전형적 용도
Static Initialization Order Fiasco(SIOF) — 링크와의 관계 포함
중복 심볼(duplicate / multiple definition) 진단 방법
프로덕션 환경에서의 링커 트러블슈팅

전제: ELF/Linux·macOS의 ld.lld/ld 또는 Windows의 link.exe 같은 전통적인 링커 모델을 기준으로 설명합니다. 플랫폼마다 옵션 이름과 메시지는 다르지만, “미해결 참조를 채우고, 충돌을 거부한다”는 흐름은 동일합니다.

1. 심볼 해석(symbol resolution) 과정

1.1 링커의 입력과 산출

컴파일러는 각 번역 단위(보통 .cpp 하나)를 재배치 가능 오브젝트(.o/.obj)로 만듭니다. 이 안에는 정의(definition) 와 참조(reference) 가 심볼 테이블과 재배치(relocation) 정보로 기록됩니다.

링커의 역할을 단순화하면 다음과 같습니다.

모든 입력 오브젝트(직접 컴파일한 것 + 정적 라이브러리에서 뽑힌 멤버)를 하나의 이미지로 합친다.
각 정의는 전역 가시 심볼 이름(필요 시 이름 장식(mangling) 된 이름)으로 식별된다.
각 미해결 참조(예: 다른 .cpp에 있는 함수 호출)는, 이름이 일치하는 정의를 찾아 주소를 채운다(재배치 적용).
정의를 찾지 못하면 undefined reference / unresolved external symbol 이 난다.
같은 이름에 서로 다른 강한 정의가 있으면 multiple definition / duplicate symbol 이 난다.

즉, 링커는 “이름으로 매칭하는 글로벌 해석기”이며, C++ 언어 규칙(ODR)과 겹쳐서 동작합니다.

1.2 정적 라이브러리(.a/.lib)와 “한 번 스캔”

정적 아카이브는 여러 .o를 묶은 파일입니다. 흔한 동작은 다음과 같습니다.

링커가 아카이브를 만나면, 현재까지 미해결인 심볼을 만족시키는 멤버 .o만 당겨온다.
이미 당겨온 .o 안의 추가 미해결 심볼은 같은 패스에서 계속 채우려 한다.
뒤에 나온 오브젝트·라이브러리만이 앞쪽 참조를 해결할 수 있다는 점에서, 명령줄 순서가 중요해진다. 예: main.o가 libfoo.a에 있는 심볼을 필요로 하면, libfoo.a는 그 참조가 이미 기록된 뒤에 와야 할 수 있다(구현·모드에 따라 --start-group 등으로 완화).

반면 공유 라이브러리(-lfoo, .so/.dylib)는 로더 시점에 해석되는 부분이 있지만, 링크 시점에도 “필요한 공유 객체를 기록하고 미해결을 줄이는” 과정이 이어집니다.

1.3 재배치(relocation)와 “왜 링크가 느린가”

심볼이 확정되면 링커는 코드·데이터 섹션 안의 상대/절대 주소 자리를 채웁니다. 대규모 바이너리에서는 이 작업과 링커 최적화(예: --gc-sections, LTO)가 빌드 시간에 큰 비중을 차지합니다. 프로덕션에서는 “같은 에러인데 링크만 10분” 같은 현상이 여기서 비롱되기도 합니다.

2. 약한 심볼(weak) vs 강한 심볼(strong)

2.1 강한 심볼

강한(strong) 정의는 링커가 “이 이름의 주인”으로 인정하는 일반적인 전역 정의입니다. 같은 링크 단위에서 다른 강한 정의와 이름이 겹치면 충돌입니다.

2.2 약한 심볼

약한(weak) 심볼은 “없어도 되고, 있으면 쓰인다”에 가깝습니다. 여러 약한 정의가 있어도 하나로 합쳐지거나, 강한 정의가 있으면 그쪽이 이깁니다(툴체인·대상 파일 형식에 따름).

전형적 용도:

기본 구현 제공: 라이브러리가 weak로 기본 핸들러를 두고, 애플리케이션이 강한 심볼로 교체
선택적 기능: 특정 객체 파일을 링크했을 때만 심볼이 강해지는 패턴
컴파일러/런타임이 생성하는 보조 심볼 일부

GNU 계열 예시(리눅스·임베디드에서 종종 사용):

// weak_default.cpp
extern "C" __attribute__((weak)) void platform_init() {
    // 기본은 아무 것도 안 함
}

애플리케이션에서 같은 시그니처로 강한 정의를 제공하면, 링커는 그 정의를 사용합니다.

2.3 디버깅 시 주의점

약한 심볼 때문에 “내가 정의한 함수가 호출되지 않는다”는 착시가 날 수 있습니다. 이름·링키지(extern "C" 여부)·호출 규약이 조금만 달라도 다른 심볼이 되어, 의도한 “덮어쓰기”가 실패합니다. nm, objdump -t, llvm-nm 등으로 실제 심볼 문자열을 확인하는 것이 안전합니다.

3. Static Initialization Order Fiasco(SIOF)

3.1 문제의 본질

SIOF는 서로 다른 번역 단위에 있는 정적·전역 객체의 초기화 순서가 언어 표준상 서로에 대해 거의 보장되지 않는다는 사실에서 옵니다. 한 객체의 생성자가 다른 번역 단위의 정적 객체를 사용하면, 아직 초기화되지 않은 상태를 읽을 수 있습니다.

이것은 대개 링크 에러가 아니라 런타임 버그입니다. 다만 다음과 같이 링크·배포 단계와 엮입니다.

초기화 순서가 바뀐 것처럼 보이는 휴리스틱은 링커 입력 순서·링크 타임 최적화(LTO)·동적 로딩 순서에 민감할 수 있다.
동일 소스인데 빌드 설정·라이브러리 순서만 바꿨는데 크래시가 난다면 SIOF를 의심합니다.

3.2 나쁜 예

// a.cpp
struct Registry { void add(int); };
Registry& g_registry(); // 어딘가에 정의

struct A {
    A() { g_registry().add(1); } // 다른 TU의 정적 객체에 의존
};
A a;

// b.cpp
Registry& g_registry() {
    static Registry r; // 초기화 시점이 A와 비교 불가
    return r;
}

A의 생성자가 g_registry()의 내부 정적 객체보다 먼저 실행되면 미정의 동작입니다.

3.3 실무 대응

정적 지역 변수(함수 안 static)로 첫 호출 시 초기화를 쓰면, 의존을 함수 호출 순서로 줄일 수 있습니다(여전히 설계는 신중해야 함).
Construct On First Use idiom, std::call_once, 의존성 주입으로 전역 상태 제거.
테스트에서 다른 .cpp 링크 순서를 바꿔 재현되는지 확인.

4. 중복 심볼(duplicate symbol) 진단

4.1 링커가 보고하는 것

multiple definition of 'foo' / duplicate symbol _foo 류 메시지는, 동일한 링커 가시 이름에 둘 이상의 강한 정의가 있다는 뜻입니다. C++에서는 네임스페이스·오버로드·템플릿 때문에 장식된 이름으로 확인하는 것이 빠릅니다.

4.2 단계별 진단

에러에 나온 오브젝트/아카이브를 확인합니다. main.o, other.o, libbar.a(bar.o) 등 어느 입력이 충돌하는지가 힌트입니다.
nm -C(또는 llvm-nm -C)로 해당 .o에서 심볼 목록을 봅니다. T(코드), D/B(데이터) 등 여러 파일에 동일 정의가 있는지 확인합니다.
헤더에 구현을 둔 함수가 inline/템플릿/ODR 예외가 아닌지 확인합니다. 헤더에 둔 자유 함수는 거의 항상 중복입니다.
같은 이름의 C 심볼이 extern "C" 블록 밖·안에서 중복되지 않았는지 확인합니다.
정적 라이브러리에 실수로 같은 .o가 두 번 들어간 경우, 또는 동일 소스가 두 번 컴파일되어 서로 다른 경로로 링크되는 경우를 봅니다.

4.3 ODR과의 관계

ODR은 “프로그램 전체에 하나의 정의”를 요구합니다. 헤더에 인라인이 아닌 정의를 넣으면 번역 단위마다 정의가 생기고, 링커는 이를 강한 충돌로 잡습니다. 반면 inline 함수, 템플릿, constexpr 함수 등은 규칙적으로 여러 번역 단위에 동일 정의를 허용합니다(세부는 표준 규칙 따름).

자세한 패턴은 C++ multiple definition 에러 글과 함께 보는 것이 좋습니다.

5. 프로덕션 linker 트러블슈팅

5.1 재현성과 환경 고정

컴파일러·링커·표준 라이브러리 버전을 CI와 동일하게 맞춥니다. “로컬만 된다”는 경우 링커 스크립트·rpath·SDK 경로 차이가 흔합니다.
링크 커맨드를 파일로 저장(compile_commands.json, 링크 응답 파일)하여 이슈 티켓에 첨부합니다.

5.2 정적 vs 동적, 그리고 `-Wl,--as-needed` 류

리눅스에서 불필요한 .so 의존성이 붙거나 반대로 필요한 심볼이 공유 객체에 있는데 링크 순서가 어긋나 미해결이 나는 경우가 있습니다. ldd, readelf -d, nm -D로 실제 의존성을 확인합니다.

5.3 LTO(Link Time Optimization)와 디버깅

LTO를 켜면 진단 메시지가 중간 표현 기준으로 보일 수 있고, 심볼이 병합·제거되어 스택 트레이스가 어색해질 수 있습니다. 링크 실패 원인이 LTO인지 확인하려면 일시적으로 LTO를 끄고 같은 입력으로 재현하는지 봅니다.

5.4 Windows와 MSVC 계열

LNK2005, LNK1169 등은 동일한 심볼에 여러 정의입니다. 런타임 라이브러리(/MD, /MT, /MDd, /MTd)가 프로젝트마다 섞이면 링크 단계에서 이상한 중복·충돌이 납니다. 전 프로젝트 동일 설정이 원칙입니다.

5.5 마지막 수단: 링커 맵 파일

‑Wl,-Map=output.map(GNU) 등으로 어떤 오브젝트가 어떤 섹션에 기여했는지 추적합니다. 중복 정의가 어느 라이브러리에서 왔는지 숨겨진 경우에 특히 유용합니다.

내부 동작과 핵심 메커니즘

이 글의 주제는 「[2026] C++ 링커 에러 심화 가이드 — 심볼 해석·약한 심볼·SIOF·중복 진단」입니다. 여기서는 앞선 설명을 구현·런타임 관점에서 한 번 더 압축합니다. 시스템·런타임 경계(스케줄링, I/O, 메모리, 동시성)를 기준으로 생각하면, “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)이 어디서 터지는가”가 한눈에 드러납니다.

처리 파이프라인(개념도)

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

알고리즘·프로토콜 관점에서의 체크포인트

불변 조건(Invariant): 각 단계가 만족해야 하는 조건(예: 버퍼 경계, 프로토콜 상태, 트랜잭션 격리)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 동일 입력에 동일 출력이 보장되는 순수한 층과, 시간·네트워크에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합처럼 “한 번의 호출이 아니라 누적되는 비용”을 의심 목록에 넣습니다.

프로덕션 운영 패턴

실서비스에서는 기능 구현과 함께 관측·배포·보안·비용이 동시에 요구됩니다. 아래는 팀에서 자주 쓰는 최소 체크리스트입니다.

영역	운영 관점에서의 질문
관측성	요청 단위 상관 ID, 에러율/지연 분위수, 주요 의존성 타임아웃이 보이는가
안전성	입력 검증·권한·비밀 관리가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등한 연산에만 적용되는가, 서킷 브레이커·백오프가 있는가
성능	캐시 계층·배치 크기·풀링·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리, 마이그레이션 호환성이 문서화되어 있는가

운영 환경에서는 “개발자 PC에서는 재현되지 않던 문제”가 시간·부하·데이터 크기 때문에 드러납니다. 따라서 스테이징의 데이터 양·네트워크 지연을 가능한 한 현실에 가깝게 맞추는 것이 중요합니다.

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스 컨디션, 타임아웃, 외부 의존성 불안정	최소 재현 스크립트 작성, 분산 트레이스·로그 상관관계 확인
성능 저하	N+1 쿼리, 동기 I/O, 잠금 경합, 과도한 직렬화	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 클로저/이벤트 구독 누수, 대용량 객체의 불필요한 복사	상한·TTL·스냅샷 비교(힙 덤프/트레이스)
빌드·배포만 실패	환경 변수·권한·플랫폼 차이	CI 로그와 로컬 `diff`, 컨테이너/런타임 버전 핀(pin)

권장 디버깅 순서: (1) 최소 재현 만들기 (2) 최근 변경 범위 좁히기 (3) 의존성·환경 변수 차이 확인 (4) 관측 데이터로 가설 검증 (5) 수정 후 회귀·부하 테스트.

정리

링커는 심볼 이름으로 미해결 참조를 채우고, 강한 정의 충돌을 거부합니다.
정적 아카이브는 필요한 멤버만 당기므로 명령줄 순서가 실무 이슈가 됩니다.
약한 심볼은 확장 기능·기본 구현 패턴에 쓰이지만, 이름·링키지 불일치 시 “조용히 엉뚱한 구현”이 연결될 수 있습니다.
SIOF는 전역 정적 초기화 순서 문제로, 링크 순서 변경으로 간헐 재현될 수 있는 런타임 결함입니다.
중복 심볼은 nm/맵 파일로 어느 .o가 주범인지를 밝히고, ODR·헤더 설계를 수정합니다.

더 기초적인 미해결 외부 심볼(LNK2019 등) 은 C++ LNK2019 가이드, 빌드 파이프라인 전체는 컴파일 과정 글을 참고하시기 바랍니다.