UnrealBuild.cs

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using Nuke.Cola;
using Nuke.Common;
using Nuke.Common.IO;
using Nuke.Common.Utilities;
using Nuke.Common.Utilities.Collections;
using Nuke.Unreal.Ini;
using Nuke.Unreal.Platforms;
using Nuke.Unreal.Platforms.Android;
using Nuke.Unreal.Tools;
using Serilog;
 
namespace Nuke.Unreal;
 
/// <summary>
/// Indicating the INI config hierarchy importance, from least important to most important
/// (in terms of what overrides the other)
/// </summary>
public enum IniHierarchyLevel
{
    Base,
    Default,
    Saved
}
 
/// <summary>
/// The main build class Unreal projects using Nuke.Unreal should inherit from. This class
/// contains all base targets for use-cases which are relevant for 99% of Unreal project
/// development tasks.
/// </summary>
[DisableDefaultOutput(DefaultOutput.ErrorsAndWarnings)]
public abstract partial class UnrealBuild : NukeBuild, IUnrealBuild
{
    protected override void OnBuildCreated()
    {
        base.OnBuildCreated();
        PlatformSdkManager.RegisterSdks();
    }
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// Specify the target Unreal Engine version. It's used only for the Switch target. Everything else should infer
    /// engine version from the project file. Can be simple version name like `5.5`, a GUID associated with engine
    /// location or an absolute path to engine root.
    /// </summary>
    /// <remarks>
    /// Most targets read the desired Unreal version from the project file.
    /// </remarks>
    [Parameter(Name = "unreal")]
    public virtual string? UnrealVersion { get; set; }
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// Specify the output working directory for artifacts
    /// </summary>
    [Parameter]
    public AbsolutePath? Output;
 
    /// <summary>
    /// Get an output folder where the targets should store their artifacts. Override this
    /// function in your main build class to enforce your own.
    /// </summary>
    public virtual AbsolutePath GetOutput() => Output ??= ProjectFolder / "Intermediate" / "Output";
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// Set platform for running targets
    /// </summary>
    [Parameter]
    public virtual UnrealPlatform Platform { get; set; } = UnrealPlatform.FromFlag(Unreal.GetHostPlatformFlag());
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// The target configuration for building or packaging the project
    /// </summary>
    [Parameter]
    public virtual UnrealConfig[] Config { get; set; } = [UnrealConfig.Development];
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// The editor configuration to be used while building or packaging the project
    /// </summary>
    [Parameter]
    public virtual UnrealConfig[] EditorConfig { get; set; } = [UnrealConfig.Development];
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// The Unreal target type for building the project
    /// </summary>
    [Parameter]
    public virtual UnrealTargetType[] TargetType { get; set; } = [UnrealTargetType.Game];
 
    /// <summary>
    /// <para>
    /// **NUKE PARAMETER**
    /// </para>
    /// Select texture compression mode for Android
    /// </summary>
    [Parameter]
    public virtual AndroidCookFlavor[] AndroidTextureMode { get; set; } = [ AndroidCookFlavor.Multi ];
 
    /// <summary>
    /// UBT arguments to be applied globally for all UBT invocations. Override this function
    /// in your main build class if your project needs extra intricacies for everything what
    /// UBT may do through Nuke.Unreal.
    ///
    /// These arguments are also propagated to all UAT invocations through its `-UbtArgs`
    /// </summary>
    public virtual UbtConfig UbtGlobal(UbtConfig _) => _
        .WaitMutex();
 
    /// <summary>
    /// UAT arguments to be applied globally for all UAT invocations. Override this function
    /// in your main build class if your project needs extra intricacies for everything what
    /// UAT may do through Nuke.Unreal.
    /// </summary>
    public virtual UatConfig UatGlobal(UatConfig _)
    {
        var ubtArgs = GetArgumentBlock("ubt").ToList();
        return _
            .UTF8Output()
            .WaitForUATMutex()
            .NoP4()
            .If(!ubtArgs.IsEmpty(), _ => _.UbtArgs(ubtArgs.JoinSpace()));
    }
 
    private EngineVersion? _engineVersionCache = null;
 
    /// <summary>
    /// Utility function to get the proper Engine version associated with current project.
    /// Rather use `Unreal.Version` static function, that looks nicer.
    /// </summary>
    public EngineVersion GetEngineVersionFromProject()
    {
        if (_engineVersionCache == null)
        {
            var versionString = UnrealVersion ?? ProjectDescriptor.EngineAssociation;
            Assert.NotNull(versionString, "Unreal Engine version couldn't be determined");
            _engineVersionCache = new(versionString!);
        }
        return _engineVersionCache!;
    }
 
    /// <summary>
    /// Path to the root of the associated Unreal Engine installation/source
    /// </summary>
    public AbsolutePath UnrealEnginePath => Unreal.GetEnginePath(this);
 
