BuildHistory

Description

Provides access to the build history generated during builds.

Unity stores the metadata files for Player and Content Directory builds in a sub-folder of the build history folder.

By default, build history is stored in Library/BuildHistory. You can change this location, for example to consolidate builds from multiple machines into a shared build history folder.

The build metadata folder is populated with files with information about various aspects of the build such as the BuildReport, profiling information, and type-usage information. The precise content is influenced by the type of build, build options and certain settings in the Preferences > Build Pipeline window.

Unity assigns each build a unique GUID, which the BuildHistory API uses to precisely identify each build. For more information, refer to BuildReportSummary.BuildSessionGUID.

The files in the build history folder are for development and debugging purposes only. They are not meant to be shipped along with the content and are not required by the runtime. Deleting build history does not impact the built content or the ability to run the Player, but can limit the ability to analyze or debug the results of the build. Incorporate the collection of the build history directory content into automated build pipelines.

Build Lifecycle

For Player builds, BuildPlayerProcessor.PrepareForBuild runs before the Player build is added to the history. This allows any Content Directory builds triggered during that callback to appear in the history before the Player build itself, resulting in a chronological ordering.

Unity adds a build to the history early in the build process (but after BuildPlayerProcessor.PrepareForBuild) and sets the result to BuildResult.Pending. If the Editor process terminates during a build, the build remains in the history with its initial Pending result.

Some BuildHistory methods, for example BuildHistory.TryGetMetadataPath and BuildHistory.TryGetFilePath, are available for use in the IPreprocessBuildWithReport and IPostprocessBuildWithReport build callbacks.

When the build completes, the BuildReportSummary is updated with the final result (BuildResult.Succeeded, BuildResult.Failed, or BuildResult.Cancelled).

Additional resources: BuildReportSummary, BuildReport

using System;
using System.Text;
using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;
using UnityEngine;

/// <summary>
/// Example showing how to scan build history and generate a statistics report.
/// </summary>
public class BuildHistoryStatsExample
{
    [MenuItem("Example/BuildHistory/Print Build Statistics")]
    static public void PrintBuildStatistics()
    {
        int buildCount = BuildHistory.GetBuildCount();

        if (buildCount == 0)
        {
            Debug.Log("No builds found in build history.");
            return;
        }

        // Collect statistics by scanning the summary of all builds
        long totalTimeMs = 0;
        int succeededCount = 0;

        GUID[] allBuilds = BuildHistory.GetAllBuilds();
        foreach (var buildGuid in allBuilds)
        {
            BuildReportSummary summary = BuildHistory.GetBuildSummary(buildGuid);
            totalTimeMs += summary.TotalTimeMs;
            if (summary.BuildResult == BuildResult.Succeeded)
                succeededCount++;
        }

        var sb = new StringBuilder();
        sb.AppendLine($"=== Build History Statistics ===");
        sb.AppendLine($"Total Builds: {buildCount}");

        double successRate = (double)succeededCount / buildCount * 100;
        sb.AppendLine($"  Success rate: {successRate}%");

        TimeSpan totalTime = TimeSpan.FromMilliseconds(totalTimeMs);
        sb.AppendLine($"Total Build Time: {totalTime:g}");
        TimeSpan averageTime = TimeSpan.FromMilliseconds(totalTimeMs / buildCount);
        sb.AppendLine($"Average Build Time: {averageTime:g}");

        Debug.Log(sb.ToString());
    }
}

Static Properties

Static Methods