Почему шаблоны C++ нужно определять в заголовочном файле, а не в .cpp?

Краткий ответ: шаблоны — это не функции, а "формочки" для создания функций

Проблема, с которой вы столкнулись, — классическая ловушка для новичков в C++. Давайте разберёмся, почему обычный подход с разделением на .h и .cpp не работает для шаблонов.

Как работает компиляция обычных функций

Для обычной функции процесс выглядит так:

• Компилятор видит объявление функции в .h и её вызов в main.cpp. Он генерирует машинный код для этого вызова (инструкцию CALL) и оставляет ссылку на функцию, которую должен найти компоновщик.
• Компилятор math_utils.cpp видит определение функции и компилирует его в машинный код.
• Компоновщик (линкер) соединяет вызов из main.cpp с реализацией из math_utils.obj — всё работает.

Почему шаблоны ломают эту схему

Шаблон template <typename T> T max(T a, T b) — это не функция. Это инструкция компилятору: "Когда увидишь вызов max с конкретным типом, создай для этого типа новую функцию". Компилятор генерирует код для max<int>, max<double> и т.д. на месте использования.

Теперь посмотрим на ваш код:

• main.cpp видит только объявление шаблона. Компилятор пытается сгенерировать max<int> и max<double>, но определения шаблона нет — есть только объявление. Компилятор оставляет "дырку" для компоновщика.
• math_utils.cpp компилируется отдельно. Он содержит определение шаблона, но не содержит ни одного вызова с конкретными типами. Компилятор не знает, какие версии нужно генерировать, поэтому не генерирует никакого машинного кода.
• Компоновщик не находит реализацию max<int> и max<double> — отсюда ошибка "undefined reference".

Решение №1 (рекомендуемое): Определение в заголовочном файле

Самый простой и стандартный способ — поместить определение шаблона прямо в .h файл:

// 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

Теперь каждый .cpp файл, который включает math_utils.h, видит полное определение шаблона и может сгенерировать нужные версии. Да, это нарушает "чистоту" разделения, но это особенность C++ — шаблоны требуют видимости определения в точке использования.

Решение №2: Явное инстанцирование (для больших проектов)

Если вы хотите сохранить .cpp файл, можно явно указать, какие версии шаблона нужно сгенерировать:

// math_utils.cpp
#include "math_utils.h"

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

// Явное инстанцирование для нужных типов
template int max<int>(int, int);
template double max<double>(double, double);

Теперь math_utils.cpp сгенерирует код для int и double. Но минус в том, что вы должны заранее знать все типы, которые будут использоваться. Если кто-то вызовет max(1.0f, 2.0f) (float) — снова получите ошибку.

Решение №3: Сборка с модулями (C++20)

Начиная с C++20, можно использовать модули, которые решают эту проблему более элегантно, но это тема отдельного разговора.

Итог

Помещение определения шаблона в заголовочный файл — это не "костыль", а стандартная практика в C++. Да, это может увеличить время компиляции (из-за повторной генерации одного и того же кода), но для этого есть техники вроде явного инстанцирования или extern template (C++11). Для небольших проектов просто пишите реализацию в .h — это нормально.

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

// Сообщаем: "Не генерируй код для int, я сделаю это в одном месте"
extern template int max<int>(int, int);

// math_utils.cpp
#include "math_utils.h"

// Генерируем код только здесь
template int max<int>(int, int);

template class std::vector<int>; // Явное инстанцирование класса