Introduction
Unreal Engine is one of the most popular game development engines today, and many popular games are developed using Unreal Engine.
However, the definition of the term 'engine' in the industry is somewhat vague and can mean different things to different people. Is it a code library? An editor? Or a toolbox?
It could be all of those, yet there is a lack of documentation to help people understand it correctly.
In my previous work, I often dealt with integrating third-party libraries into the engine, and I spent a lot of time understanding the Unreal build process. Now, I am writing the results in this article.
If you do not understand how C++ is compiled, I recommend you read this website: LearnCpp
What is Unreal Engine?
I would like to try to explain this with my own understanding. Unreal Engine is a bunch of C++ code that can be compiled in different ways on different platforms (operating systems). You can extend the engine code with your own game code (i.e., develop games on top of Unreal), but your code will heavily depend on the engine code.
When you compile Unreal Engine from source, you will generate a game client (something that runs on PC or console), a game server (for multiplayer games), an editor, and many other small programs (referred to as Programs in the engine source, which are specific programs that accomplish specific tasks). This editor allows you to do many things, including tools for designing scenes, and you can also write (drag and drop) blueprints (a scripting language unique to Unreal Engine). These small programs include a bunch of tools, such as Unreal Build Tool and Unreal Header Tool, and this is what we will discuss in this article.
What is Unreal Build Tool?
To support multiple compilation forms and multi-platform support, and even compile the same code into a .lib or a .dll (for hot loading), the Unreal development team decided to develop their own build tool, which means no longer using traditional makefiles or MSBuild, but using Unreal Build Tool. Therefore, C++ development and integration of third-party libraries in Unreal will be somewhat different compared to traditional methods.
Unreal Build Tool is written in C# and serves as the first compilation step in the entire Unreal compilation process. When you run 'GenerateProjectFiles' (a batch file used to generate Visual Studio solutions and projects), this first step is to execute MSBuild to compile this 'Unreal Build Tool' under the Source/Programs/UnrealBuildTool/UnrealBuildTool.csproj project.
So, Unreal Build Tool is actually a command-line program that can accomplish many tasks, such as generating project files, executing Unreal Header Tool, and calling compilers (Compiler) and linkers (Linker) for various different platform build styles. This process will be explained in detail later.
Modules
Modules in Unreal Engine are actually a series of source files. They can be C++ modules or C# modules. C# modules use .csproj (Visual Studio C# project description file) as their project file.
For C++ modules, it gets a bit strange. Modules use a 'ModuleName.build.cs' file to define themselves, which is similar to vcxproj (Visual Studio C++ project description file), with a Private directory for storing private header files and source files; and a Public directory for storing public header files and source files.
Header files in the Public directory are exposed to other modules by default (you can directly include files from this directory after adding module dependencies), while those in the Private directory are not (unless you manually add PrivateIncludePath).
Therefore, the rule for creating a C++ module is to create a new directory under Engine/Source or your game project/Source and add a .Build.cs file. The dependencies of this module on other modules also need to be configured in the .Build.cs file.
The same goes for integrating third-party code; create a directory, a .Build.cs, and describe in the .Build.cs file how the module is built and which header files need to be exposed to other modules.
A C++ module can be compiled as a whole (monolith), or as part of other modules (an executable file, Dll, etc.), or as a .dll for hot loading. This is the flexibility provided by Unreal.
Reference Unreal Engine Modules
Targets
A Target in Unreal can be understood as a 'compilation form' mentioned earlier.
UnrealBuildTool supports building multiple target types: - Game - a standalone game - Client - the same as the game, but without any server code. Suitable for online games. - Server - the same as the game, but without any client code. Suitable for dedicated servers in online games. - Editor - extends the target of the Unreal editor. - Program - builds standalone utilities on top of Unreal Engine.
Targets are declared by C# source files with the extension .Target.cs and stored in the project's Source directory. They can be used to set a bunch of definitions and other properties that a Target depends on. Even Unreal utilities like UnrealHeaderTool are built as Program targets.
Reference Targets
Generating Project Files
First, what you need to do is run GenerateProjectFiles. But... what will happen?
- Unreal Build Tool is built.
- The batch file calls a command similar to the following (depending on your project, Visual Studio version, platform, etc.)
-ProjectFiles -nodummyconfigs -game -engine -2017 "-project=Path\To\Your\Project.uproject" -Platforms=Win64+XboxOne+UWP64 -noSolutionSuffix - Unreal Build Tool will search all files with the .Build.cs extension in the engine and game directories to discover all defined modules.
- Unreal Build Tool will search all files with the .Target.cs extension to discover all defined targets.
- It will generate a solution that includes all targets as build configurations and all modules as projects.
C# projects are just .csproj files in the source folder. C++ projects are not exactly 'standard' projects. They no longer call MSBuild, but call UnrealBuildTool!
Building C++ Projects
When building C++ projects in Unreal, you can see (based on the NMakeBuildCommandLine property of vcxproj) a command line similar to this will be called:
C:\Path\To\Your\Engine\Build.bat TargetName Win64 Debug "$(SolutionDir)$(ProjectName).uproject" -waitmutex $(AdditionalBuildArguments) -2017
It actually calls UnrealBuildTool behind the scenes!
So, the role of UnrealBuildTool here is:
- Compile targets. It compiles the .Target.cs code at runtime (using the C# compiler) to obtain build properties. This is where UnrealBuildTool gets most of the definitions and platform information. Certain properties (like bBuildEditor) indicate that you need to build the editor. It creates a WITH_EDITOR definition that is then forwarded to the source files by the compiler for conditional compilation in the source code: #if WITH_EDITOR conditional compilation.
- Resolve all dependent modules, including dependencies from .Target.cs and .Build.cs (modules).
- Compile all dependent modules' Build.cs to get additional properties on how to build each module.
- Resolve which modules use shared compilation headers (i.e., .Build.cs files that include SharedPCHHeaderFile properties, such as CoreUObject, Core, Engine, etc.).
- Resolve which modules depend on the UObject module.
- Run Unreal Header Tool for all modules that depend on UObject, at which point Unreal Engine will inject some behaviors into your classes, forcing you to include the '.generated.h' header file generated by Unreal Header Tool in your files.
- Based on the code generated by Unreal Header Tool, resolve all include paths.
- Based on the resolved paths, definitions, external libraries, etc., generate a series of command lists that will be executed in the target environment:
- Call the compiler (CL.EXE) for shared precompiled headers
- Call the compiler to compile source files (CL.EXE)
- Call the linker (LINK.EXE)
- Call all these operations
Clearly, these steps are somewhat simplified. There are more details and settings, such as whether you use CLR, whether you use Mono, whether you use Clang, etc. But the general steps are similar to what has been described above.
Conclusion
I hope this article can help those who are accustomed to using standard build tools understand the details of UnrealBuildTool.
Hope it helps~