Cross-Compiling for Linux


LinuxXC_Banner.png

Note: If you are developing your project with Unreal Engine, version 4.13 (or older), refer to the 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:

UE4 Version

Toolchain

4.22

-v13 clang-7.0.1-based

Note: With this toolchain, there is no need to extract files or set the environment variable, just run the installer package.

4.21

-v12 clang-6.0.1-based

4.19 and 4.20

-v11 clang-5.0.0-based

4.18

-v10 clang-5.0.0-based

4.16 and 4.17

-v9 clang-4.0.0-based

4.14 and 4.15

-v8 clang-3.9.0-based

4.11 thru 4.13

-v7 clang-3.7.0-based

4.9 and 4.10

-v6 clang-3.6.0-based

4.8 and earlier

-v4 clang-3.5.0-based

Note: The Setup and UnSetup Windows Batch Files (*.bat) are not included in -v9 because you only need these files if you're setting up AutoSDKs for UE4. Setup.bat and Unsetup.bat were included in previous versions of the toolchain because they're part of the AutoSDKs system (which is currently not documented).

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 UnrealBuildTool (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. After working through the following steps, your host environment will be set up to target any of the currently supported platforms.

Note: 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.
    LinuxXC_Step2.png
    Note: If you're using a different naming convention, make sure that your preferred folder name does not contain any whitespace characters.
  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
  4. Open the [ROOT]/Linux_CrossCompileToolChain/v11_clang-5.0.0-centos7 folder to view the extracted files.

    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
    Note: Please note that we haven't yet added Engine libraries for the i686 platform.

Targeting Specific Platforms

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

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

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.
    LinuxXC_Step5.png
  2. At this point, a new OutputEnvVars text file should be located inside of the v8_clang-3.9.0-centos7 folder.
    LinuxXC_Step6.pngThe 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.
    LinuxXC_Step8.png
  4. Now, click the Environment Variables... button.  
  5. To add a new System Variable, click the New... button under the System variables list.  

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

  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.
    Step11_LinuxXC.png
  7. After returning to the Evironment Variables menu, click the Ok button to save the LINUX_MULTIARCH_ROOT environment variable.  

    Note: 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.  
    Note: After adding the Environment Variable, go ahead and save your work before restarting Windows.

Troubleshooting Step

To verify your current setup, run %LINUX_MULTIARCH_ROOT%x86_64-unknown-linux-gnu\bin\clang++ -v from the Command Prompt. If the Command Prompt displays "clang version X.X.X ..." (see below), you can work on the next section. 

env_var_clangsampleflush.png

If your system cannot find the specified path, you should carefully redo the steps in this section before moving on.

Packaging Projects for Linux

After downloading the toolchain and setting your system's environment variable, you are ready to start packaging your project for the Linux platform. You can package your project from either the Launcher or the Source Build of the engine, so keep reading to learn more about each of these packaging workflows.

From a Launcher Build

To package a project from a Launcher Build of UE4:

Required Step

If you are using the Launcher Build workflow, follow these steps to download the required Linux Target Platform files:

  1. From the Launcher, click the down arrow next to the engine version's Launcher button.
    PackagePrereq0.png
  2. Click the Options button.
    PackagePrereq1.png
  3. Select the Target Platforms > Linux option (1) before clicking Apply (2).

    PackagePrereq2-1.png

Packaging Steps

  1. From the Editor, open File > Package Project and select Linux.
    Click for full image.
  2. If you haven't already done so, create a new folder (for example, "Linux" can be its name), select it (1) and click the Select Folder button (2).
    PackageProject2.png
    Note: This folder serves as your project's Staging Directory. To update your project's Staging Directory, open File > Package Project, select the Packaging Settings... button (1), and update the Staging Directory field (2) in the Project - Packaging menu.
    Click for full image.
  3. At this point, the Editor will use the toolchain to package your project for Linux.
    Note: If the toolchain was not downloaded or if you did not set your system's environment variable correctly, the Editor won't package your project. Otherwise, if you set everything up correctly, the Editor will take a few minutes to complete the packaging process.
    PackageFlow.png
  4. After the Editor finishes packaging your project, navigate to your project's Staging Directory (1) to verify that all of the packaged content (2) was generated.
    PackageProject6.png 

Section Result

By now, you should be able to run your packaged project in Linux.

PackageProject_SectionResult.png

Note: If you aren't able to run your project's *.sh script, you may need to chmod +x the file to execute it.

PackageProjectExec.png

From a Source Build

To package a project from a Source Build of UE4:

  1. Open 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-1.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. Navigate to [UE4 ROOT] and double-click UE4.sln to open the UE4 solution in Visual Studio.
    LinuxXC_Step19-1-1.png
  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.

Section Result

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

Click for full image.