Unreal Engine game development Linux pitfalls & resolutions

Unreal Engine its support for working and building for Linux is ‘lacking’ to say the least. Not only in the documentation about the tools that now have to be run manually from the commandline; generally what is and which features are not supported and common issues and resolutions are at least for Linux barely documented. So I will list some of the problems I have encountered and how to resolve them. Resolving all these problems will make creating a cross-platform game, using the UE4Editor on Linux and creating binary releases for distribution possible.

Index

Building the Unreal Engine from source

Linux users will not be met with friendly binary distributions such as .deb packages. Instead the Unreal Engine has to compiled from source in order to have it operate on Linux. Luckily the actual compilation of the Unreal Engine from source is very well covered for every platform it supports. Building unreal engine from source

In short these steps should work on most systems but you do have to register your github account with the EpicGames team.

File, Class and include capitalization

Typically problem with File, Class or include capitalization can be recognized by errors such as:

UnrealBuildTool Exception: Expecting to find a type to be declared in a target rules named ‘ProjectNameTarget’

fatal error: ‘projectname.h’ file not found

If you generate a Uproject on Windows which includes a capital in a name and then want to work on this project on Linux then you are in for a bad time. The project will generate source files which will include capitals, however the class and include declarations inside of these source files will not. On a case sensitive operating system such as Linux this will cause the UnrealBuildTool to fail and after that file inclusion to fail. The only way to resolve the problem is to add the capitals to all the filenames and includes manually.

Recommendation: Open the ProjectName.Target.cs and ProjectNameEditor.Target.csfiles; These are located in the Source folder of the project. When opened capitalize the class names in correspondence to the capitals in the file name. For example changing public class projectnameTarget : TargetRules into public class ProjectNameTarget : TargetRules.

From within the same Source folder open the folder matching the name of the project; inside of it should exist a file with the same name as the project, this file should have a .cpp file extension. Open this file in a text editor and look for the #include statement at the top of the file. Make sure the name referenced in the #include statement matches the actual filename. For instance changing #include "projectname.h" into #include "ProjectName.h".

In total the following files should be changed, all the exact matches of ‘projectname’ should of course reflect the name of your own Uproject:

Source/projectname.target.cs

Source/projectnameEditor.target.cs

Source/projectname/projectname.cpp

Path spaces

In typical bad Linux support fashion both the path of the UnrealEngine or the path leading up to the Uproject file cannot contain any spaces. If it contains any you will have to remove them, moving the path of the UnrealEngine means that the UnrealBuildTool needs to be rerun on the Uproject since the references to the Engine location are hardcoded into the CMakeLists.txt and MakeFile files. To rerun the UnrealBuildTool simply use the GenerateProjectFiles.sh command as listed below.

Generate project files on Linux

This command generates the necessary CmakeLists.txt and MakeFile files to compile the project, it will be necessary to run this command if the Uproject file was originally generated on Windows. After generation use the UnrealBuildTool to compile the project, this command has to be run from the root folder of the Unreal Engine source after the engine has been compiled. It can only successfully run if problems around capitalization or path spaces have been resolved.

After GenerateProjectFiles.sh has successfully completed the source files used in the Uproject can be compiled, in order to have the compiled code reflected in the Unreal Editor the right build target has to be chosen. The MakeFile lists around 150 different build targets so picking the right one can be challenging. The right build target will always be the project name appended with ‘Editor’. For example ProjectNameEditor.

user@device:~/path/to/ProjectName$ make ProjectNameEditor

Compiling for release

Luckily once the UE4Editor can be opened with the proper generated project files life using Linux with Unreal Engine becomes easier. This following video demonstration shows in clear detail how to compile a successful release.

References

Even though the majority of information was not determined from the Unreal Engine documentation; since it is simply not present in the documenation, These references may still contain valuable information as to understanding projectsfiles, buildsystems and compilation regarding the Unreal Engine.