Почему шаблоны C++ нужно реализовывать в заголовочных файлах? Ошибка undefined reference

Причина ошибки: как работает компиляция шаблонов

Проблема в том, что шаблоны — это не обычные функции. Обычная функция компилируется один раз и помещается в объектный файл (.o). Когда линковщик видит вызов этой функции, он просто находит её адрес. С шаблонами всё иначе: шаблон — это инструкция для генерации кода, а не сам код. Компилятор не создаёт реализацию функции max<int>, пока не увидит её конкретное использование с типом int.

Разберём процесс пошагово:

1. Компиляция math_utils.cpp: компилятор видит определение шаблона template <typename T> T max(T a, T b). Он проверяет синтаксис, но не генерирует никакого машинного кода, потому что не знает, с каким типом T будет вызвана функция. Файл math_utils.o получается пустым в плане реализации max.
2. Компиляция main.cpp: компилятор видит вызов max(5, 10) и понимает, что нужна функция max<int>. Но в этом файле есть только объявление шаблона (из заголовка). Компилятор помечает вызов как "нужно будет найти реализацию позже" и генерирует ссылку на max<int> в main.o.
3. Линковка: линковщик пытается соединить main.o и math_utils.o. В main.o есть запрос на max<int>, но в math_utils.o эта функция никогда не была создана. Отсюда ошибка undefined reference.

Почему это работает с обычными функциями?

С обычной функцией int max_int(int a, int b) компилятор видит её реализацию в math_utils.cpp и сразу создаёт машинный код. Линковщик находит его без проблем. Шаблоны же — это "чертёж", а не готовая деталь.

Правильное решение: реализация в заголовочном файле

Самый простой и правильный способ — перенести реализацию шаблона в заголовочный файл:

// math_utils.h
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

template <typename T>
T max(T a, T b) {
    return (a > b) ? a : b;
}

#endif

Теперь при компиляции main.cpp компилятор увидит и объявление, и реализацию шаблона. Когда он встретит max(5, 10), он на месте сгенерирует функцию max<int> и поместит её в main.o. Файл math_utils.cpp больше не нужен.

Альтернативные подходы (менее удобные)

• Явное инстанцирование: можно в math_utils.cpp вручную указать, для каких типов генерировать код:

  // math_utils.cpp
  #include "math_utils.h"
  
  template <typename T>
  T max(T a, T b) { ... }
  
  // Явное инстанцирование
  template int max<int>(int, int);
  template double max<double>(double, double);
  

  Недостаток: нужно перечислять все используемые типы, и пользователи вашей библиотеки не смогут использовать шаблон с новыми типами без изменения вашего кода.
• Инклюд-файлы: можно вынести реализацию в отдельный файл .tpp или .inl и включить его в конце заголовка:

  // math_utils.h
  #include "math_utils.tpp"  // в конце файла
  

  Это чисто организационный трюк — технически код всё равно оказывается в заголовке.

Важное замечание

Несмотря на то, что код шаблона находится в заголовочном файле, он не нарушает правило одного определения (ODR), если все реализации шаблона идентичны. Компилятор помечает сгенерированные функции как inline (неявно), и линковщик умеет выбрасывать дубликаты.