Contents

Read These First

Key concepts

Contents

Since conan-ue4cli acts as a bridge between the Conan C++ package management system and the Unreal Engine’s build system, there are a number of concepts related to both of these systems that developers must be familiar with before they can start making use of conan-ue4cli. These concepts are presented below, grouped by the technology or system from which they originate.

C++ concepts

The Conan and conan-ue4cli documentation both assume that readers are familiar with building and consuming C++ code libraries. The following concepts must be understood and will not be explained elsewhere in this documentation:

  • Multi-phase translation: there are a number of phases that occur when compiling and linking C++ source code. Readers must be familiar with how preprocessing, compilation and linking works. Setting the correct search paths for headers and libraries is key when working with third-party libraries, and clashes between preprocessor definitions from different libraries are a common issue in the Unreal Engine.

  • Static .vs. dynamic libraries: although conan-ue4cli currently only supports building and consuming static libraries, readers should be familiar with the details of different linking types and their differences. This is particularly important because most of Epic’s official documentation on integrating third-party libraries features a distinct focus on dynamic libraries and understanding which elements are not applicable to static libraries can help to avoid confusion.

  • ABI compatibility: C++ code compiled for one configuration of compiler, build type, compiler flags, etc. is not necessarily compatible with code compiled for another, similar configuration. Understanding C++ ABI compatibility issues is particularly important when working with the Unreal Engine under Linux, or under Windows with Visual Studio and different versions of the C Run-time Library (CRT).

Conan concepts

Ideally, developers should have a complete understanding of Conan prior to using conan-ue4cli and should familiarise themselves with the system by using it within standalone C++ projects that do not involve the Unreal Engine. However, the following concepts represent the absolute minimum that must be understood:

  • Packages, recipes and binaries: packages are how individual tools or code libraries are represented in Conan. A package consists of a recipe, which is a Python script describing the package’s dependencies and the steps required to build the package from source, and binaries, which are the results of building the package for a given configuration of operating system, compiler, build type, etc. Each package may depend on any number of other packages, and each of those packages may also depend on other packages in turn, resulting in a complex dependency graph. Conan will ensure binaries for the entire dependency graph are present when building a package, either by building each dependency from source or by downloading pre-built binaries from a remote repository.

  • Profiles: profiles are used to encapsulate a set of configuration options for building conan packages. Profiles specify all of the information required to build packages for a given configuration, including the operating system, compiler, build type, environment variables, required build tools and other settings. Typically a single profile will represent a single build configuration with respect to ABI compability, and binaries built with different profiles will result in different package IDs. Profiles are particularly useful when cross-compiling for target systems that differ from the host system performing the build, since they can encapsulate the details of the entire cross-compilation toolchain and sysroot.

  • Remotes: remotes are Conan servers to which packages can be uploaded and from which packages can be downloaded. Remotes are useful for sharing packages between multiple developers in a team, or across multiple machines that are building or consuming packages. This mechanism can be particularly useful when you are already using conan-ue4cli on an existing machine (or inside a Docker container) and need to speed up the process of getting conan-ue4cli setup on a new machine.

  • Local cache: Conan maintains a local filesystem cache to store copies of package recipes and their accompanying binaries. The cache is populated when Conan packages are built from source, and is also used when exchanging data with a Conan remote. When building a Conan package the local cache is searched first for its dependencies, followed by any configured remotes, although this behaviour can be configured using build policies.

Unreal Engine concepts

Developers who use the Unreal Engine but do not modify its underlying source code may not be familiar with the Engine’s unique build system. Although a complete understanding of how the build system works is not necessary, the following concepts do need to be understood prior to using conan-ue4cli:

  • UnrealBuildTool: UnrealBuildTool (UBT) is the tool that is used to compile the source code for the Unreal Engine, as well as all Unreal projects and plugins. UBT is written in C#, and discovers information about a codebase by compiling and loading the assemblies of C# rules files that describe individual modules and targets (discussed below.) UBT is the heart of the Unreal Engine build system, and fulfills the same role as other C++ build systems that readers may be familiar with, such as MSBuild or CMake. Although UBT invokes other tools such as UnrealHeaderTool (UHT) to preprocess source files and is itself commonly invoked by the Unreal AutomationTool (UAT) as part of larger workflows, UBT itself is the only tool that directly interacts with the underlying C++ compiler toolchain and controls all compilation and linking of source code. UBT also supports exporting build configuration information in JSON format, and it is this export functionality that conan-ue4cli uses to query UBT for information about the Unreal Engine’s bundled third-party libraries.

  • Bundled third-party libraries: the Unreal Engine source tree bundles a number of third-party libraries under the Engine/Source/ThirdParty directory. Each of these libraries is accompanied by an XML file with a .tps extension which describes the library’s purpose and license. A small handful of these libraries are proprietary technologies that Epic Games has licensed from various vendors, but the majority are freely-available open source libraries. Some of these open source libraries are unmodified from their publicly-available upstream versions, whilst others include specific modifications made by Epic Games engineers. Each third-party library includes pre-compiled binaries for each of the target platforms under which it is supported. These binaries are typically dynamic libraries for proprietary dependencies and static libraries for open source dependencies, although a few open source libraries do include dynamic libraries, such as the Chromium Embedded Framework (CEF). In cases where a given third-party library depends upon another one, the provided binaries for the library are specifically built against the bundled version of its dependency.

  • Modules: the source code for the Unreal Engine itself, as well as all Unreal projects and plugins, is organised into a set of modules, each of which represents an individual component that encapsulates a unique set of functionality. Each module consists of a directory containing zero or more source files and a C# rules file with a .Build.cs file extension. The rules file declares the module type, which can be either a C++ Module that encapsulates actual source code or an External Module that provides access to pre-compiled binaries for a third-party library. C++ Modules are used to encapsulate all of the source code for the Unreal Engine itself, whilst External Modules are used to encapsulate all of the Engine’s bundled third-party libraries. The contents of the rules file for a module differs depending on the module type. Rules files for C++ Modules define the compiler configuration required in order to build the source files for that module, whereas rules files for External Modules define the compiler configuration required to link against the pre-built binaries for the module’s encapsulated third-party libraries. Both C++ Modules and External Modules can list other modules as dependencies, allowing modules to consume the functionality of other modules, and C++ modules can also separate the public and private subsets of their API in order to restrict which parts of their functionality can be consumed by dependant modules.

  • Targets: in the same manner that modules define the individual functional components that make up the Unreal Engine source code, targets define the executable applications that consume that functionality. By default, modules are compiled into dynamic libraries and targets are compiled into standalone executables that link against those libraries. Targets do not contain any C++ source code themselves and each target consists purely of a C# rules file with a .Target.cs file extension. The rules file lists the modules that the target links against and the target type. Each target must specify one of the predefined target types listed in the linked documentation page. The Unreal Engine itself is organised into a small number of targets representing the Editor and associated tools, as well as three special targets named UE4Client, UE4Game and UE4Server, which are used to represent different target types when packaging Blueprint-only projects that contain no C++ source code. The source code generated for newly-created C++ Unreal projects typically includes two targets by default, an Editor target and a Game target, but Client and Server targets can be added after initial project creation. Unreal plugins contain modules but do not contain targets, since plugins cannot be compiled into executable applications.

