Download

UGS Precompiled Binaries Guide

Mar 23, 2021.Knowledge

Precompiled binaries (PCBs) of an editor built for a project are useful if a team has content creators who don’t need to work with the code base or rebuild the editor in order to create content for their project. To enable users to download precompiled binaries, a zip file containing the required binaries can be submitted to Perforce. UnrealGameSync will then sync and extract that zip file instead of compiling locally.

Doing this uses the same user interface as compiling locally, but any changes that don’t have matching binaries will be greyed out. Once configured, users can opt in to using precompiled binaries by checking the Sync Precompiled Binaries item under the Options menu.

Basic Perforce Setup

Without going into great detail on what’s required from a connection or network configuration standpoint, we’re going to detail what users will need in order to use Precompiled Binaries with their Unreal projects and engine. To set up a Perforce server’s contents for use with UGS, there are a few things to be done.

Users will need a single stream that contains their engine source code, dependencies that aren’t generated by Unreal’s build process, and their projects.

  • To make sure all required Unreal Engine files are present, users should copy of one of Epic’s existing Perforce release streams
  • Any of our release streams with the naming convention //UE4/Release-4.xx should be fine to copy from
    • Make sure the .p4ignore.txt file is copied, as that will make sure no extra files are added to the copy of a stream after developers start building from it locally.
  • Users can also use the GitHub source build ( https://github.com/EpicGames/UnrealEngine ), run GitDependencies.exe, and upload the full source as well as dependencies that were gathered. Copying one of our Perforce streams is still the recommended path, and a copy of the .p4ignore.txt file from a stream is required regardless of how the files are gathered, generated, and uploaded.
  • Either way you decide to set up your files within Perforce, make sure their file types and permissions match the release stream of whatever release you’re setting up. If a file is marked as writable in our stream, it should also be writable in your stream. A mismatch between what’s writable and not might cause build or runtime failures. To check these permissions, open the stream in P4V and check to the right of the filename:

If you find you need to change the file type or permissions in your stream, right click the file after opening it for edit, and click “Change Filetype”:

This will open up a menu that you’re able to edit the file type and permissions to match our release stream.

Note: if you get an “Access Denied” error for a specific file during a build or at runtime, it’s most likely due to these permissions not being set up properly.

  • Any project that is used with UGS will need to be native and in the same stream as the files for the Unreal Engine.
    • A native project is one that’s discoverable from either the top level directory of Unreal’s directory structure, or is discoverable one level deep from a path listed in a .uprojectidrs file (also at the top level of Unreal’s directory structure).
    • For additional information on native projects that contains specific examples and images of file structures that are compatible with UGS, please read this Knowledge Base Article: https://udn.unrealengine.com/s/article/What-s-a-Native-Project

Users should use a separate stream to hold the Precompiled Binaries zip file

  • It’s possible to use a single stream, but it’s highly recommended to use a second, separate stream that all users with access to the first stream also have access to. This will avoid churn for team members that do not use PCBs.

    • It is not necessary to maintain a separate workspace for this; UnrealGameSync will fetch the PCBs in a stateless way using the same login credentials that it uses to sync files.
  • To configure the stream for PCBs to be uploaded to, add Build/UnrealGameSync.ini under the project’s root directory and reference the Perforce location the binaries will be uploaded to. This is what UGS will search for when getting PCBs from Perforce.

An example Build\UnrealGameSync.ini entry:

[//UE4/Main/Samples/Games/ShooterGame/ShooterGame.uproject]

ZippedBinariesPath=//UE4/Dev-Binaries/++UE4+Main-Editor.zip

Note: UnrealGameSync.ini is required to be in the location [Project Root]/Build/*

  • When specifying the ZippedBinariesPath, there are a couple things to keep in mind:
    • The name //UE4/Dev-Binaries/++UE4+Main-Editor.zip needs to match the ArchiveStream argument mentioned in the upload section below, where ++UE4+Main is the name of the current branch with slashes escaped as ‘+’ characters. The slashes should be present instead of the ‘+’ characters when using the argument.
    • Any user account that has access to the PCB stream can upload a new set of PCBs to them, but how this is done is up to users, as this is subjective to how a studio wants to deploy. A manual user could do this, or an automated build node could also be responsible.

Generating and Uploading Precompiled Binaries

After the two streams are set up and users have permissions to access them, it’s time to generate and upload the PCBs to the designated PCB stream.

To generate and upload the PCBs:

  • Sync the main stream’s contents from Perforce
  • Run a BuildGraph script that’s based on our example, located at

[UE Root]/Engine/Build/Graph/Examples/BuildEditorAndTools.xml

to generate and upload PCBs to the correct Perforce location (using the -ArchiveStream argument to specify the location)

An example command using BuildEditorAndTools:

Engine\Build\BatchFiles\RunUAT.bat

BuildGraph

-Script=Engine/Build/Graph/Examples/BuildEditorAndTools.xml

-Target=“Submit To Perforce for UGS”

-set:EditorTarget=ShooterGameEditor

-set:ArchiveStream=//UE4/Dev-Binaries

-p4

-submit

In this example, ShooterGame is a native project, and any projects users want to upload PCBs need to be native as well.

Note: Additional information about using BuildEditorAndTools.xml can be found in the comments at the start of the file.

Note: ArchiveStream needs to match the ZippedBinariesPath specified earlier, but instead of the ‘+’ characters to escape the slashes, slashes are used.

  • This example will submit a zip file to //UE4/Dev-Binaries/++UE4+Main-Editor.zip, where ++UE4+Main is the name of the current branch with slashes escaped as ‘+’ characters. The same path should be set as the value for ZippedBinariesPath in UnrealGameSync.ini.

Note: Make sure CL descriptions are in the right format. UGS expects each CL description to start with [CL nnnnnnnnn] so it knows which changelist the binaries are associated with

Note: PDBs are included in this zip file, but they are stripped to reduce build size. This will allow callstacks to be gathered from crashes, but not allow for full debugging. If a team needs better symbol storage, they’ll probably want to use a symbol server, which is left to their IT and Deployment teams to implement.

Using Precompiled Binaries from UGS

After the precompiled binaries have been successfully generated and uploaded to a secondary stream, using the files located in the primary stream, UGS should be able to detect and use PCBs with the main stream.

  • Toggle the "Sync Precompiled Binaries’’ option, and sync to latest. The pictured example is a stream without any precompiled binaries, but the option should be selectable if the binaries were set up correctly in the previous steps.
  • PCBs should be picked up and used instead of building the engine for anyone with this option selected