Project Files for IDEs

The following guide is meant for users who've downloaded and built UE4 from its source code, which we've made available on GitHub.

If you download the latest Unreal Engine 4 (UE4) code, you might notice that there are no Visual Studio (VS) or Xcode project files included for compiling and running the engine or example games. You will need to run a script that generates project files for you to load:

• Run the GenerateProjectFiles.bat file which is located in the main UE4 directory

  You can run that script from any folder.

• The project generator tool will analyze the module and target build files and generate new project files. This can take up to 15 seconds or so.

For VS developers, this will generate a UE4.sln file in the same directory. You will use this solution file to build and run UE4 games and programs. For your first time compiling, we recommend building using the Development configuration with Win64 platform.

By default, we generate buildable projects for all available platforms that we detected SDKs for, so that you will be able to build and debug console and mobile platforms as well. If you want to generate projects only for the current platform you are running on (for example, Windows.), run the GenerateProjectFiles.bat with the -CurrentPlatform argument. The project files will be a little lighter.

Important: Remember to re-run GenerateProjectFiles.bat after syncing new code changes from source control. If you forget to do this, you will most likely run into problems when compiling or running your game.

If you make local changes to modules such as adding or removing source files, you should re-run GenerateProjectFiles.bat again. We do not recommend manually making changes to project files.

Integration With UnrealVS Extension

The UnrealVS Extension for VS includes a tool-bar button that you can click to re-generate project files for the currently loaded solution.

You can also bind a shortcut key to this feature. In VS, open Tools -> Options -> Environment -> Keyboard, then search for UnrealVS.RefreshProjects.

Note that this feature is only enabled after you have a solution loaded (because the tool needs to know which code branch to generate projects for.) If you have no UE4.sln file generated yet, you will need to run the GenerateProjectFiles.bat script directly first.

Command-line Options (Advanced)

The project generator has some optional command-line arguments that you can use if you want to customize your generated project files to suit your needs more closely. Typically these options are not required or recommended.

Frequently Asked Questions

Why are newly-added source files compiled even though I did not update project files?

The UE4 build system does not actually require project files to compile the code. Unreal Build Tool always locates source files using module and target build files. For this reason, if you add a new source file and trigger a compile, the new source file may be included in the build even though the project files have not been refreshed yet. Just something to keep in mind.

Where are the actual projects saved to?

For VS projects, the generated solution file is UE4.sln and is saved to the root UE4 directory. However, the project files are saved to the /UE4/Engine/Intermediate/ProjectFiles/ directory. It is safe to delete these files at any time and regenerate projects, however you may lose certain project-specific preferences such as command-line argument strings if you delete these files.

What are the advantages of generating project files?

There are certainly both pros and cons, but here are some important reasons why we decided to generate project files for UE4:

• UE4 is designed to work with many platforms, but different teams may only be working with a few specific platforms at any time. By generating project files, we can omit platform-specific files and build configurations that are not relevant.

• UE4 programming methodology incorporates many sub-modules, and it was very important that we made it as easy as possible for programmers to add new modules.

• The project generator emits highly-accurate definitions and includes paths which are used by VS IntelliSense while you are working in UE4 code.

• Setting up a new project is much easier when project files are automatically generated.

• We want to support multiple platforms and development environments (for example, VS and Xcode.) Hand-maintaining multiple sets of project files is error-prone and tedious.

• We wanted to enable programmers to generate highly customized project files. We expect, over time, this to become even more important.

• The directory structure of source files is automatically mirrored in the project file solution hierarchy. This is really convenient when browsing source files, but was difficult to maintain with hand-authored projects.

• UE4 build configurations are very complex and are difficult to hand-maintain. The project generator makes this nearly transparent to developers.

What are all of these other files doing in the project?

Along with source code for C++ modules, we automatically add several other files to the generated projects. This is just to make it easy to locate these files when doing searches. Some examples of other files that are added to the generated projects:

• Shader source code (*.usf files)

• Engine documentation files (*.udn files)

• Program configuration files (*.ini files)

• Localization files (*.int files)

• Program resource files and manifests (*.rc, .manifest)

• Certain external (non-generated) project files (e.g. UnrealBuildTool, Clean)

Why are there no project files checked in to source control?

Merging source control conflicts to project files was tedious and highly error-prone. The new system avoids this entirely by treating project files as pure intermediates. Plus, solution files will be different for each team that is working on different game projects. Chances are that the project files that we use at Epic will not be useful to other teams without modifications.

What does `GenerateProjectFiles.bat` actually do?

This script is a simple wrapper around Unreal Build Tool, which is launched in a special mode that builds project files instead of building program executables. It invokes Unreal Build Tool with the -ProjectFiles command-line option.

I am making changes to the project generator code. How do I debug it?

• Change your startup project to UnrealBuildTool.

• Set the command-line parameters for debugging to: -ProjectFiles

• Set the working directory to your local path for: [Your UE4 Directory]/Engine/Source/

• Compile and debug as per normal.

Be aware that the project generator may clobber the project files you are using in VS as you are working. For this reason, it is sometimes useful to load the UnrealBuildTool project directly into VS instead of debugging through the regular UE4 solution file.

How do I build multiple configurations at the same time?

You can use the Batch Build feature in VS. You can find this under the Build menu. Simply select all of the configurations that you want to compile and click Build. We are looking at ways to make this interface much easier to work with in the future.