md.Nuke.Unreal 1.0.5

.NET 5.0
Install-Package md.Nuke.Unreal -Version 1.0.5
dotnet add package md.Nuke.Unreal --version 1.0.5
<PackageReference Include="md.Nuke.Unreal" Version="1.0.5" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add md.Nuke.Unreal --version 1.0.5
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: md.Nuke.Unreal, 1.0.5"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install md.Nuke.Unreal as a Cake Addin
#addin nuget:?package=md.Nuke.Unreal&version=1.0.5

// Install md.Nuke.Unreal as a Cake Tool
#tool nuget:?package=md.Nuke.Unreal&version=1.0.5
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Nuke.Unreal

Simplistic workflow for automating Unreal Engine project steps embracing Nuke.

Nuke + Unreal Engine workflow provides a consistent way to work with UE4/5 tools reducing the chore it comes with

Usage

Nuke.Unreal is available as a Nuget package and you can just add it to your build project as usual (package ID is md.Nuke.Unreal)

  1. <details><summary>Install Nuke for an Unreal project</summary>

    > dotnet tool install Nuke.GlobalTool --global
    
    > dotnet new sln --name Build
    
    > nuke :setup
    # preferably put your build project inside Nuke.Targets folder
    
    > cd ./Nuke.Targets
    > dotnet add package md.Nuke.Unreal
    

    </details>

  2. Inherit your Build class from UnrealBuild instead of NukeBuild

  3. No further boilerplate required, run nuke --plan to test Nuke.Unreal

  4. (optional) Inherit IPackageTargets interface if you want to package the associated Unreal project

  5. (optional) Inherit IPluginTargets interface for automating plugin development related steps.

Your bare-bones minimal Build.cs which will provide the default features of Nuke.Unreal should look like this:

// Build.cs
using namespace Nuke.Common;
using namespace Nuke.Unreal;

class Build : UnrealBuild
{
    public static int Main () => Execute<Build>(x => x.BuildEditor);
}

Features:

  • All what the great Nuke can offer
  • Common UE4 build tasks (generate project files, build editor, cook, package, etc)
    > nuke generate
    > nuke build-editor
    > nuke build --config Shipping
    > nuke build --config DebugGame Development --run-in Editor
    > nuke cook
    > nuke package
    
  • Prepare plugins for release in Marketplace
    > nuke make-release --for-marketplace
    
  • Bind Unreal tools to Nuke with fluent C# API [very WIP]
  • Generate boilerplate code and scaffolding from Scriban templates so no editor needs to be opened
    > nuke new-actor --name MyActor
    > nuke new-plugin --name MyPlugin
    > nuke new-module --name MyModule
    etc...
    

Setting up for a project

Nuke.Unreal targets looks for the *.uproject file automatically and it will use the first one it finds. A *.uproject is required to be present even for plugin development (more on plugins below). Automatically found project files can be in the sub-folder tree of Nuke's root (which is the folder containing the .nuke) or in parent folders of Nuke's root. If for any reason there are more than one or no *.uproject files in that area, the developer can specify an explicit location of the associated *.uproject file.

public override AbsolutePath ToProject => RootDirectory / ".." / "MyProject" / "MyProject.uproject";

Only one Unreal project is supported per Nuke.Unreal instance.

Setting up for plugin development

Same is applicable when Nuke.Unreal is used for developing an Unreal Plugin for release. Of course Nuke.Unreal can work with multiple plugins in a project, but the IPluginTargets interface focuses only on one plugin. Again if the plugin is not trivially locatable then the developer can specify its location explicitly.

public override AbsolutePath ToPlugin => UnrealPluginsFolder / "MyPlugin" / "MyPlugin.uplugin";

Additional Plugin Targets

However plugins which require some pre-processing might benefit from the very simple "Plugin Targets" pattern, which is just simple class-library C# projects, referencing Nuke.Unreal as a nuget, and define extra targets or functionality which can be used by the main Nuke installation for the project. Let's have this scaffolding as an example:

<project root>
  - .nuke
  - Nuke.Targets
    - _build.csproj
    - Build.cs (main build script)
  - Content, Build, etc...
  - Source
    - MyModule
      - <source files>
      - Nuke.Targets
        - MyModule.csproj
        - MyModule.cs
  - Plugins
    - MyPlugin
      - <regular plugin files>
      - Nuke.Targets
        - MyPlugin.csproj
        - MyPlugin.cs
  - MyUnrealProject.uproject

MyModule.csproj and MyPlugin.csproj were both simply generated by dotnet new classlib --name ... --output ./Nuke.Targets and then the md.Nuke.Unreal which brings in the core Nuke packages, was added to define targets. Of course the developer can manually add these project references to the main build project, but Nuke.Unreal provides discover-plugin-targets target, which seeks out C# projects inside Nuke.Targets folders, and add them to the main build project automatically. After calling discover-plugin-targets, the developer can use these plugin projects as any other regular .NET reference. In most cases the plugin projects define interfaces which has some targets declared with "default implementation", then these interfaces can be inherited by the main Build class. Nuke will see the new targets without further boilerplate.


