UGS Precompiled Binaries

When you use UnrealGameSync (UGS) to sync and compile a build, it depends on your local machine having an IDE that can compile Unreal Engine (UE), and uses a series of scripts to automate the build process. However, many contributors on a project do not work with the code base or have access to an IDE. To make it possible for these users to run up-to-date builds of a project, UGS supports adding precompiled binaries (PCBs) to builds. You can submit PCBs to Perforce in a .zip file to associate them with a changelist. After that, UGS can sync and extract the .zip file's contents 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 Sync Precompiled Binaries under the Options menu.

Basic Perforce Setup

The following procedure explains what users need in order to use precompiled binaries with their UE projects. This procedure assumes that the user already has Perforce set up for use as source control. To set up a Perforce server's contents for use with UGS, proceed as described here.

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 from one of Epic's existing Perforce release streams.

Any of our release streams with the naming convention //UE/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, run GitDependencies.exe, and upload the full source as well as dependencies that were gathered. Copying one of Epic's 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 Perforce 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.

  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).

Setting Up Streams

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

It's possible to use a single stream, but we highly recommend using 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; Unreal Game Sync will fetch the PCBs in a stateless way using the same login credentials that it uses to sync files.

To configure the stream where PCBs will be uploaded:

1. Add Build/UnrealGameSync.ini under the project's root directory and reference the Perforce location where the binaries will be uploaded. 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

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

2. When specifying the ZippedBinariesPath, there are some details to remember:

   • 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 will vary depending on how a studio wants to deploy. A manual user can perform the upload, or an automated build node can 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:

1. Sync the main stream's contents from Perforce.

2. 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 as PCBs need to be native as well.

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

   ArchiveStream needs to match the ZippedBinariesPath specified earlier, but instead of the '+' characters to escape the slashes, slashes are used.

3. 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.

   Make sure CL descriptions are in the right format. UGS expects each CL description to start with 'CL' followed by an 8-digit number (CL ########) so it knows which changelist the binaries are associated with.

   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.

1. Enable 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.

   

2. PCBs should be picked up and used instead of building the engine for anyone with this option selected.