Skip to content

Latest commit

 

History

History
116 lines (71 loc) · 12.5 KB

mitigations.md

File metadata and controls

116 lines (71 loc) · 12.5 KB
Raw

Mitigations for Known Issues

This page lists known issues that can occur when building and running Unreal Engine under Wine, along with the mitigations for these issues that are automatically applied when building a container image for Epic's patched version of Wine.

Contents

Issues that interfere with compiling native code

Visual Studio telemetry uploader crashes intermittently

Issue: when compiling native C++ code with MSVC, a child process called vctip.exe is launched automatically to submit telemetry data to Microsoft. Under Wine, the upload process will sometimes fail and print a stack trace indicating a failure in the Microsoft.VisualStudio.Telemetry.TelemetrySession.DisposeToNetworkAsync function. This crash can sometimes be detected as a compilation failure, despite being unrelated to the success or failure of the MSVC parent process.

Despite not interfering with the compilation of C++ code itself, this issue can nonetheless lead to spurious reports of failure when building Unreal Engine's C++ code.

Mitigation: since Visual Studio telemetry submission is entirely optional and this issue only occurs due to telemetry being enabled by default, the mitigation is to simply opt-out by setting the registry keys listed on the Visual Studio Customer Experience Improvement Program page of the Visual Studio documentation. Note that although the Registry settings section of that page indicates that 64-bit environments should only configure a registry key for use by 32-bit applications, it is typically necessary to configure the equivalent key for 64-bit applications as well.

When building a container image, this mitigation is applied by running the following commands:

# Set the Visual Studio telemetry opt-out value for 64-bit applications
wine64 reg add "HKLM\\SOFTWARE\\Microsoft\\VSCommon\\17.0\\SQM" /f /v "OptIn" /t REG_DWORD /d 0

# Set the Visual Studio telemetry opt-out value for 32-bit applications
wine64 reg add "HKLM\\SOFTWARE\\Wow6432Node\\Microsoft\\VSCommon\\17.0\\SQM" /f /v "OptIn" /t REG_DWORD /d 0

Issues that interfere with building modern .NET projects

The overwhelming majority of Unreal Engine's C# tooling targets the modern, cross-platform .NET 5+. The issues listed below interfere with building these .NET projects unless the accompanying mitigations are applied.

.NET code compilation fails when building in parallel

Issue: by default, the dotnet build command will build .NET projects and their dependencies in parallel when running in environments where multiple CPU cores are available. Under Wine, parallel builds may fail silently, reporting success but producing no build outputs.

This issue can prevent all of Unreal Engine's .NET tooling from being built.

Mitigation: .NET builds will work correctly when parallel builds are disabled by setting the BuildInParallel MSBuild property to false. The default behaviour can be overridden automatically for all builds by utilising a custom .props file, as described in the Customize your local build and Customize all .NET builds pages of Microsoft's MSBuild documentation.

When building a container image, this mitigation is applied by creating a file named Custom.After.Microsoft.Common.Props in the %LOCALAPPDATA%\Microsoft\MSBuild\Current\Imports\Microsoft.Common.props\ImportAfter directory, with the following contents:

<Project>
	<PropertyGroup>
		<BuildInParallel>false</BuildInParallel>
		<StopOnFirstFailure>true</StopOnFirstFailure>
	</PropertyGroup>
</Project>

NuGet signed-package verification fails when running dotnet restore

Issue: when running under Windows or Wine, the dotnet restore command will unconditionally enable NuGet signed-package verification during package restore operations, and this step cannot be disabled. The verification process relies on trusted root certificates for code signing and timestamping, which are bundled with the .NET SDK starting in version 6.0.400. However, the bundled certificate trust list files are only used as a fallback under Linux and macOS, and under Windows or Wine the verification process expects the root certificates to be present in the Windows root certificate store. Under Wine, attempts to access the Windows root certificate store will be routed to the certificate store of the underlying Linux host system, and if the required root certificates are not present then package verification will fail.

This issue prevents all of Unreal Engine's .NET tooling that uses NuGet packages from being built.

