BuildHistory

Description

Provides access to the build history generated during builds.

For each Player or Content Directory build, Unity creates a "build report directory" inside the build history. This directory holds the BuildReport file and the supporting data captured during that build, including 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.

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.

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 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 content into automated build pipelines.

Retention Policy

To prevent unbounded growth of the build history folder, Unity applies a retention policy at the start of each Player and Content Directory build. BuildHistory.BuildHistoryLimit sets the maximum number of builds to retain; when a new build pushes the count over the limit, the oldest entries are deleted. Set the limit to 0 to disable automatic deletion. You can also invoke the policy manually with BuildHistory.ApplyRetentionPolicy.

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.TryGetBuildReportDirectory 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