Les modules sont la clé de voûte de l'Unreal Engine (UE). Le moteur est constitué d'un vaste ensemble de modules, et les jeux fournissent leurs propres modules pour les compléter. Chaque module englobe un ensemble de fonctionnalités et peut fournir une interface publique et un environnement de compilation (avec des macros, des chemins d'inclusion, etc.) pour d'autres modules.
Les modules sont déclarés via des fichiers sources en C# portant l'extension .build.cs et sont stockés dans le répertoire source de votre projet. Le code source C++ appartenant à un module est stocké avec le fichier .build.cs, ou dans ses sous-répertoires. Chaque fichier .build.cs déclare une classe dérivant de la classe de base ModuleRules, et définit des propriétés qui contrôlent la façon dont elle doit être générée à partir de son constructeur. Ces fichiers .build.cs sont compilés par l'outil Unreal Build Tool (UBT) et créés pour déterminer l'environnement de compilation global.
La structure typique d'un fichier .build.cs est la suivante.
using UnrealBuildTool;
using System.Collections.Generic;
public class MyModule : ModuleRules
{
public MyModule(ReadOnlyTargetRules Target) : base(Target)
{
// Properties and settings go here
}
}Propriétés en lecture seule
$ IsPlugin (booléen) : true si un plug-in contient ce module.
$ Logger (ILogger) : accesseur pour l'enregistreur de cible.
$ HasPackageOverride (booléen) : renvoie true si un type de remplacement a été spécifié sur ce module.
$ ForceIncludeFiles (List<String>) : fichiers d'en-tête qui doivent être obligatoirement inclus pour chaque fichier source dans ce module.
$ SDKVersionRelevantPlatforms (List<UnrealTargetPlatform>) : si le composant contient une plateforme et que la version SDK du projet a été remplacée par défaut, ce module est compilé en tant que module de projet et non en tant que module de moteur partagé.
$ StaticAnalyzerCheckers (HashSet<String>) : vérificateurs de l'analyseur statique devant être activés plutôt que les valeurs par défaut. Cette option n'est prise en charge que pour Clang. Consultez la page https://clang.llvm.org/docs/analyzer/checkers.html pour obtenir une liste complète. Vous pouvez aussi exécuter : 'clang -Xclang -analyzer-checker-help' ou 'clang -Xclang -analyzer-checker-help-alpha' pour obtenir la liste des vérificateurs en phase expérimentale.
$ StaticAnalyzerDisabledCheckers (HashSet<String>) : vérificateurs par défaut de l'analyseur statique devant être désactivés. Propriété non utilisée si StaticAnalyzerCheckers est renseigné. Cette option n'est prise en charge que pour Clang. Consultez la page https://clang.llvm.org/docs/analyzer/checkers.html pour obtenir une liste complète. Vous pouvez aussi exécuter : 'clang -Xclang -analyzer-checker-help' ou 'clang -Xclang -analyzer-checker-help-alpha' pour obtenir la liste des vérificateurs en phase expérimentale.
$ StaticAnalyzerAdditionalCheckers (HashSet<String>) : vérificateurs non par défaut de l'analyseur statique devant être activés. Propriété non utilisée si StaticAnalyzerCheckers est renseigné. Cette option n'est prise en charge que pour Clang. Consultez la page https://clang.llvm.org/docs/analyzer/checkers.html pour obtenir une liste complète. Vous pouvez aussi exécuter : 'clang -Xclang -analyzer-checker-help' ou 'clang -Xclang -analyzer-checker-help-alpha' pour obtenir la liste des vérificateurs en phase expérimentale.
$ StaticAnalyzerPVSDisabledErrors (HashSet<String>) : erreurs d'analyse de PVS Studio devant être désactivées.
$ AutoSdkDirectory (chaîne) : répertoire AutoSDK pour la plateforme hôte active.
$ EngineDirectory (chaîne) : répertoire actuel du moteur.
$ PluginDirectory (chaîne) : propriété du répertoire contenant ce plug-in. Utile pour ajouter des chemins vers des dépendances tierces.
$ ModuleDirectory (chaîne) : propriété du répertoire contenant ce module. Utile pour ajouter des chemins vers des dépendances tierces.
$ TestsDirectory (chaîne) : renvoie le répertoire de tests de bas niveau du module nommé « Tests ».
$ IsVcPackageSupported (booléen) : renvoie ce paramètre si VcPkg est pris en charge dans la configuration du build.
Propriétés en lecture/écriture
$ StaticAnalyzerRulesets (HashSet<FileReference>) : ensembles de règles de l'analyseur statique à utiliser pour filtrer les avertissements. Cette propriété est uniquement prise en charge pour MSVC. Consultez la page https://learn.microsoft.com/fr-fr/cpp/code-quality/using-rule-sets-to-specific-the-cpp-rules-to-run
$ AllowedRestrictedFolders (List<String>) : liste des dossiers qui peuvent être référencés lors de la compilation de ce fichier binaire, sans propager de noms de dossiers restreints.
$ AliasRestrictedFolders (Dictionary<String, String>) : ensemble de références de dossiers restreints avec alias.
$ PublicIncludePathModuleNames (List<String>) : liste de noms de modules (aucun chemin d'accès nécessaire) avec les fichiers d'en-tête auxquels les en-têtes publics de notre module doivent avoir accès, mais qu'il est inutile d'« importer » ou de lier.
$ PublicDependencyModuleNames (List<String>) : liste de noms de module de dépendance public (aucun chemin d'accès nécessaire) (l'inclusion privée/publique est automatique). Il s'agit de modules requis par nos fichiers sources publics.
$ PrivateIncludePathModuleNames (List<String>) : liste des noms de modules (aucun chemin d'accès nécessaire) avec les fichiers d'en-tête auxquels les fichiers de code privé de notre module doivent avoir accès, mais qu'il est inutile d'« importer » ou de lier.
$ PrivateDependencyModuleNames (List<String>) : liste de noms de module de dépendance privée. Il s'agit de modules dont dépend notre code privé, mais dont aucun élément de nos fichiers d'inclusion publics ne dépend.
$ CirclelyReferencedDependentModules (List<String>) : uniquement pour des raisons de compatibilité, à éviter dans le nouveau code. Liste des dépendances de module devant être traitées comme références circulaires. Ces modules doivent déjà avoir été ajoutés à la liste des modules dépendants publics ou privés.
$ PublicSystemincludePaths (List<String>) : liste des chemins d'accès aux systèmes/bibliothèques, généralement utilisée pour les modules externes (tiers). Il s'agit de répertoires publics de fichiers d'en-tête stables qui ne sont pas vérifiés lors de la résolution des dépendances.
$ PublicIncludePaths (List<String>) : (ce paramètre n'est pas nécessaire, car nous détectons tous les fichiers du dossier « Public ») liste de tous les chemins d'accès aux fichiers d'inclusion qui sont exposés à d'autres modules.
$ InternalIncludePaths (List<String>) : (ce paramètre n'est pas nécessaire, car tous les fichiers du dossier « Internal » sont découverts) liste de tous les chemins d'accès aux fichiers d'inclusion qui sont exposés à d'autres modules internes.
$ PrivateIncludePaths (List<String>) : liste de tous les chemins d'accès aux fichiers d'inclusion internes de ce module, non exposés aux autres modules (au moins une inclusion vers le chemin « privé », davantage pour éviter les chemins relatifs).
$ PublicSystemLibraryPaths (List<String>) : liste des chemins d'accès à la bibliothèque du système (répertoire de fichiers .lib ) ; pour les modules externes (tiers), utilisez plutôt PublicAdditionalLibraries.
$ PrivateRuntimeLibraryPaths (List<String>) : liste des chemins de recherche des bibliothèques à l'exécution (p. ex., (fichiers .so).
$ PublicRuntimeLibraryPaths (List<String>) : liste des chemins de recherche des bibliothèques à l'exécution (p. ex., (fichiers .so).
$ PublicAdditionalLibraries (List<String>) : liste de bibliothèques supplémentaires (noms des fichiers .lib y compris leur extension) ; utilisée généralement pour les modules externes (tiers).
$ PublicDebugVisualizerPaths (List<String>) : liste des visualiseurs de débogage supplémentaires (.natvis et .natstepfilter) exposée à d'autres modules. Cette liste est généralement utilisée pour les modules externes (tiers).
$ DependenciesToSkipPerArchitecture (Dictionary<String, List<UnrealArch>>) : listes de dépendances par architecture à ignorer lors de la liaison (utile lors de la création de builds pour plusieurs architectures, et lorsqu'une bibliothèque n'est nécessaire que pour une seule architecture). Il appartient à la chaîne d'outils d'utiliser cette propriété.
$ PublicPreBuildLibraries (List<String>) : liste de bibliothèques prégénérées supplémentaires (noms des fichiers .lib y compris leur extension) ; généralement utilisée pour les cibles supplémentaires qui sont encore générées, mais qui utilisent soit TargetRules.PreBuildSteps, soit TargetRules.PreBuildTargets.
$ PublicSystemLibraries (List<String>) : liste des bibliothèques système à utiliser. Celles-ci sont généralement référencées via le nom, puis accessibles via les chemins système. Si vous devez faire référence à un fichier .lib, utilisez plutôt PublicAdditionalLibraries.
$ PublicFrameworks (List<String>) : liste des frameworks XCode (iOS et macOS)
$ PublicWeakFrameworks (List<String>) : liste des frameworks faibles (pour les transitions de version du SE)
$ PublicAdditionalFrameworks (List<Framework>) : liste des frameworks d'ajout ; généralement utilisée pour les modules externes (tiers) sur Mac et iOS
$ AdditionalBundleResources (List<BundleResource>) : liste des ressources supplémentaires à copier dans le bundle de l'application pour Mac ou iOS
$ TypeLibraries (List<TypeLibrary>) : liste des bibliothèques de types pour lesquelles générer des en-têtes (Windows uniquement)
$ PublicDelayLoadDLLs (List<String>) : liste des DLL à chargement différé ; généralement utilisée pour les modules externes (tiers).
$ PrivateDefinitions (List<String>) : définitions du compilateur privé pour ce module.
$ PublicDefinitions (List<String>) : définitions du compilateur public pour ce module.
$ DynamicallyLoadedModuleNames (List<String>) : modules d'ajout que ce module peut nécessiter à l'exécution.
$ RuntimeDependencies (RuntimeDependencyList) : liste des fichiers dont ce module dépend à l'exécution. Ces fichiers sont mis à disposition avec la cible.
$ AdditionalPropertiesForReceipt (ReceiptPropertyList) : liste des propriétés supplémentaires à ajouter à la réception du build.
$ ExternalDependencies (List<String>) : fichiers externes qui invalident le fichier makefile s'il est modifié. Les chemins relatifs sont résolus par rapport au fichier .build.cs.
$ SubclassRules (List<String>) : fichiers de règles de sous-classe qui invalident le fichier makeFile s'il est modifié.
$ GenerateHeaderFuncs (List<ValueTuple<String, Action<ILogger, DirectoryReference>>>) : liste de noms de sous-dossiers et de fonctions appelées pour générer les fichiers d'en-tête. Le nom du sous-répertoire est ajouté au répertoire de code généré pour former un nouveau répertoire dans lequel les en-têtes sont générés.
$ Name (String) : nom de ce module.
$ Type (ModuleType) : type de module
$ OverridePackageType (PackageOverrideType) : type de module remplacé qui définit différents indicateurs de paquets. Il n'est pas possible d'utiliser ce paramètre pour les modules qui font partie d'un plug-in, car il est déjà défini dans le fichier « .uplugin ».
$ BinariesSubFolder (chaîne) : sous-dossier du dossier Binaries/PLATFORM où placer ce module lors de la génération des DLL. Cette propriété ne doit être utilisée que pour les modules trouvés via une recherche, notamment les modules TargetPlatform ou ShaderFormat. Si FindModules n'est pas utilisée pour en effectuer le suivi, les modules sont introuvables.
$ OptimizeCode (CodeOptimization) : détermine quand le code de ce module doit être optimisé.
$ OptimizationLevel (OptimizationMode) : permet d'ajuster précisément le niveau d'optimisation pour la vitesse et/ou la taille du code. Requiert un PCH privé (ou NoPCHs, ce qui n'est pas recommandé).
$ FPSemantics (FPSemanticsMode) : permet de remplacer la sémantique FP de ce module. Requiert un PCH privé (ou NoPCHs, ce qui n'est pas recommandé).
$ PrivatePCHHeaderFile (chaîne) : PCH privé explicite pour ce module. Implique que ce module n'utilisera pas de PCH partagé.
$ SharedPCHHeaderFile (chaîne) : nom du fichier d'en-tête d'un PCH partagé fourni par ce module. Il doit s'agir d'un chemin relatif valide vers un fichier d'en-tête C++ public. Cette propriété ne doit être définie que pour les fichiers d'en-tête inclus par un nombre significatif d'autres modules C++.
$ ShortName (chaîne) : spécifie un nom alternatif pour les répertoires et fichiers intermédiaires de ce module. Cette propriété est utile lorsque vous atteignez les limites de longueur de chemin.
$ PCHUsage (PCHUsageMode) : utilisation d'en-têtes précompilés pour ce module.
$ bTreatAsEngineModule (booléen) : détermine si ce module doit être traité comme un module de moteur (par exemple, à l'aide de définitions de moteur, de PCH, compilé avec les optimisations activées dans les configurations DebugGame, etc.). Cette propriété est initialisée à une valeur par défaut basée sur l'ensemble de règles à partir duquel elle a été créée.
$ bValidateFormatStrings (booléen) : génère des erreurs de compilation pour les chaînes de format UE_LOG incorrectes.
$ bValidateInternalApi (booléen) : émet des avertissements/erreurs obsolètes pour l'utilisation interne de l'API pour les modules ne faisant pas partie du moteur.
$ DefaultBuildSettings (BuildSettingsVersion) : détermine les paramètres de build de la version du moteur à utiliser par défaut.
$ IncludeOrderVersion (EngineincludeOrderVersion) : détermine la version de l'ordre d'inclusion à utiliser lors de la compilation de ce module. Peut être remplacé via -ForceIncludeOrder sur la ligne de commande ou dans les règles d'un module.
$ bUseRTTI (booléen) : utilise les informations de type d'exécution.
$ bVcRemoveUnreferencedComdat (booléen) : indique s'il convient de demander à MSVR de supprimer les données et les fonctions COMDAT non référencées.
$ bCodeCoverage (booléen) : active la prise en charge de la compilation/de la liaison de la couverture de code.
$ bUseAVX (booléen) : obsolète : indique au compilateur de générer des instructions AVX partout où des intrinsèques SSE ou AVX sont utilisées, sur les plateformes qui les prennent en charge. Notez qu'en activant cette option, vous modifiez la configuration minimale des plateformes de PC ; l'exécutable résultant peut entraîner un blocage sur les machines ne prenant pas en charge AVX.
$ MinCpuArchX64 (Nullable<MinimumCpuArchitectureX64>) : ordonne au compilateur de générer des instructions AVX partout où des intrinsèques SSE ou AVX sont utilisées, sur les plateformes x64 qui les prennent en charge. Notez qu'en activant cette option, vous modifiez la configuration minimale des plateformes de PC ; l'exécutable résultant peut entraîner un blocage sur les machines ne prenant pas en charge AVX.
$ bEnableBufferSecurityChecks (booléen) : active les contrôles de sécurité du tampon. Cette propriété doit généralement être activée, car elle évite les risques de sécurité élevés.
$ bEnableExceptions (booléen) : active la gestion des exceptions.
$ bEnableObjCExceptions (booléen) : active la gestion des exceptions de l'objectif C
$ bEnableObjectiveCAutomaticReferenceCounting (booléen) : active le décompte automatique des références de l'objectif C (ARC). Si cette propriété est définie sur true, vous ne devez pas utiliser de PCH partagés pour ce module. Le moteur n'utilise pas l'ARC de manière intensive à court terme. Si vous ne procédez pas ainsi, des erreurs de compilation risquent de se produire, car les PCH partagés ont été compilés avec des indicateurs différents de ceux du consommateur.
$ DeterministicWarningLevel (WarningLevel) : indique comment traiter les avertissements déterministes (fonction expérimentale).
$ ShadowVariableWarningLevel (WarningLevel) : indique comment traiter les alertes de variable d'ombre.
$ bWarningsAsErrors (booléen) : indique s'il convient d'activer tous les avertissements en tant qu'erreurs. L’UE active déjà la plupart des avertissements en tant qu'erreurs, mais en désactive certaines (comme les avertissements d’obsolescence).
$ UnsafeTypeCastWarningLevel (WarningLevel) : indique comment traiter les avertissements de conversion de type implicite non sécurisée (par exemple, double->float ou int64->int32).
$ UndefinedIdentifierWarningLevel (WarningLevel) : indique le niveau d'avertissement/d'erreur auquel traiter les identificateurs non définis dans les expressions conditionnelles.
$ bEnableUndefinedIdentifierWarnings (booléen) : active les avertissements suite à l'utilisation d'identificateurs non définis dans les expressions #if
$ ModuleIncludePathWarningLevel (WarningLevel) : indique comment traiter les messages de validation de chemin d'inclusion de module général.
$ ModuleIncludePrivateWarningLevel (WarningLevel) : indique comment traiter les messages de validation de chemin d'inclusion de module privé, où un module ajoute un chemin d'inclusion qui expose les en-têtes privés.
$ ModuleIncludeSubdirectoryWarningLevel (WarningLevel) : indique comment traiter les messages de validation de chemin d'inclusion de sous-répertoire de modules inutiles.
$ bDisableStaticAnalysis (booléen) : désactive toutes les analyses statiques - clang, msvc, pvs-studio.
$ bStaticAnalyzerExtensions (booléen) : active les avertissements d'extension de l'analyseur supplémentaires à l'aide du plug-in EspXEngine. Cette propriété est uniquement prise en charge pour MSVC. Consultez la page https://learn.microsoft.com/fr-fr/cpp/code-quality/using-the-cpp-core-guidelines-checkers Ce paramètre ajoute un grand nombre d'avertissements par défaut. Il est recommandé d'utiliser StaticAnalyzerRulesets si cette propriété est activée.
$ bUseUnity (booléen) : indique si les builds Unity sont activés ; il est possible d'utiliser cette propriété pour déterminer si le build de ce module spécifique sera créé avec Unity. Pour ce faire, il convient d'utiliser les configurations par module de BuildConfiguration.
$ bMergeUnityFiles (booléen) : indique s'il convient de fusionner le module et les fichiers Unity générés pour une compilation plus rapide.
$ MinSourceFilesForUnityBuildOverride (Int32) : nombre de fichiers sources dans ce module avant que le build Unity soit activé pour ce module. Si la valeur définie est autre que -1, cette propriété remplace le paramètre par défaut, qui est contrôlé par MinGameModuleSourceFilesForUnityBuild
$ MinFilesUsingPrecompiledHeaderOverride (Int32) : remplace BuildConfiguration.MinFilesUsingPrecompiledHeader si la valeur est non nulle.
$ NumIncludedBytesPerUnityCPPOverride (Int32) : remplace Target.NumIncludedBytesPerUnityCPP si la valeur est non nulle.
$ bBuildLocallyWithSNDBS (booléen) : dans la mesure où le module utilise #import, il doit être généré localement lors de la compilation avec SN-DBS
$ bEnableNonInlinedGenCppWarnings (booléen) : active les avertissements si des fichiers .gen.cpp peuvent être intégrés dans un fichier cpp manuscrit correspondant.
$ IsRedistribuableOverride (Nullable<Boolean>) : indicateur de remplacement de redistribution pour ce module.
$ bLegalToDistributeObjectCode (booléen) : indique si la sortie de ce module peut être distribuée publiquement, même si elle contient du code ou dépend de modules qui ne le sont pas (par exemple : CarefullyRedist, NotForLicensees, NoRedist). Utilisez cette propriété lorsque vous prévoyez de publier des fichiers binaires, mais pas du code source.
$ bEnforceIWYU (booléen) : applique les règles « include what you use » lorsque la propriété PCHUsage est définie sur ExplicitOrSharedPCH ; envoie un avertissement lorsque des en-têtes monolithiques (Engine.h, UnrealEd.h, etc.) sont utilisés et vérifie que les fichiers sources incluent d'abord l'en-tête correspondant.
$ IWYUSupport (IWYUSupport) : permet à la variable « include what you use » de modifier le code source lors de l'exécution. bEnforceIWYU doit être définie sur true pour que cette variable prenne effet.
$ bAddDefaultIncludePaths (booléen) : indique s'il convient d'ajouter tous les chemins d'inclusion par défaut au module (p. ex., dossier Source/Classes, sous-dossiers sous Source/Public).
$ bIgnoreUnresolvedSYMbols (booléen) : indique s'il convient d'ignorer les symboles orphelins (p. ex., externes non résolus) dans les modules.
$ bPrecompile (booléen) : indique s'il convient de précompiler ce module. Cette propriété est par défaut définie sur l'indicateur bPrecompile de la cible. Supprimez cet indicateur pour empêcher la précompilation d'un module.
$ bUsePrecompiled (booléen) : indique si ce module doit utiliser des données précompilées. Cette propriété est toujours définie sur true pour les modules créés à partir d'assemblages installés.
$ bAllowConfidentialPlatformDefines (booléen) : indique si ce module peut utiliser les définitions de style PLATFORM_XXXX, où XXXX correspond au nom de plateforme confidentiel. Cette propriété permet de s'assurer que le moteur ou tout autre code partagé ne révèle pas d'informations confidentielles à l'intérieur d'un bloc #if PLATFORM_XXXXXX. Le code du jeu du titulaire de la licence peut toutefois autoriser ces définitions.
$ bDisableAutoRTFMInstrumentation (booléen) : désactive l'instrumentation AutoRTFM de ce module uniquement lorsque AutoRTFMCompiler est activé.
$ PrecompileForTargets (PrecompileTargetsType) : cibles pour lesquelles ce module doit-il être précompilé.
$ bRequiresImplementModule (Nullable<Boolean>) : indique si ce module nécessite l'implémentation de la macro IMPLEMENT_MODULE. La plupart des modules de l'UE nécessitent cette propriété, car la macro IMPLEMENT_MODULE sert à effectuer d'autres surcharges globales (p. ex., transfert des opérateurs new/delete vers GMalloc).
$ bLegacyPublicIncludePaths (booléen) : indique si ce module qualifie les en-têtes inclus d'autres modules relatifs à la racine de leur dossier « Public ». Cette propriété réduit le nombre de chemins de recherche qui doivent être transmis au compilateur, ce qui améliore les performances et réduit la durée de la ligne de commande du compilateur.
$bLegacyParentIncludePaths (booléen) : indique si ce module qualifie les en-têtes inclus d'autres modules relatifs au répertoire parent. Cette propriété réduit le nombre de chemins de recherche qui doivent être transmis au compilateur, ce qui améliore les performances et réduit la durée de la ligne de commande du compilateur.
$ bValidateCirularDependencies (booléen) : indique si les dépendances circulaires seront validées par rapport à la liste d'autorisation. Les dépendances de module circulaire entraînent des builds plus lents. Il est vivement déconseillé de désactiver cette option. Cette option est ignorée pour les modules du moteur qui sont toujours validés par rapport à la liste d'autorisation.
$ CppStandard (Nullable<CppStandardVersion>) : norme à utiliser pour compiler ce module.
$ CStandard (Nullable<CStandardVersion>) : norme à utiliser pour compiler ce module.
$ ModuleSymbolVisibility (SymbolVisibility) : contrôle la visibilité des symboles.