This pipeline will explain how to set up build automation for Unreal Engine 4 using Perforce. The batch files used in this pipeline should work with any version control system although it might require some minor changes.
Prerequisites
Before we begin this tutorial, make sure you have the following set up and available.
- A Linux or Windows server running Jenkins CI and (optional) Perforce Helix.
- Jenkins Perforce plugin (optional)
- A local workstation with Unreal Engine 4 installed that will work as our build executor.
- Make sure you have the correct Visual Studio setup (Setting Up Visual Studio for UE4).
- Make sure you have installed the Java Runtime Environment (JRE).
Login to Jenkins
Let's start by logging into your Jenkins environment. You should have already set up your server so logging in should be easy!
Once logged in you should be greeted with the Jenkins home screen, in my example I already have a few projects running. Before we get started we will set up our build executer.
Setting up the build executor
We need to set up our build executer, this workstation will build the Unreal Engine 4 project for us and sync them with Jenkins. Navigate to "Manage Jenkins" > "Manage Nodes" and select "New Node".
Supply some information about the node, something like the above should be fine.
Note: If the "launch method", Launch with Java Web Start is not available for you, you might need to enable the TCP port of JNLP agents. You can find the option under "Manage Jenkins" > "Configure Global Security" > "TCP port for JNLP agents".
Next up we will set up some node environment variables. These settings might differ per build executer. This way we can configure the settings per build executer.
You will need to set up the environment variables for "7 zip" and our "unreal engine root". After you have done this we can start by setting up our project.
NAME: ARCHIVE_ROOT
==================================================================================
YOUR_7ZIP_ROOT_LOCATION
==================================================================================
The path to 7-zip on the device.
NAME: ENGINE_ROOT
==================================================================================
YOUR_ENGINE_ROOT_LOCATION
==================================================================================
The path to the engine version.
Setting up a new Freestyle project
From the home screen you can visit "New Item" to create a new project. In our case we will create a new "Freestyle project", give the project a appropriate name and press Ok.
Give the build a clear description. We also want to set up the number of builds to keep. In my case, my server disk space is limited so I have set up Jenkins to keep a maximum of 2 artifacts per project, for a maximum of 7 days. You should pick the options that suite your project.
Parameterize the build
To provide yourself with easy access to some settings, we want to parameterize the build.
Tick the "This project is parameterized" option.
The following script allows us to easily change our build configuration.
Choice Parameter
==================================================================================
NAME: BUILD_CONFIGURATION
==================================================================================
Development
Shipping
Test
DebugGame
==================================================================================
Development = This configuration is equivalent to Release. Unreal Editor uses the Development configuration by default. Compiling your project using the Development configuration enables you to see code changes made to your project reflected in the editor.
Shipping = This is the configuration for optimal performance and shipping your game. This configuration strips out console commands, stats, and profiling tools.
Test = This configuration is the Shipping configuration, but with some console commands, stats, and profiling tools enabled.
DebugGame = This configuration builds the engine as optimized, but leaves the game code debuggable. This configuration is ideal for debugging only game modules.
We might also want to change our engine version per build.
Choice Parameter
==================================================================================
NAME: ENGINE_VERSION
==================================================================================
UE_4.20
==================================================================================
What Unreal Engine 4 version we want to build the project with.
And we might not want to use PAK files for our build, so let's include an option. We will however have the option for PAK enabled by default.
String Parameter
==================================================================================
NAME: USE_PAK
==================================================================================
-pak
We want to easily be able to duplicate a Jenkins project for a new project. So I find it easy to have a choice parameter for my project name. So I don't have to change the project name in all the batch scripts.
Choice Parameter
==================================================================================
NAME: PROJECT_NAME
==================================================================================
ProjectName
==================================================================================
The name of the uproject file.
Add Perforce as Source Control (Optional)
If you do not want to use Perforce, you can skip this step. You will have to look up how to set up a different SCM with Jenkins.
Next up we need to supply which version control we are using. In my case, this is Perforce. If you are not using Perforce you will have to set it up for Git or SVN.
I picked the manual workspace behavior, here I can supply the stream to check and specify my workspace view mappings. Set up yours according to your project.
Note: You will need to add your Perforce Credentials, just click on "add" and follow the instructions provided by Jenkins.
We probably also want Jenkins to poll our SCM once in a while to check for possible changes. I have set up Jenkins to poll the SCM every 30 minutes. This way we will get a fresh build ever 30 minutes and also be notified if our build fails.
Building the Unreal Engine 4 project
Now we will have to set up the build commands that will be executed on our build executer.
Click on "Add Build Step" and choose "Execute Windows Batch Command".
First, we got to make sure we do not have any leftover files from the previous build.
# remove the temporary directory if it still exists
rd /s /q temp
# cleanup binaries, they will be rebuild during the process
rmdir /s /q "%WORKSPACE%\Game\Binaries"
# cleanup intermediates, they will be rebuild during the process
rmdir /s /q "%WORKSPACE%\Game\Intermediate"
Now we can use the Unreal Build Tool to start building the project.
"%ENGINE_ROOT%\%ENGINE_VERSION%\Engine\Binaries\DotNET\UnrealBuildTool.exe" -projectfiles -project="%WORKSPACE%\Game\%PROJECT_NAME%.uproject" -game -rocket -progress
Now that we have linked our project with the Unreal Build Tool, we want to rebuild our project code and make sure our binaries are up to date.
# Rebuild our binaries
"%ENGINE_ROOT%/%ENGINE_VERSION%/Engine/Binaries/DotNET/UnrealBuildTool.exe" %PROJECT_NAME% %BUILD_CONFIGURATION% Win64 -project="%WORKSPACE%/Game/%PROJECT_NAME%.uproject" -rocket -editorrecompile -progress -noubtmakefiles -NoHotReloadFromIDE -2017
Now we create a new folder to store our build in.
# Create a folder to store our build in
if not exist "%WORKSPACE%/temp/x64" mkdir "%WORKSPACE%/temp/x64"
After the folder has been created, we can start packaging our project.
"%ENGINE_ROOT%\%ENGINE_VERSION%\Engine\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="%WORKSPACE%\Game\%PROJECT_NAME%.uproject" -noP4 -platform=Win64 -clientconfig=%BUILD_CONFIGURATION% -cook -allmaps -build -stage %USE_PAK% -archive -archivedirectory="%WORKSPACE%/temp/x64"
Once the build has been completed, let's rename our temporary folder to something that provides us with some more information. In this case, we will provide the build configuration and the perforce change list number.
ren %WORKSPACE%\temp\x64\WindowsNoEditor %PROJECT_NAME%_%BUILD_CONFIGURATION%_%P4_CHANGELIST%_x64
And finally, we archive our build.
"%ARCHIVE_ROOT%/7z.exe" a -t7z %WORKSPACE%\builds\%BUILD_CONFIGURATION%\%PROJECT_NAME%_%BUILD_CONFIGURATION%_%P4_CHANGELIST%_x64.rar "%WORKSPACE%\temp\x64\%PROJECT_NAME%_%BUILD_CONFIGURATION%_%P4_CHANGELIST%_x64"
Post Build Actions
Finally we need to upload our build artifact to Jenkins, so everyone with access can access the artifact online. Click on "Add post-build action" and select "Archive the artifacts". Don't worry if Jenkins provides you with a error, this is because we are using environment variables.
builds\${BUILD_CONFIGURATION}\${PROJECT_NAME}_${BUILD_CONFIGURATION}_${P4_CHANGELIST}_x64.rar
Your project is now set up and ready to go! Finally, you might want to add Slack Notifications.