Mitigation: to allow package verification to succeed, it is necessary to add the NuGet code signing and timestamping root certificates to the Linux host system's certificate store. The two required certificate trust list files can be obtained from the trustedroots directory of the .NET SDK repository on GitHub:

The exact mechanism for adding these to the host system's certificate store varies between different Linux distributions. Under Debian-based distributions such as Ubuntu, place the certificate trust list files in the /usr/local/share/ca-certificates directory (making sure to rename them so they have a .crt file extension) and run the update-ca-certificates command.

Issues that interfere with building legacy .NET Framework projects

A tiny subset of Unreal Engine's C# tooling still targets the older, Windows-specific .NET Framework. The issues listed below interfere with building these .NET Framework projects unless the accompanying mitigations are applied.

The Visual Studio version of MSBuild fails to build .NET Framework projects under Mono

Issue: the version of MSBuild distributed with Visual Studio 2022 fails to build .NET Framework projects when running in a Wine environment that uses Wine Mono to run .NET Framework applications rather than the Microsoft implementation of the .NET Framework. Some build tasks fail to run, ostensibly due to mismatches between the actual and expected types of their input or output parameters:

C:\BuildTools\Common7\IDE\CommonExtensions\Microsoft\NuGet\NuGet.targets(994,7): error MSB4028: The "GetRestoreProjectReferencesTask" task's outputs could not be retrieved from the "RestoreGraphItems" parameter. Specified cast is not valid.

This issue prevents all of Unreal Engine's .NET Framework tooling from being built.

Mitigation: although it is possible to mitigate this issue by installing the proprietary Microsoft implementation of the .NET Framework under Wine via the Winetricks verb dotnet48, this solution is potentially problematic due to licensing restrictions. The preferred mitigation is to instead install the Windows release of the upstream Mono project, which has shipped with a copy of MSBuild since version 5.0.0. The version of MSBuild that is shipped with Windows releases of Mono does not suffer from the type mismatch issue, although it does introduce the issue The Mono version of MSBuild fails to generate executable manifest files for .NET Framework projects, which is described in the section below.

When building a container image, this mitigation is applied by installing the Windows release of the upstream Mono project, alongside the Wine Mono fork that provides functionality for running .NET Framework applications. Note that unlike upstream Mono, the Wine Mono fork does not ship with a copy of MSBuild, so it is necessary to install both.

The Mono version of MSBuild fails to generate executable manifest files for .NET Framework projects

Issue: the version of MSBuild that is shipped with Windows releases of Mono fails to generate executable manifest files when building .NET Framework projects, and reports errors when attempting to copy missing manifest files to project output directories:

C:\Program Files\Mono\lib\mono\msbuild\15.0\bin\Microsoft.Common.CurrentVersion.targets(5073,5): error MSB3030: Could not copy the file "obj\Development\SwarmCoordinator.exe.manifest" because it was not found.

Of the small number of Unreal Engine C# projects that target the .NET Framework, only a handful of those set the GenerateManifests MSBuild property to true and trigger this error. This issue prevents those projects from being built.

Mitigation: .NET Framework builds will work correctly if the GenerateManifests MSBuild property is overridden with a value of false. The value can be overridden automatically for all builds by utilising a custom .props file, as described in the Customize your local build and Customize all .NET builds pages of Microsoft's MSBuild documentation.

When building a container image, this mitigation is applied by creating a file named Custom.After.Microsoft.NETFramework.Props in the %LOCALAPPDATA%\Microsoft\MSBuild\Current\Microsoft.NETFramework.props\ImportAfter directory, with the following contents:

<Project>
	<PropertyGroup>
		<GenerateManifests>false</GenerateManifests>
	</PropertyGroup>
</Project>

Note that this custom .props file will only be loaded when building .NET Framework projects, and does not affect the build process for .NET 5+ projects. The version of MSBuild that is shipped with Windows releases of Mono does not load the custom .props file from the mitigation for the issue .NET code compilation fails when building in parallel, so the configuration overrides intended for .NET 5+ projects will also not affect the build process for .NET Framework projects.