Public/Private/Classes: почему граница модуля — не конвенция, а компилятор

Ты уже видел папки Public и Private внутри почти каждого модуля движка и, скорее всего, решил, что это просто договорённость команды — «сюда кладём то, чем можно делиться, сюда — внутреннее». Это не догадка, а буквальная механика: UnrealBuildTool физически не добавляет содержимое Private в список путей, которые видит компилятор при сборке любого другого модуля. Не «не принято» — «невозможно» штатным способом.

01Что это?

Каждый модуль движка (Engine, CoreUObject, Renderer, твой собственный игровой модуль) физически разложен по каталогам Source/<Модуль>/Public, Source/<Модуль>/Private и, в части старых модулей, ещё и Source/<Модуль>/Classes.

Это не архивная организация файлов «для порядка» — это буквальный вход в алгоритм UnrealBuildTool (UBT), который при сборке любого модуля решает, из каких физических каталогов компилятору вообще разрешено брать заголовки по #include. Дальше — почему это устроено именно так, а не как «просто договорились».

02Почему это существует?

Проблема

Представь модуль Renderer — он рисует кадр: обходит сцену, строит списки отрисовки, работает с GPU-командами. Внутри у него наверняка есть заголовок вроде SceneRendering.h, где описан класс FSceneRenderer с полями и методами, знать о которых снаружи модуля незачем — это внутренняя кухня конкретно этой реализации рендера.

Причина

Если бы любой заголовок любого транзитивно связанного модуля был доступен отовсюду, у Epic не осталось бы способа поменять внутреннее устройство FSceneRenderer между версиями движка, не сломав при этом непредсказуемое число сторонних проектов, которые случайно (или намеренно) утянули этот заголовок к себе. Модуль перестал бы быть модулем в инженерном смысле — единицей, которую можно менять изнутри, не трогая контракт снаружи — и превратился бы в один плоский набор из тысяч заголовков без реальных границ.

03Какую проблему решает

Деление на Public/Private превращает «пожалуйста, не включай это» в физическое ограничение уровня компилятора: заголовок, лежащий в Private, банально не резолвится через #include из другого модуля обычным, штатным способом сборки — не потому что кто-то запретил, а потому что компилятору неоткуда узнать, где его искать.

04Как устроено

Ограничения, которым должно было удовлетворить решение

Механизм должен был не требовать от разработчика ничего сверх привычной работы с файлами (никаких специальных атрибутов доступа, которых в C++ на уровне заголовков просто не существует), работать одинаково для всех модулей движка и любого стороннего плагина без исключений, и не создавать накладных расходов в рантайме — вся эта граница обязана существовать только на этапе сборки, не в скомпилированном бинарнике.

Решение: include-пути формируются по каталогам, а не по правам доступа

У C++ нет встроенного понятия «модуль» с контролем видимости заголовков (собственно модули C++20 — отдельная, недавняя фича языка, и Unreal Build Tool строился независимо от неё, на уровне препроцессора). Значит границу пришлось построить не языковыми средствами, а средствами системы сборки: какие каталоги физически передаются компилятору как -I (пути поиска заголовков) при сборке конкретного модуля.

Вот что реально происходит внутри UnrealBuildTool (UEBuildModuleCPP.cs) при формировании путей для модуля:

Для КАЖДОГО модуля, который собирается в проекте:

  Source/МойМодуль/Classes/**  ─┐
  Source/МойМодуль/Public/**   ─┼─► добавляются в PublicIncludePaths
                                 │    ЭТОТ модуль публикует эти пути
                                 │    ВСЕМ, кто на него зависит
                                 │
  Source/МойМодуль/Private/**  ─┴─► добавляются ТОЛЬКО в собственные
                                     include-пути компиляции файлов
                                     самого МойМодуль — наружу не публикуются

Другой модуль, зависящий от МойМодуль через Build.cs:
  получает в свой -I список ТОЛЬКО PublicIncludePaths модуля МойМодуль
  (Public + Classes) — Private физически отсутствует в списке путей
  поиска заголовков при его собственной сборке

// Add the 'classes' directory, if it exists
if (ModuleDir.TryGetDirectory("Classes", out DirectoryItem? ClassesDirectory) && ClassesDirectory.ContainsFiles(SearchOption.AllDirectories))
{
    PublicIncludePaths.Add(ClassesDirectory.Location);
}

// Add all the public directories
if (ModuleDir.TryGetDirectory("Public", out DirectoryItem? PublicDirectory) && PublicDirectory.ContainsFiles(SearchOption.AllDirectories))
{
    PublicIncludePaths.Add(PublicDirectory.Location);
    /* ... */
}

