Git clean while there is a C++ error leaves project in irrecoverable state

Summary

Doing a git clean, git clone, non-git fresh VCS checkout, or manual clean of an Unreal project while there is a compile error in a C++ file leaves the project essentially permanently broken, because the project file cannot open without first compiling the C++ file but the user cannot see the C++ error or compile the project themselves without opening the project file.

Configuration

For the following, I am running Unreal Editor 4.18.0-3709383+++UE4+Release-4.18 on Mac OS X 10.12.6 (16G29) with XCode 9.1 (9B55) as my Source Code Editor.

Reproduction steps:

  • Create an Unreal project named CppContentsTest.
  • Create one C++ file named “TestClass”.
  • Into TestClass::TestClass(), insert the letters xyyz. This is a syntax error, which you can confirm by building.
  • git init && git add CppContentsTest.uproject && git add Source && git add Config && git commit -m "Initial"
  • Close Xcode and Unreal Editor.
  • git clean -xffd. This removes Binaries/, Content/ (empty), CppContentsTest.xcworkspace/, Intermediate/, and Saved/.
  • Reopen Unreal Editor and open the CppContentsTest project.

Observed behavior

Unreal Editor tells me a dylib is missing and asks if I would like to rebuild it. If I say “no”, Unreal Editor closes. If I say “yes”, it begins building. During this step a helpful progress bar and log window are displayed:

When the file completes, however, the log window is removed and this lone, unhelpful dialog box appears:

Clicking “OK” closes Unreal Editor.

The problem

The dialog box states the code “could not be compiled”, but does not show the error that prevented it from being compiled. It further instructs the user to compile the code manually, but at this point the user cannot compile the code because the xcworkspace file has been deleted. The only way to get into XCode and see the error is to open Unreal Editor and choose “Open XCode”— but the user cannot open Unreal Editor, because of the “could not be compiled” dialog. The user is being required to fix a problem they cannot see, related to a project they cannot build. The user is stuck.

I think there might be a way to get unstuck here by running UnrealBuildTool.exe at the command line, but the average user would not know how to do this. This appears to be a recurring problem for people on Unreal Answers. One answer given by Unreal support staff suggests “right-clicking (ctrl+click) on the .uproject file and selecting Generate Xcode Project” but first off, this is difficult to discover (I usually open Unreal projects using Epic Games Launcher, not the Finder) and second off, when I do this on my personal copy of Unreal with the CppContentsTest project it does not work— it prints the error message /Users/Shared/Epic Games/UE_4.18/Engine/Binaries/ThirdParty/Mono/Mac/lib/mono/4.5/Microsoft.Common.targets: error : Error executing task GetReferenceAssemblyPaths: Method 'Array.Empty' not found. and does not create a project.

Expected behavior

I do not need support on this issue (I got my project “broken” by a git clean in this way, but got lucky and was able to find the error by eyeballing the code). However I think it would be a better experience for developers if the “Try rebuilding from source manually” dialog would either:

  1. Have a button for “Show Log” which shows the log from the “Starting build…” window, which I assume would have contained the error message if it did not close so quickly;

  2. Have a button for “Open XCode” which generates the XCode file and opens it; and/or

  3. Allow me to proceed to the project in the editor with the C++ dylib not loaded, so I can Open XCode myself.

I assume there is some technical reason you do not do (3), but I think (1) and (2) are surely possible.