// MyModule.cs
using namespace Nuke.Common;
using namespace Nuke.Unreal;
namespace Nuke.MyModule;

public interface IMyModuleTargets : INukeBuild
{
    Target Foo => _ => _
        .DependsOn<IPackageTargets>()
        .Executes(() {...});
}

// MyPlugin.cs
using namespace Nuke.Common;
using namespace Nuke.Unreal;
namespace Nuke.MyPlugin;

public interface IMyPluginTargets : INukeBuild
{
    Target Foo => _ => _
        .Before<UnrealBuild>(u => u.Generate, u => u.Build, u => u.BuildEditor)
        .Executes(() {...});
}

// Build.cs
using namespace Nuke.Common;
using namespace Nuke.Unreal;
using namespace Nuke.MyModule;
using namespace Nuke.MyPlugin;

class Build : UnrealBuild, IPackageTargets, IMyModuleTargets, IMyPluginTargets
{
    public static int Main () => Execute<Build>(x => x.BuildEditor);
}

While discovering plugin targets, C# projects inside a Nuke.Targets folder neighbouring a .nuke folder will be ignored.

Custom UBT or UAT arguments

Nuke.Unreal supports passing custom arguments to UBT or UAT via --ubt-args or --uat-args. These are regular array properties exposed as Nuke target parameters. This means however that doing --ubt-args -DisableUnity wouldn't actually add -DisableUnity to the argument list. This happens bec ause Nuke stops parsing the array argument when it hits a - character. For this reason Nuke.Unreal has a special escape mechanism where ~- is replaced with -, or if the argument starts with ~ then that's also replaced with a -.

So doing --ubt-args ~DisableUnity ~2022 will correctly pass arguments -DisableUnity -2022 to UBT.

For convenience the sequence '' is also replaced with a double quote " hopefully escaping command line parsers.

This is especially useful for doing temporary debugging with UBT and the compiler: (not an actual usecase)

> nuke build ... --ubt-args "~CompilerArguments=''/diagnostics:caret /P /C''" ~DisableUnity
> nuke build ... --ubt-args "~LinkerArguments=''/VERBOSE''"
> nuke build ... --ubt-args ~Preprocess

Generators

Unreal boilerplate templates

Nuke.Unreal provides some targets which creates boilerplate code for common Unreal entities, such as

  • Plugins
  • Modules
  • Unreal Object/Actor/Structs/Interfaces
  • Slate widgets

without the need for opening the UE4 editor or extend heavy weight IDE's. These boilerplate targets work with Scriban templates. The path to these templates can be overridden in the actual Nuke build class in case a project requires further boilerplate. Example:

In any folder in your project

> nuke NewActor --name MyPreciousActor

This will generate MyPreciousActor.h and ~.cpp at their respective places (taking public and private folders into account) and the minimal actor class boilerplate for unreal.

Optional Custom templates folders are required to contain generator specific subfolders. If a subfolder doesn't exist for a generator the default will be used. Example:

Scaffolding:

  • RootDirectory
    • Nuke.Targets
      • ...
      • Build.cs
    • ...
    • MyTemplates
      • Actor
      • Object

In Nuke.Targets/Build.cs override TemplatesPath property

public override AbsolutePath TemplatesPath { get; set; } = RootDirectory / "MyTemplates";

This way Actor and Object generators will have their project specific Scriban templates but the remaining generator types will use the default templates of Nuke.Unreal.

Generators for Unreal Tools [WIP]

Nuke.Unreal can generate type-safe fluent API for UE tooling with similar mindset as Nuke tools using direct reflection data from Unreal tools written for .NET. The Tool Generators project directly reference those programs as .NET assemblies. It's only done like this in the generator, and not actually inside the build project because the assemblies are referred with an absolute path, but the location of Unreal is a dynamic data during runtime ("build-time" if you prefer). So there's no extra ceremony for the user during setting up their build environment with Nuke.Unreal. As an added extra this way we can still somewhat treat these tools as executable black-boxes during runtime/build-time, so we don't run into any problems regarding different .NET environment requirements.

On the other hand Contributors to Nuke.Unreal need to modify LocalUnrealAssemblies.targets in order to explicitly point to their own location of their unreal installation depending on their development platform. Again this is only necessary for generating the fluent tool API, but not for running the actual Nuke.Unreal targets.

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.5 127 4/13/2022
1.0.4 102 4/13/2022
1.0.3 102 4/13/2022
1.0.1 108 4/12/2022
1.0.0 112 4/12/2022