Unreal Engine 4 режим IWYU (для тех кто на C++)⁠⁠

Include-What-You-Use (IWYU), означает, что исходный код движка включает в себя только те зависимости, которые ему необходимы для компиляции. Цель IWYU состоит в том, чтобы избежать включения монолитных заголовочных файлов, таких как Engine.h или UnrealEd.h, тем самым уменьшая лишние зависимости. Следующее справочное руководство расскажет вам, что это значит для IWYU, включая объяснение того, как включить IWYU для вашего проекта. Кроме того, если вы решите использовать режим IWYU для своих игровых проектов, вы узнаете несколько общих советов, которые помогут вам получить максимальную отдачу от работы в режиме IWYU.

Режим IWYU по умолчанию отключен для игр и игровых плагинов; однако режим IWYU по умолчанию включен для модулей Engine и Engine.

В предыдущих версиях Unreal Engine 4 (UE4) большинство функциональных возможностей движка было включено через большие, ориентированные на модули заголовочные файлы, такие как Engine.h и UnrealEd.h и быстрое время компиляции зависело от того, какие файлы быстро компилируются с помощью Precompiled Header (PCH).

С IWYU каждый файл включает в себя только то, что ему нужно, а любой файл PCH, который мы выбираем для использования, действует как слой оптимизации поверх базовых исходных файлов. Их можно изменить, чтобы уменьшить время сборки, независимо от изменения самих исходных файлов и без влияния на то, успешно ли компилируется код.

При написании кода IWYU мы принимаем 4 конкретных соглашения:

1. Все заголовочные файлы содержат свои необходимые зависимости.

2. Файлы .cpp сначала включают соответствующие им файлы * .h.

3. Файлы PCH больше не включены явно.

4. Монолитные заголовочные файлы больше не включены.

Соглашения IWYU

Следующие описания соглашений IWYU должны дать вам хорошее представление о правилах для IWYU.

1. Все заголовочные файлы содержат свои необходимые зависимости.

- Существует заголовочный файл CoreMinimal, содержащий набор вездесущих типов (включая FString, FName, TArray и т.д.) из UE4 Core.

- Заголовочный файл CoreMinimal (расположенный в корневом каталоге UE4 по адресу \Engine\Source\Runtime\Core\Public\CoreMinimal.h) сначала включается в большинство заголовочных файлов движка.

- В модуле Core большинство заголовочных файлов включают в себя заголовочный файл CoreTypes.h. Это включает только определения типов для примитивных типов C++, макросы сборки UE4 и директивы для настройки среды компиляции.

Основной вывод заключается в том, что каждый заголовочный файл теперь содержит все, что ему нужно для компиляции.

2. Файлы .cpp сначала включают соответствующие им файлы * .h.

- Чтобы убедиться, что все ваши исходные файлы включают в себя все необходимые зависимости, скомпилируйте игровой проект в режиме non-unity с отключенными файлами PCH.

3. Файлы PCH больше не включены явно.

- Хотя файлы PCH все еще используются, они принудительно включаются в командную строку компилятора UnrealBuildTool (UBT).

4. Монолитные заголовочные файлы больше не включены.

- Компилятор выдаст предупреждение, если ваш код содержит монолитные заголовочные файлы (такие как Engine.h или UnrealEd.h).

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

Включен ли IWYU

До установления соглашений IWYU с выпуском версии 4.15 код UE4 обычно включал файл PCH вверху каждого файла CPP, что противоречит тому, что разработчик хочет, чтобы код был совместимый с IWYU. Следуя соглашениям IWYU, файлы PCH можно рассматривать как уровни оптимизации во время компиляции, которые применяются отдельно от того, как изначально создавался код. Таким образом, вместо того, чтобы создавать и включать файлы PCH, мы оставляем за UBT решать, какой файл PCH использовать (если он есть).

Если вы хотите убедиться, что IWYU включен, и убедитесь, что модуль соответствует соглашениям IWYU, откройте файл модуля * .build.cs и убедитесь, что для PCHUsage установлено значение PCHUsageMode.UseExplicitOrSharedPCHs.

Установка PCHUsageMode.UseExplicitOrSharedPCHs в PCHUsage создает явный файл PCH для модуля, только если он имеет параметр PrivatePCHHeaderFile в файле * .build.cs модуля. В противном случае модуль использует общий PCH с другим модулем, что избавляет инструмент от создания большего количества файлов PCH, чем необходимо. Также имейте в виду, что при включении режима UseExplicitOrSharedPCHs исходный файл должен включать соответствующий ему заголовочный файл. В качестве альтернативы, если вы хотите, чтобы модуль отказался от соблюдения соглашений IWYU, вы можете установить для PCHUsage значение PCHUsageMode.UseSharedPCHs.

После преобразования кода в модель IWYU мы наблюдали значительные улучшения со временем компиляции UE4.

Работа в режиме IWYU

Если вы запускаете свою игру в режиме IWYU, вам необходимо убедиться, что ваши файлы .cpp включают в себя соответствующие им файлы .h. Это полезная практика, поскольку она позволяет компилятору гарантировать, что файл * .h включает все необходимые ему зависимости (когда файлы PCH и сборки Unity отключены). Unreal Build Tool (UBT) выдаст предупреждение, если вы не включите соответствующий заголовочный файл в начале (для соответствующего CPP-файла).

Если вы хотите отключить компилятор от выдачи предупреждений, вы можете установить для bEnforceIWYU значение false в файле модуля * .build.cs.

Если вы хотите отключить предупреждение для всего таргета, вы можете установить для bEnforceIWYU значение false в файле * .target.cs.

Общие советы

Если вы хотите выбрать IWYU для вашей игры, необходимо помнить несколько советов:

1. Включите CoreMinimal.h вверху каждого заголовочного файла.

2. Чтобы убедиться, что все ваши исходные файлы включают в себя все необходимые зависимости, скомпилируйте игровой проект в режиме non-unity с отключенными файлами PCH.

3. Если вам нужен доступ к UEngine или GEngine, подключите заголовочный файл находящийся по этому пути: Runtime\Engine\Classes\Engine\Engine.h (вместо монолитного заголовочного файла, который находится в Runtime\Engine\Public\Engine.h).

4. Если вы используете класс, который компилятор не распознает и вы не знаете какие заголовочные файлы нужно подключить, заголовочный файл класс можно убрать. Это особенно актуально если вы конвертируете код не принадлежащий IWYU, который скомпилирован правильно. Вы можете найти класс в документации API и найти необходимые модули и заголовочные файлы.

Чтобы помочь пользователям преобразовать существующие проекты на C++ в стиль IWYU, разработчики выпустили IncludeTool, который вы можете найти в \Engine\Source\Programs\IncludeTool.

IncludeTool можно найти только в исходном коде движка на GitHub, в обычных версиях этой программы нету.