undefined reference는 개별 소스 파일의 컴파일 단계(g++ -c)는 통과했지만, 목적 파일과 라이브러리를 합치는 링크 단계에서 링커(collect2를 통한 /usr/bin/ld)가 선언된 심볼(U)의 실제 정의(T)를 찾지 못할 때 발생하는 C++ 링크 에러입니다. 이 글에서는 2026-10-28(KST)에 g++/gcc (Debian 14.2.0-19) 14.2.0, x86_64, /usr/bin/ld 환경에서 재현한 네 가지 사례와 nm 출력을 바탕으로 원인과 해결 방법을 정리합니다(출력의 +0x5 같은 오프셋 값은 이 실행 환경의 값이며, 임시 목적 파일 경로는 /tmp/ccXXXXXX.o로 표기했습니다).

핵심 요약

undefined reference는 컴파일러가 아니라 링커가 내는 에러로, 함수를 쓰겠다는 선언은 확인했으나 실제 정의(본문)를 링크 대상 어디에서도 찾지 못했다는 뜻입니다. 대표적인 원인은 정의 자체를 작성하지 않았거나, 정의가 담긴 .cpp·라이브러리를 링크 명령에서 빠뜨렸거나, C 함수를 extern "C" 없이 호출했거나, 정적 라이브러리 -l 옵션을 호출하는 목적 파일보다 앞에 둔 경우입니다. nm 및 nm -C로 U(이 파일에 정의 없음)와 T(코드 섹션에 정의됨)를 비교하면 원인을 바로 좁힐 수 있습니다.

undefined reference 에러란 무엇입니까?

한 줄 답: undefined reference는 선언만 보고 넘어간 컴파일 단계(g++ -c) 뒤, 링커(ld)가 실제 함수 정의(T)를 찾지 못해 ld returned 1 exit status와 함께 중단되는 링크 에러입니다.

C++ 분리 컴파일에서는 함수 선언만 있으면 개별 소스 파일을 목적 파일(.o)로 컴파일할 수 있습니다. 하지만 실행 파일을 만들 때 링커가 모든 목적 파일과 라이브러리를 뒤져도 그 함수의 정의를 찾지 못하면 링크 에러가 발생합니다.

아래 c1_main.cpp는 함수 선언만 있고 정의가 없는 코드입니다.

void helper();   // 선언만 있음
int main() { helper(); }

이 파일을 $ g++ c1_main.cpp -o c1 명령으로 실행 파일까지 빌드하면 종료 코드 1(exit=1)로 실패하며 다음 출력이 나옵니다.

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c1_main.cpp:(.text+0x5): undefined reference to `helper()'
collect2: error: ld returned 1 exit status

반면 링크를 생략하고 컴파일만 수행하는 $ g++ -c c1_main.cpp -o c1_main.o 명령은 종료 코드 0(exit=0)으로 성공합니다. 생성된 목적 파일을 $ nm -C c1_main.o로 확인하면 결과는 다음과 같습니다.

                 U helper()
0000000000000000 T main

여기서 T는 이 목적 파일의 텍스트(코드) 섹션에 정의된 심볼을 뜻하고, U는 이 파일에서 참조하지만 정의는 외부에 있어 아직 해결되지 않은 심볼을 뜻합니다. 이는 동일한 함수 정의가 두 번 이상 들어가 충돌하는 C++ multiple definition 에러란? 헤더에 함수를 정의할 때 inline이 필요한 이유(정의 두 번 vs 0번)와 정반대 상황이며, 전처리기·문법 단계에서 발생하는 expected unqualified-id before numeric constant 에러란? 매크로와 이름이 겹칠 때 C++ 해결 방법 같은 컴파일 에러와도 메시지 형태가 다릅니다. 분리 컴파일의 기본 구조는 C++ 분할 컴파일: 헤더 #include 비용과 C++20 모듈 차이 (Tour 3.2)에서도 다룹니다.

링커가 선언된 심볼 U에 대응하는 정의 T를 목적 파일과 라이브러리에서 찾는 과정

정의 파일을 빠뜨리면 어떻게 됩니까?

한 줄 답: 헤더 파일만 #include하고 함수 본문이 담긴 .cpp 파일을 빌드 명령에서 빼먹으면, 컴파일은 통과해도 링커가 정의를 찾지 못합니다.

선언과 정의를 헤더(math.h)와 구현 파일(math.cpp)로 나눈 뒤, 호출하는 쪽(c2_main.cpp)만 빌드 명령에 넣는 경우입니다.

// math.h
#pragma once
int add(int a, int b);
// math.cpp
#include "math.h"
int add(int a, int b) { return a + b; }
// c2_main.cpp
#include "math.h"
#include <cstdio>
int main() { std::printf("add=%d\n", add(2, 3)); }

math.cpp를 빼고 $ g++ c2_main.cpp -o c2를 실행하면 종료 코드 1(exit=1)과 함께 다음 링크 에러가 출력됩니다.

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c2_main.cpp:(.text+0xf): undefined reference to `add(int, int)'
collect2: error: ld returned 1 exit status

