bSaveSymbols

bSaveSymbols

#Overview

name: bSaveSymbols

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 2 C++ source files. Also referenced in 3 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C# source code and build system

The purpose of bSaveSymbols is to control whether symbol files are saved during the build process for Android platforms in Unreal Engine 5. Symbol files contain debugging information that can be useful for troubleshooting and crash analysis.

This setting variable is primarily used in the Android-specific build and deployment systems of Unreal Engine. Based on the callsites, it’s referenced in the AndroidPlatform.Automation.cs and UEDeployAndroid.cs files, which are part of the Android platform support in Unreal Engine.

The value of this variable is set in the Android Runtime Settings, specifically in the “/Script/AndroidRuntimeSettings.AndroidRuntimeSettings” section of the project’s configuration files.

This variable interacts with other variables, particularly:

  1. bBuildWithHiddenSymbolVisibility
  2. Configuration (specifically checking for UnrealTargetConfiguration.Shipping)

Developers must be aware that:

  1. When bSaveSymbols is true, the build process will save symbol files separately.
  2. In Shipping configuration, symbols may be saved even if bSaveSymbols is false, if bBuildWithHiddenSymbolVisibility is true.
  3. Saving symbols can increase build time and storage requirements but is valuable for debugging.

Best practices when using this variable include:

  1. Enable it during development and testing phases to aid in debugging.
  2. Consider disabling it for final release builds to reduce package size, unless you need to debug production issues.
  3. Always use it in conjunction with crash reporting systems for easier issue resolution.

Regarding the associated variable bBuildWithHiddenSymbolVisibility:

The purpose of bBuildWithHiddenSymbolVisibility is to control whether symbols are built with hidden visibility for Android platforms. This affects how symbols are exposed in the compiled binaries.

This variable is also used in the Android build system, specifically in the UEDeployAndroid.cs file.

Like bSaveSymbols, its value is set in the Android Runtime Settings section of the project’s configuration.

It interacts with bSaveSymbols and the build Configuration, particularly affecting behavior in Shipping builds.

Developers should be aware that:

  1. This setting can affect the size and performance of the final binary.
  2. It’s particularly important for Shipping builds, where it can trigger symbol saving even if bSaveSymbols is false.

Best practices include:

  1. Generally, keep this enabled for better binary security and smaller size.
  2. Consider the implications on debugging and crash analysis when using this in conjunction with bSaveSymbols.
  3. Test thoroughly with this setting enabled before final releases to ensure it doesn’t interfere with required functionality.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3075, section: [/Script/AndroidRuntimeSettings.AndroidRuntimeSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/Android/AndroidTargetPlatformControls/Private/AndroidTargetPlatformControls.h:114

Scope (from outer to inner):

file
class        class FAndroidTargetPlatformControls : public TNonDesktopTargetPlatformControlsBase<FAndroidPlatformProperties>
function     virtual void GetBuildProjectSettingKeys

Source code excerpt:

		InBoolKeys.Add(TEXT("bBuildForArm64"));	InBoolKeys.Add(TEXT("bBuildForX8664"));
		InBoolKeys.Add(TEXT("bBuildForES31")); InBoolKeys.Add(TEXT("bBuildWithHiddenSymbolVisibility"));
		InBoolKeys.Add(TEXT("bSaveSymbols")); InStringKeys.Add(TEXT("NDKAPILevel"));
	}

	virtual bool ShouldExpandTo32Bit(const uint16* Indices, const int32 NumIndices) const override;
	//~ End ITargetPlatform Interface

	virtual void InitializeDeviceDetection();

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Classes/AndroidRuntimeSettings.h:461

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	// Always save .so file with symbols allowing use of addr2line on raw callstack addresses.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = AdvancedBuild, meta = (DisplayName = "Always save a copy of the libUnreal.so with symbols. [Experimental]"))
	bool bSaveSymbols;

	// Strip shader reflection information under Android to avoid issues on older drivers
	UPROPERTY(config, EditAnywhere, Category = AdvancedBuild, meta = (
	DisplayName = "Strip shader reflection information",
	ToolTip = "If true, strip shader reflection information under Android",
	ConfigRestartRequired = true))

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/AutomationTool/Android/AndroidPlatform.Automation.cs:933

		ConfigHierarchy Ini = ConfigCache.ReadHierarchy(ConfigHierarchyType.Engine, DirectoryReference.FromFile(SC.RawProjectPath), SC.StageTargetPlatform.PlatformType);
		bool bSave = false;
		return (Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bSaveSymbols", out bSave) && bSave);
	}

	private bool GetEnableBundle(DeploymentContext SC)
	{
		ConfigHierarchy Ini = ConfigCache.ReadHierarchy(ConfigHierarchyType.Engine, DirectoryReference.FromFile(SC.RawProjectPath), SC.StageTargetPlatform.PlatformType);
		bool bEnableBundle = false;

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Android/UEDeployAndroid.cs:5247


				Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bBuildWithHiddenSymbolVisibility", out bBuildWithHiddenSymbolVisibility);
				Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bSaveSymbols", out bSaveSymbols);
				bSaveSymbols = true;
				if (bSaveSymbols || (Configuration == UnrealTargetConfiguration.Shipping && bBuildWithHiddenSymbolVisibility))
				{
					// Copy .so with symbols to 
					int StoreVersion = GetStoreVersion(bEnableBundle ? null : Arch);
					string SymbolSODirectory = Path.Combine(DestApkDirectory, ProjectName + "_Symbols_v" + StoreVersion, ProjectName + Arch);

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Android/UEDeployAndroid.cs:4758

					bool bSaveSymbols = false;
					Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bBuildWithHiddenSymbolVisibility", out bBuildWithHiddenSymbolVisibility);
					Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bSaveSymbols", out bSaveSymbols);
					if (bSaveSymbols || (Configuration == UnrealTargetConfiguration.Shipping && bBuildWithHiddenSymbolVisibility))
					{
						// Copy .so with symbols to 
						int StoreVersion = GetStoreVersion(bEnableBundle ? null : Arch);
						string SymbolSODirectory = Path.Combine(DestApkDirectory, ProjectName + "_Symbols_v" + StoreVersion + "/" + ProjectName + Arch);
						string SymbolifiedSOPath = Path.Combine(SymbolSODirectory, Path.GetFileName(SourceSOName));