External Files

When using submodules or NuGet packages for build sharing, it usually involves quite a bit of heavy work, like updating the parent repositories or creating a NuGet feed. External files are a more lightweight approach: There is a primary repository containing the actual Build.cs template file, and several replica repositories with only a Build.cs.ext file. This .ext file contains a URI referencing the Build.cs file, which will cause MSBuild to actually download or update that file as a pre-build step when compiling the build project. The generated Build.cs file can either be committed or excluded from the repository, depending on the individual requirements.

Usage

To enable support for external files, the build project file must contain an item group similar to this. By default, it's already part of the SDK project template:

<ItemGroup>
    <NukeExternalFiles Include="**\*.*.ext" Exclude="bin\**;obj\**" />
</ItemGroup>

Downloading or updating a Build.cs from an external source would then require to create a Build.cs.ext file with the following content:

https://raw.githubusercontent.com/nuke-build/nuke/develop/build/Build.cs

Note, that instead of develop also a tag like 1.2.3 could be used, allowing to use lightweight versioning.

Templating

Besides natural extension points like partial classes or type inheritance, this approach supports minor output modifications in the form of conditionals and replacements. Considering a template like this:

class Build
{
    readonly string Source = "_SOURCE_";

    [GitVersion] readonly GitVersion GitVersion;    // GITVERSION
}

With the following Build.cs.ext file, the generated output can be modified to replace the _SOURCE_ placeholder, and also allows to either include or exclude the GitVersion field declaration:

https://raw.githubusercontent.com/nuke-build/nuke/master/build/Build.cs

GITVERSION

SOURCE=https://api.nuget.org/v3/index.json

The first line must always be the URI reference. All lines containing a = are considered a replacement, while all other non-empty lines are definitions. Note that the template engine requires definition comments to be prefixed with two whitespace to be distinguishable from normal comments.