구현 파일까지 함께 지정해 $ g++ c2_main.cpp math.cpp -o c2를 실행하면 종료 코드 0(exit=0)으로 링크가 완료되며, $ ./c2 실행 결과는 다음과 같습니다.

add=5

CMake를 사용하는 프로젝트라면 add_executable(또는 라이브러리 타깃)의 소스 파일 목록에 구현 .cpp 파일이 빠지지 않았는지 확인합니다.

C 함수를 부를 때는 왜 생깁니까?

한 줄 답: C++ 컴파일러는 오버로딩 지원을 위해 함수 이름을 맹글링(_Z8c_squarei)하지만 C 컴파일러는 원래 이름(c_square)을 그대로 내보내므로, extern "C"가 없으면 심볼 이름이 어긋납니다.

cppreference의 언어 연결(Language linkage) 문서에 따르면, extern "C"는 C 언어 연결을 지정하여 C++ 이름 맹글링(name mangling)을 적용하지 않고 C로 컴파일된 함수를 C++ 프로그램에서 호출할 수 있게 해 줍니다.

먼저 C 컴파일러(gcc -c csq.c -o csq.o)로 컴파일한 csq.c입니다.

int c_square(int x) { return x * x; }

extern "C" 없이 선언만 적은 csq_noextern.h(int c_square(int x);)를 포함한 c3_main_bad.cpp는 다음과 같습니다.

#include "csq_noextern.h"
#include <cstdio>
int main() { std::printf("sq=%d\n", c_square(4)); }

두 파일을 합치는 $ g++ c3_main_bad.cpp csq.o -o c3bad 명령은 csq.o를 함께 넘겼는데도 종료 코드 1(exit=1)로 실패합니다.

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c3_main_bad.cpp:(.text+0xa): undefined reference to `c_square(int)'
collect2: error: ld returned 1 exit status

각 목적 파일의 심볼 테이블을 nm으로 확인하면 원인이 드러납니다. 먼저 $ nm csq.o 출력입니다.

0000000000000000 T c_square

반면 C++로 컴파일된 c3_main_bad.o를 $ nm c3_main_bad.o로 확인하면 맹글링된 이름을 찾고 있습니다.

                 U _Z8c_squarei
0000000000000000 T main
                 U printf

디맹글링 옵션인 $ nm -C c3_main_bad.o를 주면 사람이 읽는 시그니처로 보입니다.

                 U c_square(int)
0000000000000000 T main
                 U printf

즉 csq.o는 c_square를 제공하고 c3_main_bad.o는 _Z8c_squarei를 찾고 있어 이름이 맞지 않았습니다.

C 컴파일러는 c_square를, C++ 호출 쪽은 _Z8c_squarei를 찾아 심볼 이름이 어긋나는 name mangling

이를 해결하려면 C와 C++ 양쪽에서 포함할 수 있도록 #ifdef __cplusplus와 extern "C" 패턴을 쓴 csq.h를 사용합니다.

#ifdef __cplusplus
extern "C" {
#endif
int c_square(int x);
#ifdef __cplusplus
}
#endif

c3_main_bad.cpp에서 포함 헤더만 #include "csq.h"로 바꾼 c3_main_ok.cpp를 $ g++ c3_main_ok.cpp csq.o -o c3ok로 빌드하면 종료 코드 0(exit=0)으로 성공하며, $ ./c3ok 실행 결과는 다음과 같습니다.

sq=16

라이브러리 순서는 왜 중요합니까?

한 줄 답: 링커는 명령줄에 지정된 순서대로 목적 파일과 라이브러리를 검색·처리하므로, 정적 라이브러리를 참조하는 목적 파일보다 -l 옵션을 뒤에 두어야 합니다.

GCC 공식 문서(Link Options)는 링커가 라이브러리와 목적 파일을 지정된 순서대로 검색하고 처리한다고 설명합니다. 따라서 -lz보다 뒤에 나오는 bar.o가 라이브러리 z의 함수를 참조하면 해당 함수들이 적재되지 않을 수 있으므로, -l 옵션은 이를 참조하는 목적 파일 뒤에 놓아야 합니다.

앞서 작성한 math.cpp를 g++ -c math.cpp -o math.o && ar rcs libmymath.a math.o 명령으로 정적 라이브러리 libmymath.a로 묶은 뒤, -lmymath를 소스 파일보다 앞에 둔 $ g++ -L. -lmymath c2_main.cpp -o c4bad를 실행하면 종료 코드 1(exit=1)로 실패합니다.

/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
c2_main.cpp:(.text+0xf): undefined reference to `add(int, int)'
collect2: error: ld returned 1 exit status

