Ошибка компоновщика «undefined reference» в C++: причины и исправление

Что такое ошибка «undefined reference»?

Ошибка «undefined reference» (или «unresolved external symbol») — это ошибка этапа компоновки (linking). Она возникает, когда компоновщик (ld) не может найти реализацию (определение) функции или переменной, которая была объявлена и используется в коде. В отличие от ошибок компиляции, которые проверяют синтаксис, эта ошибка говорит: «Я знаю, что такая функция существует (ты объявил её), но не вижу её кода, чтобы вставить в исполняемый файл».

Почему это произошло в вашем случае?

Вы скомпилировали только main.cpp командой g++ main.cpp -o program. Компилятор обработал main.cpp, увидел объявление функции add из заголовка, сгенерировал объектный файл с вызовом этой функции, но не включил в сборку файл math_utils.cpp, где находится её определение. Компоновщик не нашёл реализацию — отсюда ошибка.

Как исправить?

Есть несколько способов:

1. Явно указать все .cpp файлы при компиляции

Самый простой способ — передать компилятору все исходные файлы:

g++ main.cpp math_utils.cpp -o program

Компилятор скомпилирует каждый .cpp в объектный файл, а затем скомпонует их вместе.

2. Раздельная компиляция с последующей компоновкой

Профессиональный подход для больших проектов:

g++ -c main.cpp -o main.o      # компиляция main.cpp
g++ -c math_utils.cpp -o math_utils.o  # компиляция math_utils.cpp
g++ main.o math_utils.o -o program     # компоновка

3. Использование Makefile или CMake

Для автоматизации сборки проекта.

Другие частые причины ошибки

• Забыли добавить файл в проект (как в вашем случае).
• Опечатка в имени функции — объявили add, а определили Add. C++ чувствителен к регистру.
• Не подключили библиотеку — например, при использовании математических функций нужно добавить флаг -lm.
• Проблемы с inline-функциями — если функция объявлена как inline в заголовке, но определение находится в .cpp без inline.
• Статические или глобальные переменные — объявлены как extern в заголовке, но не определены нигде.
• Порядок компоновки — в некоторых компиляторах порядок объектных файлов и библиотек важен (библиотеки после файлов, которые их используют).

Как отлаживать?

Используйте флаг -v для подробного вывода или nm для просмотра символов в объектных файлах:

nm main.o | grep add   # показывает, что add — это неопределённый символ (U)
nm math_utils.o | grep add  # показывает, что add определён (T)

Символ U (undefined) в main.o и T (text/code) в math_utils.o — значит, проблема именно в том, что вы не скомпоновали эти файлы вместе.

Заключение

Ошибка «undefined reference» — это нормальная часть процесса разработки на C++. Она просто говорит: «Ты используешь функцию, но не дал мне её код». Всегда проверяйте, все ли исходные файлы участвуют в сборке, и правильно ли написаны имена. После добавления math_utils.cpp в команду компиляции ваша программа соберётся успешно.

CC = g++
CFLAGS = -Wall -std=c++11

program: main.o math_utils.o
    $(CC) main.o math_utils.o -o program

main.o: main.cpp math_utils.h
    $(CC) $(CFLAGS) -c main.cpp

math_utils.o: math_utils.cpp math_utils.h
    $(CC) $(CFLAGS) -c math_utils.cpp

clean:
    rm -f *.o program

g++ main.o -o program -lpthread   # правильно
g++ -lpthread main.o -o program   # может не сработать