Симметрично для Private: в том же файле каталог добавляется в список путей, которые видит только компиляция файлов внутри самого модуля — не в тот список, который передаётся модулям-потребителям.

Второй уровень границы: зависимость модуля вообще должна быть объявлена

Публичность заголовка — необходимое, но не единственное условие. Даже полностью публичный заголовок другого модуля не резолвится через #include, пока твой модуль не объявил зависимость от него в .Build.cs — через PublicDependencyModuleNames или PrivateDependencyModuleNames.

public class MyGame : ModuleRules
{
    public MyGame(ReadOnlyTargetRules Target) : base(Target)
    {
        PublicDependencyModuleNames.AddRange(new string[] {
            "Core", "CoreUObject", "Engine", "InputCore"
        });
    }
}

Именно эта строка — причина, по которой в твоём игровом модуле работает #include «GameFramework/Actor.h»: Actor.h лежит в Engine/Classes, каталог Classes публикуется модулем Engine как часть PublicIncludePaths, а твой модуль явно объявил зависимость от Engine. Три условия сошлись одновременно — не одно из них.

Отсюда ответ на исходный пример про Renderer: даже если бы конкретный внутренний заголовок каким-то образом оказался физически в каталоге Public модуля Renderer — что Epic там не делает намеренно, ровно ради этой границы, — твой игровой модуль всё равно не смог бы его подключить без явной зависимости на Renderer в собственном Build.cs, а такая зависимость для геймплейного кода практически никогда не имеет смысла и не встречается в шаблонных проектах.

Public vs Private зависимость модуля — не только про заголовки, но и про то, что видят твои потребители

Разница между PublicDependencyModuleNames и PrivateDependencyModuleNames — не «то же самое, но для модулей вместо файлов», а прямое продолжение той же идеи на уровень выше: если модуль А объявляет зависимость от B как публичную, то любой модуль C, зависящий от А, автоматически получает доступ и к публичным заголовкам B — зависимость протекает наружу. Если А объявляет зависимость от B как приватную, C ничего не узнает о существовании B — А использовал B у себя внутри, но не обязан «одалживать» эту связь всем, кто зависит от А.

05Когда важно об этом думать — и когда нет

Как этим можно злоупотребить

Физическая граница UBT — не криптографическая защита: ничто не мешает разработчику вручную дописать в Build.cs путь до чужого Private-каталога через PrivateIncludePaths.Add(...) с абсолютным или относительным путём и подключить внутренний заголовок другого модуля силой. Это компилируется. Это же и есть злоупотребление: такой код молча ломается при следующем обновлении движка, потому что автор внутреннего заголовка юридически (по соглашению об API) не обязан сохранять обратную совместимость для кода, которого «не должно было туда добраться» — а он туда добрался.

06Типичные ошибки

07Практика

08Частые вопросы

09Что читатель должен начать замечать

Ошибка компилятора «cannot open include file» перестаёт восприниматься как «где-то опечатка в пути» и начинает читаться как конкретный, диагностируемый вопрос: заголовок вообще публичный, или он в Private? Модуль, где он лежит, вообще объявлен зависимостью в Build.cs?

Открывая любой Build.cs — свой или чужой — ты начинаешь видеть не список имён через запятую, а карту того, что этому модулю физически разрешено включать, и что он, в свою очередь, разрешает включать своим потребителям.

Путь до заголовка (Classes/, Public/, Private/) в чужом коде движка начинает нести информацию сам по себе — ты знаешь, что он означает, ещё до того, как открыл файл.

10Итоги

• ✔ объяснить, почему деление на Public/Private — ограничение UnrealBuildTool, а не просто договорённость команды
• ✔ назвать три условия, которые должны совпасть, чтобы #include из другого модуля скомпилировался
• ✔ объяснить разницу между PublicDependencyModuleNames и PrivateDependencyModuleNames через то, что «протекает» дальше по графу зависимостей
• ✔ решить, в какой каталог (Public/Private) положить новый заголовок собственного модуля
• ✔ по ошибке компилятора «cannot open include file» понять, чего именно не хватает — зависимости в Build.cs или самого факта публичности заголовка
• ✔ объяснить, почему принудительное подключение чужого Private-заголовка компилируется, но остаётся нарушением контракта