conan-ue4cli concepts

For the sake of establishing convenient and consistent terminology, we define the following concepts that are specific to conan-ue4cli itself, although each concept simply represents the manner in which conan-ue4cli makes use of the existing concepts from Conan and the Unreal Engine, and does not introduce additional foundational knowledge:

  • Wrapper packages: during initial setup, conan-ue4cli generates Conan packages that encapsulate each of the Unreal Engine’s bundled third-party libraries, effectively translating the information contained in the rules file for each External Module into a format that Conan understands, whilst also copying all of the header files and static library files for the third-party library to ensure the generated package is self-contained and does not rely on the original Unreal Engine installation that was used to generate it. These are regular Conan packages and are referred to as wrapper packages purely to differentiate them from any other Conan packages, such as packages that consume the wrapper packages or other unrelated Conan packages that may be present on a given machine.

  • UE4 Conan profiles: during initial setup, conan-ue4cli generates Conan profiles to encapsulate all of the configuration settings required to build packages that are compatible with the selected Unreal Engine installation and its bundled third-party libraries. These are simply regular Conan profiles that contain information about the Unreal Engine version, compiler toolchain, and generated wrapper packages. We refer to them as UE4 Conan profiles purely to differentiate them from any other Conan profiles that may be present on a given machine which were not generated by conan-ue4cli.

  • Recipe cache: conan-ue4cli maintains a cache of Conan recipes that can be used to build common third-party libraries with the ue4 conan build command. The recipe cache is automatically populated with the recipes from the ue4-conan-recipes GitHub repository the first time packages are built and can subsequently be updated using the ue4 conan update command. It is important to note that the recipe cache is distinct from Conan’s local cache and serves to act only as a source directory for the ue4 conan build command, which will by default export the recipes to Conan’s local cache, where both recipes and binaries for built packages are stored.

  • Boilerplate modules: boilerplate modules are simply External Modules that are generated by conan-ue4cli and whose rules files contain logic to retrieve information about encapsulated third-party libraries from Conan instead of directly hardcoding these details in the way that standard External Modules in the Unreal Engine source tree do. This logic automatically determines which UE4 Conan profile corresponds to the Unreal Engine version and build configuration that UBT is building the boilerplate module for, and then invokes Conan using that profile to retrieve the the compiler configuration data required to link against the binaries from the Conan packages that the boilerplate module depends upon. Once generated and configured with the list of Conan packages to encapsulate, boilerplate modules can be placed in the source tree of Unreal projects or plugins in the same manner as any other module, and the logic in their rules files be triggered automatically when that boilerplate module is built by UBT. Boilerplate modules are named as such to differentiate them from External Modules which were not generated by conan-ue4cli, and because the auto-generated code in their rules files is effectively boilerplate code that never needs to be modified.

  • Precomputed dependency data: by default, boilerplate modules retrieve information about their encapsulated third-party libraries from Conan when they are built by UBT, which means that Conan, the relevant UE4 Conan profiles generated by conan-ue4cli and their corresponding wrapper packages must all be present in order to build any Unreal project or plugin that includes a boilerplate module. To facilitate sharing Unreal projects and plugins with developers who do not have conan-ue4cli installed on their machines, the logic in the rules files for boilerplate modules also supports loading precomputed dependency data from their filesystem directories. If precomputed dependency data is present for the Unreal Engine version and build configuration that UBT is building the boilerplate module for, then this will simply be used and Conan will not be invoked. If precomputed dependency data is not present for the current build configuration then the logic in the rules file will fallback to the default behaviour and Conan will be queried as usual.