Workflow

Creating Conan packages

Sources of pre-written Conan recipes

The conan-ue4cli recipe cache

The official ue4-conan-recipes GitHub repository contains pre-written recipes for building a number of common third-party libraries with conan-ue4cli. You do not need to download these recipes manually in order to use them, as they are automatically downloaded by conan-ue4cli and stored in the local recipe cache the first time you run the ue4 conan build command. You can also run the ue4 conan update command periodically to update the recipe cache with the latest data from the GitHub repository.

Regular Conan recipes not designed for use with conan-ue4cli

There are a wide variety of Conan recipes for common tools and libraries maintained by the open source community. If a library does not depend (directly or indirectly) on any of the third-party libraries that are bundled with the Unreal Engine then it should be possible to reuse an existing Conan recipe with only minor modifications. If the library depends on any libraries that are bundled with the Unreal Engine then it will be necessary to modify the recipe more extensively to use the appropriate wrapper packages and prevent compatibility issues arising from the inclusion of multiple versions of any given dependency. Instructions for modifying existing Conan recipes to make them compatible with conan-ue4cli are provided in the Adapting existing Conan recipes for use with conan-ue4cli section below.

Writing Conan recipes for use with conan-ue4cli

Differences between regular Conan recipes and recipes compatible with conan-ue4cli

Conan recipes designed for use with conan-ue4cli are identical to regular Conan recipes aside from the following specific exceptions:

• Dynamic package channels: fully-qualified Conan package references include a “channel” as the final component of the reference. By convention, regular Conan packages typically use keywords such as “stable” or “testing” as the channel value to indicate package maturity. Conan packages designed for use with conan-ue4cli instead use the channel value to denote the version of the Unreal Engine that a package is built for (e.g. “4.23”, “4.24”, etc.) in order to make it as easy as possible for developers to differentiate between binaries for different Engine versions. As a result, the channel value is not fixed for any given package, and recipes that depend on wrapper packages or other packages built with conan-ue4cli must use their own channel value when resolving references to their dependencies.

• Use of wrapper packages: regular Conan recipes typically depend upon widely-available open source packages for common dependencies, such as those found in the official ConanCenter repository or the Bincrafters Conan repository. Recipes designed for use with conan-ue4cli can still make use of these packages for libraries that are not bundled with the Unreal Engine, but under most platforms they must be built from source using the appropriate UE4 Conan profile. Recipes that depend upon any libraries that are bundled with the Unreal Engine must use the appropriate wrapper packages generated by conan-ue4cli, and any dependencies that introduce an indirect dependency on libraries bundled with the Unreal Engine must have recipes written for them that use wrapper packages. This is necessary to prevent incompatible versions of Unreal-bundled libraries leaking into the dependency graph and resulting in compatibility issues when the package binaries are subsequently consumed by Unreal projects or plugins.

Adapting existing Conan recipes for use with conan-ue4cli

Writing recipes from scratch

Building packages

Once you have identified an existing Conan package recipe that is compatible with conan-ue4cli or written your own then the next step is to build binaries for the package and its dependencies. You should organise your recipe(s) using the following directory structure before attempting to build them with the ue4 conan build command:

# The root directory containing your recipes
./
|
|   # Contains all versions of the recipe for the package "MyPackage"
|-- MyPackage/
|   |
|   |   # Contains version 0.0.1 of the recipe for the package "MyPackage"
|   |-- 0.0.1/
|   |   |
|   |   |   # The actual recipe file for version 0.0.1 of the package "MyPackage"
|   |   |-- conanfile.py
|   |
|   |   # Contains version 0.0.2 of the recipe for the package "MyPackage"
|   |-- 0.0.2/
|       |
|       |   # The actual recipe file for version 0.0.2 of the package "MyPackage"
|       |-- conanfile.py
|
|   # Contains all versions of the recipe for the package "OtherPackage"
|-- OtherPackage/
    |
    |   # Contains version 0.0.1 of the recipe for the package "OtherPackage"
    |-- 0.0.1/
        |
        |   # The actual recipe file for version 0.0.1 of the package "OtherPackage"
        |-- conanfile.py

Once your recipes are stored in the correct directory structure, run the ue4 conan build command from the root directory containing your recipes, specifying the UE4 Conan profile to use and the names and versions of the packages to build:

# Builds the newest available version of MyPackage (0.0.2) and its dependencies,
# using the default profile for the host platform and the UE4 version reported by ue4cli
ue4 conan build "MyPackage"

# Builds version 0.0.1 of MyPackage and its dependencies,
# using the default profile for the host platform and the UE4 version reported by ue4cli
ue4 conan build "MyPackage==0.0.1"

# Builds the newest available versions of MyPackage and OtherPackage (0.0.2 and 0.0.1) and their dependencies,
# using the default profile for the host platform and the UE4 version reported by ue4cli
ue4 conan build "MyPackage" "OtherPackage"

# Builds version 0.0.1 of MyPackage and version 0.0.1 of OtherPackage, and their dependencies,
# using the default profile for the host platform and the UE4 version reported by ue4cli
ue4 conan build "MyPackage==0.0.1" "OtherPackage==0.0.1"

# Builds version 0.0.1 of MyPackage and the newest available version of OtherPackage (0.0.1), and their dependencies,
# using the default profile for the host platform and the UE4 version reported by ue4cli
ue4 conan build "MyPackage==0.0.1" "OtherPackage"

Note that none of the commands above specify a UE4 Conan profile name, so conan-ue4cli will use the default profile for the host platform and the Unreal Engine version reported by ue4cli. You can specify a profile name to build for a specific Unreal Engine version or target platform:

# Builds the newest available version of MyPackage (0.0.2) and its dependencies,
# using the profile for the Win64 target platform and Unreal Engine 4.24
ue4 conan build "MyPackage" -p ue4.24-Win64

# Builds version 0.0.1 of MyPackage and the newest available version of OtherPackage (0.0.1), and their dependencies,
# using the profile for the Linux-x86_64-unknown-linux-gnu target platform and Unreal Engine 4.24
ue4 conan build "MyPackage==0.0.1" "OtherPackage" -p ue4.24-Linux-x86_64-unknown-linux-gnu

The build command will export your package recipes to Conan’s local cache and then build them, along with all of their dependencies. For more details on customising the build process, see the page for the ue4 conan build command.

Once your package(s) have been built successfully then you are ready to move on to Consuming Conan packages.