Configuring Profile-Guided Optimization in Visual Studio

Profile-Guided Optimization support was introduced in AGDE version 22.2.71.

Locating the PGO settings

Open your project settings from Solution Explorer.

The Visual Studio Solution explorer properties menu for the current

Figure 1: The Visual Studio Solution Explorer window.

Make sure that your Platform is set to an Android configuration (for example, Android-arm64-v8a).

In the left-hand panel, select Configuration Properties > General. Look for the property group called PGO.

The project properties dialog with General properties shown, and PGO settings

Figure 2: The Project Properties dialog.

Enable PGO-Instrumented Builds in the Project

Add a new configuration called Instrumented to your project. This is based on the configuration you use during development for testing, which should be your traditional optimized build (you can still have additional debugging features enabled as long as you preserve the compiler optimization settings).

Click on Configuration Manager… in the Property page dialog.

The top of the Property Pages dialog, showing the Active Solution
Configuration and Platform drop-downs, and the Configuration Manager

Figure 3: The Configuration Manager dialog.

In the Configuration Manager dialog, select the Active solution configuration drop-down and choose <New…>.

The Configuration Manager dialog, with the Active Solution Configuration
drop-down opened and the New option

Figure 4: Creating a New build configuration.

… and create a new PGO-Instrumented configuration.

The New Solution Configuration dialog, creating a new PGO-Instrumented build
configuration based on the existing Release build

Figure 5: The New Solution Configuration dialog.

To enable building in PGO-Instrumented mode, so that you can generate a profile for your game, select Instrumented from the list of options for the Profile-Guided Optimization Mode setting.

The Project Properties dialog, opened to the General settings, with the PGO
settings shown, and the Profile Guided Optimization mode set to

Figure 6: The Project Properties dialog, highlighting the PGO settings.

For the Profile Guided Optimization Profiles setting, enter the path to the folder to write the raw output profile data file to on your Android device. Typically this value should be something like /data/data/<package name>/cache/ – where <package name> is the full package name of your APK – for example,

For more in-depth information about how this works, see the Clang documentation.

Writing PGO-Instrumented profile data to your device

PGO data is usually written to the device by the PGO instrumentation system when a process exits. On Android, apps don't exit – they're always terminated. This means the default "write to disk" functionality never triggers, requiring your app to write PGO data manually.

Your app you should explicitly call __llvm_profile_write_file to write out the profile data. This symbol is only available when building a PGO-instrumented build. To make this easier, we recommend using the following pattern when forward declaring __llvm_profile_write_file.

extern "C" int __llvm_profile_write_file(void);
extern "C" int __llvm_profile_write_file(void) { return 0; }

Calling this function writes the profile data to the folder that you specified earlier.

Performing a profile run

To generate the profile, you run your APK built with PGO-instrumentation on the target device. After you have exercised the code to your satisfaction, and have triggered the call to the __llvm_profile_write_file function, your app will write the profile data to storage.

At this point, copy the profiles back off the device for use by the compiler.

Preparing profile data for use by the compiler

When used in isolation, the command-line tool llvm-profdata that ships as part of Clang/LLVM in the Android NDK is used to prepare profile data files for use by the compiler during profile-guided optimization of a build.

AGDE performs this step automatically for you by merging together any profile data files you have added to your project, and consuming them when the Profile-Guided Optimization Mode setting in the project property pages is set to Optimized.

Building your project with Profile-Guided Optimization enabled

Now that you have captured your profile(s), and added it to your project, the compiler can use that data to fine-tune the optimization of your build.

Create a new project configuration for your PGO-Optimized Build so that you only build in this mode when it's needed.

The New Solution Configuration dialog creating a build configuration based on
the Release build, but this time with PGO-Optimized as the new build
configuration name.

Figure 7: Creating a new PGO-Optimized Build configuration.

Set the Profile-Guided Optimization Mode setting in the project property pages to Optimized.

The Project Properties dialog, opened to the General settings, with the PGO
settings shown, and the Profile Guided Optimization mode set to

Figure 8: Setting the PGO Optimization mode to Optimized.

Copy the files from the device and add them to your project in the Solution Explorer. These profile data files are picked up by the compiler the next time you build your PGO-Optimized configuration, and used to tune how the compiler optimizes your code.

You can copy the profile data files into your project from the device using ADB, or by using the Android Device File Explorer.

The Visual Studio Tools Menu is open, with the Android Game Development Extension sub-menu
open, and the Android Device File Explorer menu item

Figure 9: The Android Device File Explorer tool can be found in the Tools menu.

Using Profile-Guided Optimization outside of AGDE

If you are using a build system that is not supported by AGDE you may need to edit your build directly. Clang's documentation covers the necessary switches – -fprofile-instrumented-generate, and -fprofile-instrumented-use.

If you are using a middleware engine for your game, consult the documentation for your engine to see how to enable PGO (if it is supported).