bBuildWithHiddenSymbolVisibility

bBuildWithHiddenSymbolVisibility

#Overview

name: bBuildWithHiddenSymbolVisibility

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 4 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C# source code and build system

The purpose of bBuildWithHiddenSymbolVisibility is to control symbol visibility in the compiled Android binaries, specifically for the Shipping configuration. This setting is related to the build process and affects how symbols are handled in the final executable.

This setting variable is primarily used by the Android-specific subsystems of Unreal Engine, including the Android platform support in the Unreal Build Tool (UBT) and the Android deployment process.

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, notably:

  1. bSaveSymbols - Another boolean setting in the Android Runtime Settings
  2. Configuration - The build configuration (e.g., Shipping, Development)

Developers must be aware of the following when using this variable:

  1. It only takes effect in the Shipping configuration.
  2. When enabled, it affects the symbol visibility in the compiled binaries, which can impact debugging and crash reporting.
  3. It’s used in conjunction with bSaveSymbols to determine whether to save symbol files separately.

Best practices when using this variable include:

  1. Carefully consider the implications on debugging and crash reporting before enabling it.
  2. Ensure that the bSaveSymbols setting is configured appropriately in conjunction with this setting.
  3. Test the application thoroughly in Shipping configuration when changing this setting to ensure it doesn’t negatively impact crash reporting or performance.

The associated variable bSaveSymbols is also important in this context. The purpose of bSaveSymbols is to control whether symbol files are saved separately during the Android build process. This variable is used in conjunction with bBuildWithHiddenSymbolVisibility to determine how symbols are handled.

bSaveSymbols is also set in the Android Runtime Settings, in the same section as bBuildWithHiddenSymbolVisibility.

When bSaveSymbols is true, or when the configuration is Shipping and bBuildWithHiddenSymbolVisibility is true, the build process will save symbol files separately. This allows for better debugging and crash reporting while potentially reducing the size of the main executable.

Developers should be aware that saving symbols separately can increase build times and storage requirements but can be crucial for effective debugging and crash analysis in production environments.

Best practices for bSaveSymbols include:

  1. Enable it for development and testing builds to facilitate debugging.
  2. Consider the trade-offs between executable size, build time, and debugging capabilities when deciding whether to enable it for Shipping builds.
  3. Ensure you have a system in place to manage and store the separate symbol files if you enable this option.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3074, 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:113

Scope (from outer to inner):

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

Source code excerpt:

		OutSection = TEXT("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings");
		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

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

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	// Build the shipping config with hidden visibility by default. Results in smaller .so file but will also removes symbols used to display callstack dumps.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = AdvancedBuild, meta = (DisplayName = "Build with hidden symbol visibility in shipping config."))
	bool bBuildWithHiddenSymbolVisibility;

	// Disables extra checks for buffer overflows, comes with perf improvement, but might make tracing stack corruptions in production harder. Note that _FORTIFY_SOURCE=2 is still enabled by the toolchain providing lightweight stack checks
	UPROPERTY(GlobalConfig, EditAnywhere, Category = AdvancedBuild, meta = (DisplayName = "Disable extra checks for buffer overflows"))
	bool bDisableStackProtector;

	// Disable libc++_shared dependency validation in all .so files linked with libUnreal.so

#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:926

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

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

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Android/AndroidToolChain.cs:265

			ConfigHierarchy Ini = ConfigCache.ReadHierarchy(ConfigHierarchyType.Engine, DirectoryReference.FromFile(ProjectFile), UnrealTargetPlatform.Android);
			bool bBuild = false;
			return CompileEnvironment.Configuration == CppConfiguration.Shipping && (Ini.GetBool("/Script/AndroidRuntimeSettings.AndroidRuntimeSettings", "bBuildWithHiddenSymbolVisibility", out bBuild) && bBuild);
		}

		private bool DisableFunctionDataSections()
		{
			ConfigHierarchy Ini = ConfigCache.ReadHierarchy(ConfigHierarchyType.Engine, DirectoryReference.FromFile(ProjectFile), UnrealTargetPlatform.Android);
			bool bDisableFunctionDataSections = false;

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

				bool bSaveSymbols = false;

				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);

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

					bool bBuildWithHiddenSymbolVisibility = false;
					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);