호출하는 c2_main.cpp를 앞에 두고 정적 라이브러리 옵션을 뒤에 배치한 $ g++ c2_main.cpp -L. -lmymath -o c4ok는 종료 코드 0(exit=0)으로 성공하며, $ ./c4ok 실행 시 정상 출력됩니다.

add=5

nm으로 원인을 어떻게 찾습니까?

한 줄 답: 호출하는 목적 파일의 미해결 심볼(U)과 정의가 들어 있어야 할 파일의 정의 심볼(T)을 nm 및 nm -C로 대조하는 3단계 순서로 원인을 찾습니다.

  1. 호출하는 목적 파일에 nm -C를 실행해 링크 에러가 난 심볼이 U(미정의 참조)로 표시되는지 확인합니다.
  2. 정의를 제공해야 하는 목적 파일(.o)이나 정적 라이브러리(.a)에 nm -C를 실행해 같은 이름의 T(텍스트 섹션 정의) 심볼이 있는지 확인합니다.
  3. -C를 뺀 기본 nm에서 한쪽은 C 이름(c_square)이고 다른 쪽은 맹글링된 이름(_Z8c_squarei)이면 헤더에 extern "C"를 추가하고, 아예 T가 없거나 무시되었다면 누락된 소스·라이브러리를 추가하거나 -l 순서를 호출 파일 뒤로 옮깁니다.

자주 묻는 질문은 무엇입니까?

한 줄 답: 함수 템플릿의 분리 작성, 가상 함수 본문 누락, 크로스 컴파일 시 타깃 아키텍처 라이브러리 불일치에서도 undefined reference가 발생할 수 있습니다.

템플릿 함수를 .cpp 파일에 정의하면 왜 링크 에러가 납니까?

템플릿은 호출되는 타입에 맞춰 인스턴스화할 때 컴파일러가 전체 정의를 봐야 하므로, 명시적 인스턴스화(explicit instantiation)를 따로 하지 않는 한 템플릿 정의는 헤더 파일에 두는 것이 원칙입니다.

가상 함수를 선언만 하고 정의하지 않으면 어떻게 됩니까?

순수 가상 함수(= 0)가 아닌 일반 가상 함수의 정의를 빠뜨리면 링커 메시지에 vtable이 보일 수 있습니다. 가상 함수와 소멸자의 동작 원리는 C++ 가상 소멸자란? 부모 포인터로 delete할 때 virtual이 필요한 이유 글에서 확인할 수 있습니다.

크로스 컴파일할 때 라이브러리를 지정했는데도 왜 에러가 납니까?

호스트 아키텍처용 라이브러리나 잘못된 sysroot 경로의 라이브러리를 참조하면 링커가 호환되는 심볼 정의를 찾지 못할 수 있으며, 타깃용 gcc 빌드와 실행 순서는 크로스 컴파일이란? ARM용 gcc로 빌드하고 QEMU에서 실행할 때 순서 글을 참고하시기 바랍니다.

함께 보면 좋은 글은 무엇입니까?

한 줄 답: C++ 링크·컴파일 에러 해결, 가상 소멸자, 크로스 컴파일 및 CMake 설정을 다룬 관련 글입니다.

출처는 어디입니까?

한 줄 답: GCC 링커 옵션 공식 문서와 cppreference의 언어 연결(Language linkage) 문서를 참고했습니다.