    /// <summary>
    /// Print some rudimentary information onto console about this project and it's environment.
    /// Override this function in your main build class if your project may have its own
    /// important info like this useful for debugging.
    /// </summary>
    public virtual void PrintInfo()
    {
        var unrealVersion = GetEngineVersionFromProject();
        Log.Information("Project name:        {0}", ProjectPath.NameWithoutExtension);
        Log.Information("Unreal version:      {0}", unrealVersion.VersionName);
        Log.Information("Unreal full version: {0}", unrealVersion.VersionPatch);
        Log.Information("Unreal root:         {0}", UnrealEnginePath);
        Log.Information("Output folder:       {0}", GetOutput());
    }
 
    /// <summary>
    /// Get optionally named argument block (section after `-->`) with contextual data
    /// substituted.
    /// <list type="bullet">
    ///     <item>`~p` Project file path</item>
    ///     <item>`~pdir` Project folder</item>
    ///     <item>`~ue` Unreal Engine folder</item>
    /// </list>
    /// </summary>
    public virtual IEnumerable<string> GetArgumentBlock(string name = "")
        => Arguments.GetBlock(name)
            .Select(a => a
                .Replace("~p", ProjectPath)
                .Replace("~pdir", ProjectFolder)
                .Replace("~ue", UnrealEnginePath)
                .DoubleQuoteIfNeeded()
            );
 
    /// <summary>
    /// Read INI configuration emulating the same hierarchy of importance as Unreal Engine
    /// also does.
    /// </summary>
    /// <param name="shortName">The name of the configuration like `Game` or `Engine`</param>
    /// <param name="lowestLevel">
    ///     The least important level of hierarchy for reading this config.
    ///     Default is `Base`
    /// </param>
    /// <param name="highestLevel">
    ///     The maximum important level of hierarchy for reading this config
    ///     Default is `Saved`
    /// </param>
    /// <param name="considerPlugins">
    ///     If true also consider config files found in plugins.
    ///     Default if true.
    /// </param>
    /// <param name="extraConfigSubfolder">
    ///     Manually add extra configuration subfolders which may be outside of the normal
    ///     sources of config files.
    /// </param>
    /// <returns>The parsed contents of the indicated config name</returns>
    public ConfigIni ReadIniHierarchy(
        string shortName,
        IniHierarchyLevel lowestLevel = IniHierarchyLevel.Base,
        IniHierarchyLevel highestLevel = IniHierarchyLevel.Saved,
        bool considerPlugins = true,
        IEnumerable<string>? extraConfigSubfolder = null
    ) {
        var resultIni = new ConfigIni();
        extraConfigSubfolder = (extraConfigSubfolder ?? Enumerable.Empty<string>())
            .Append(Platform.ToString());
 
        IReadOnlyCollection<AbsolutePath> GlobIni(AbsolutePath folder)
        {
            return folder.GlobFiles($"{shortName}.ini", $"*{shortName}.ini");
        }
 
        void MergeInis(AbsolutePath folder, ConfigIni result)
        {
            if (folder.DirectoryExists())
                foreach (var iniFile in GlobIni(folder))
                {
                    var currIni = ConfigIni.Parse(File.ReadAllText(iniFile));
                    if (currIni != null)
                        result.Merge(currIni);
                }
        }
 
        void GatherInis(AbsolutePath configFolder, ConfigIni result)
        {
            MergeInis(configFolder, resultIni);
            foreach (var folder in extraConfigSubfolder.Select(s => configFolder / s))
            {
                if (folder.DirectoryExists())
                    MergeInis(folder, resultIni);
            }
        }
 
        if (lowestLevel <= IniHierarchyLevel.Base && highestLevel >= IniHierarchyLevel.Base)
        {
            var configFolder = UnrealEnginePath / "Engine" / "Config";
            var baseIni = ConfigIni.Parse(File.ReadAllText(configFolder / "Base.ini"));
            if (baseIni != null)
                resultIni.Merge(baseIni);
 
            GatherInis(configFolder, resultIni);
        }
 
        if (lowestLevel <= IniHierarchyLevel.Default && highestLevel >= IniHierarchyLevel.Default)
        {
            var configFolder = ProjectFolder / "Config";
            GatherInis(configFolder, resultIni);
        }
        if (lowestLevel <= IniHierarchyLevel.Default && highestLevel >= IniHierarchyLevel.Default && considerPlugins)
        {
            foreach (var pluginConfigFolder in (ProjectFolder / "Plugins").GlobDirectories("**/Config"))
            {
                GatherInis(pluginConfigFolder, resultIni);
            }
        }
        if (lowestLevel <= IniHierarchyLevel.Saved && highestLevel >= IniHierarchyLevel.Saved)
        {
            var configFolder = ProjectFolder / "Saved" / "Config";
            GatherInis(configFolder, resultIni);
        }
 
        return resultIni;
    }
}