Cross-Compiling for Linux

Choose your OS:
Prerequisite Topics

This page assumes you have prior knowledge of the following topics. Please read them before proceeding.

LinuxXC_Banner.png

Recent improvements to the cross-compile toolchain make it possible for Unreal Engine 4 (UE4) developers to target a variety of platforms from their Windows development environment. This guide tells you which platforms you can target with the cross-compilation toolchain, providing a link to download the toolchain, and ultimately showing you how to set it up to cross-compile a UE4 project for Linux. If you're developing a project in Unreal Engine, version 4.15, you'll also learn how to switch between target platforms.

If you're developing your project with Unreal Engine, version 4.13 (or older), you'll want to refer to our Cross-Compiling for Linux (Legacy) documentation.

Why Cross-Compilation

Cross-compilation makes it possible for game developers, working in a Windows-centric workflow, to target Linux. At this time, cross-compilation is only supported for Windows. Mac users currently have to resort to native compilation . We support, test, and provide the libraries and toolchains for the Linux-x86_64 platform.

Getting the Toolchain

Please use the following table to download the appropriate toolchain:

Toolchain

UE4 Version

-v4 clang-3.5.0-based

<= 4.8

-v6 clang-3.6.0-based

4.9 and 4.10

-v7 clang-3.7.0-based

4.11 thru 4.13

-v8 clang-3.9.0-based

4.14 and 4.15

-v9 clang-4.0.0-based

4.16

We also provide the libraries and toolchains that allow you to compile for Linux ARM as well (original Raspberry Pi and up). Although, this will require you to make a (minor) code change in Unreal Build Tool (UBT).

Setting up the Toolchain

If you want to set up a toolchain from your Windows (host) computer to target any of the aforementioned platforms, you'll have to download the toolchain and set your system's environment variable to package your application for Linux and ARM based environments. If this is your first time packaging UE4 projects for the Linux platform, you'll also have to build the engine in Visual Studio for Linux. After working through the following steps, your host environment will be set up to target any of the currently supported platforms.

Please make sure that you have a reliable Internet connection prior to following these steps. Depending on the speed of your Internet connection, downloading the toolchain can take anywhere from a few minutes to a few hours.

Downloading the Toolchain

  1. Please download the cross-toolchain appropriate for your engine version.

  2. Now, create a new folder, naming it Linux_CrossCompileToolChain.

    Click for full image.

    If you're using a different naming convention, substitute your preferred folder name with the one we've chosen for illustrative purposes.

  3. Extract the toolchain, being sure to set the extracted file's destination to the folder that you created in the previous step.

    LinuxXC_Step3.png

    Click for full image.

  4. Open the [ROOT]/Linux_CrossCompileToolChain/v8_clang-3.9.0-centos7 folder to view the extracted files.

    Click for full image.

    Supported Platforms

    Refer to the following table to download the appropriate toolchain for your version of UE4:

    Architecture

    Sub-Architecture

    Vendor

    System

    Application Binary Interface (abi)

    AArch64

    N/A

    Unknown

    Linux

    gnueabi

    ARM

    N/A

    Unknown

    Linux

    gnueabihf

    i686

    N/A

    Unknown

    Linux

    gnu

    x86_64

    N/A

    Unknown

    Linux

    gnu

    Please note that we haven't yet added Engine libraries for the i686 platform.

Setting the Environment Variable

  1. Prior to setting the LINUX_MULTIARCH_ROOT environment variable, double-click the Setup batch file (Setup.bat) to output the appropriate environment variable settings for your computer.

    Click for full image.

  2. At this point, a new OutputEnvVars text file should be located inside of the v8_clang-3.9.0-centos7 folder.

    Click for full image.

    The OutputEnvVars.txt file contains useful information for setting your system's environment variable.

  3. Press the Windows Key together with the Pause Break Key to open the System Information menu. Now, click the Advanced System Settings link to open the Advanced sub-menu, which is located in the System Properties menu.

    Click for full image.

  4. Now, click the Environment Variables... button.

    LinuxXC_Step9.png

  5. To add a new System Variable, click the New... button under the System variables list.

    LinuxXC_Step10.png

    If you haven't opened OutputEnvVars.txt yet, please do so before moving onto the next step.

    Click for full image.

  6. After the New System Variable dialog menu opens, copy the LINUX_MULTIARCH_ROOT environment variable setting into the text boxes for the New System Variable dialog.

    Click for full image.

  7. After returning to the Evironment Variables menu, click the Ok button to save the LINUX_MULTIARCH_ROOT environment variable.

    LinuxXC_Step14.png

    Please note that if you already have the LINUX_ROOT environment variable set, you don't need to delete it because the engine will prioritize LINUX_MULTIARCH_ROOT over LINUX_ROOT during the packaging process.

  8. Now, click the OK button to close the System Properties menu.

    LinuxXC_Step15.png

    Now that you've added a new Environment Variable to your system, you'll need to close and restart all currently running instances of Visual Studio and Command Prompt.

Setting up the Linux Build Configuration

If you've never packaged a project for Linux before, you'll want to follow these steps.

  1. Opening the Command Prompt, run [UE4 ROOT]/Setup.bat to check for, update, and install prerequisite dependencies for building UE4 from Visual Studio.

    LinuxXC_Step17.png

  2. Run [UE4 ROOT]/GenerateProjectFiles.bat to set up the project files for UE4.

    LinuxXC_Step18.png

    GenerateProjectFiles.bat must be run inside of the root folder that UE4 resides in ([UE4 ROOT]). If you run the batch file with Unreal Game Sync , Linux won't show up as a valid Build Configuration inside of Visual Studio.

  3. Navigating to [UE4 ROOT], double-click UE4.sln to open the UE4 solution in Visual Studio.

    Click for full image.

  4. If you haven't built UE4, go ahead and press the F5 key to build and run UE4 from Visual Studio.

    Click for full image.

  5. Now, stop running the engine, and go back to Visual Studio to select the Linux solution platform in Visual Studio. You can build for Linux by pressing the following keyboard combination: Ctrl+Shift+B.

    Click for full image.

    At this point, you should see the toolchain being displayed inside of Visual Studio's Output Window.

    Click for full image.

Targeting Specific Platforms

Because version 4.14 can only target the x86_64 platform, the following section is intended for developers working with version 4.15.

If you'd like your project to target a specific platform, you'll need to edit your project's Default Engine Configuration File file. To do so, navigate to the file's location ([Project Directory]\Config) and open DefaultEngine.ini to add the following lines:

[/Script/LinuxTargetPlatform.LinuxTargetSettings]
TargetArchitecture=X86_64UnknownLinuxGnu

Feel free to set TargetArchitecture to any of the following values:

  • X86_64UnknownLinuxGnu

  • ArmUnknownLinuxGnueabihf

  • AArch64UnknownLinuxGnueabi

End Result

Congratulations! Moving forward, you should be able to see the cross-compile toolchain being used while packaging your project for Linux.

Click for full image.

Tags