Frequently Asked Questions

The name "NUKE" originates from a combination of the words New and Make.

GNU Make can be considered the godfather of build automation tools that is based on the commonly known makefile.

NU is a play on the word New, similar as in Nu-Metal. It also breaks the common naming pattern to be AKEless - as in "working without ache/pain" - since it doesn't come with the scripting heritage most developers expect from MAKE tools. Instead, it fully integrates with IDEs and other existing tooling, and makes build automation a breeze.

Absolutely. We've heard plenty of stories where developers choose NUKE to kick off and extend their JavaScript/TypeScript or Gradle builds. Although pulling in the .NET SDK can be seen as an unnecessary dependency for the project, the gained comfort quickly outweighs this penalty.

While MSBuild is a powerful build system and definitely worth exploring for some use-cases, it falls rather short when it comes to general build automation. The XML format makes it very verbose even for medium complex logic. Writing custom tasks in C# is a possible but not practical due to the maintenance costs and cumbersome debugging.

NUKE doesn't replace MSBuild though. Using the DotNetTasks and MSBuildTasks, it is still used to compile solutions and projects.

Our rule of thumb: when something is closely related to the compilation process and involved files, you should use MSBuild. When it's not, like packaging the output files, you could use NUKE.

Using YAML can be absolutely fine in many scenarios, particularly when you're sure that your build remains simple long-term. Once it gets more complex though, you will quickly realize that common control flow elements like if-statements or foreach-loops have no home in YAML files. In addition, you will fight some other YAML issues, like repetitive formatting errors, inability for local troubleshooting, and missing refactoring tools.

NUKE doesn't replace YAML files though. Your respective CI/CD service still needs a YAML file (or similar configuration files), to invoke your NUKE build.

We encourage everyone to try and evaluate any of the other build automation options that exist in the .NET ecosystem. Some unique NUKE features from our point of view are:

• Targets (build steps) are declared as properties
• Common build automation helper functions included
• Consistent fluent API for all the major CLI tools
• Declarative build parameters (input values)
• Build sharing and build composition
• Generation of CI/CD configuration files (YAML, etc.)
• Native integration into IDEs with additional extensions

You can also read comparative articles by Dennis Doomen or Laurent Kempé.

Not necessarily. It's perfectly fine to remove them and call dotnet run on the build project. However, there are two situations when these files are really required:

1. They ensure the availability of the .NET SDK according to the global.json file. If there is no local installation, it will be downloaded to the temporary directory. This greatly simplifies execution on CI/CD environments and for anyone trying to contribute to your project.
2. They allow the Visual Studio and Visual Studio Code extensions to execute the build.

The .nuke directory allows to infer the root directory (i.e., NukeBuild.RootDirectory). Alternatively, you can invoke the build with the --root flag to indicate that the working directory should be used, or --root <path> to pass another directory.

The build.schema.json file is generated on each build execution. If you have configured shell completion, this file is used to provide completion results. If the file is not present, the first completion attempt (i.e., when hitting TAB) needs to compile your build project. Therefore, you only need to commit this file if you prefer immediate completion behavior.

No. The global tool is only required to set up a build. Contributors can use the following commands to execute the build:

dotnet run -- [args]

.\build.cmd [args]

./build.sh [args]

Whether a tool invocation is treated as an error depends solely on its exit code. Only non-zero exit codes will fail the build. Some tools are notoriously logging to the error stream while the outcome is still successful. Most commonly, this includes Git and Docker. You can overwrite the tool-specific logger in your Build constructor and delegate to any of the logging methods:

GitTasks.GitLogger = (type, text) => Log.Debug(text);

DockerTasks.DockerLogger = (type, text) => Log.Debug(text);

As of now, we don't plan to introduce this as default, because you might miss important error messages.

You're most likely running the build in a terminal that isn't set to UTF-8 output. We can't give any more help here, but recommend to check on a suitable StackExchange platform or ask our community on Slack or Discord.

Major versions are released alongside major .NET SDK releases. This is to reflect that our releases are compatible with a specific .NET SDK version. As a consequence, breaking changes may and will happen during minor releases for various reasons. Most often, it is to improve an API, fix legacy mistakes, or update a tool task to a new version.

If you can no longer find an API, proceed as follows:

• Check the changelog
• Try to fuzzy search in your IDE
• Reach out to the community on Slack or Discord

Please remember that this is an open-source project.

Most likely not, unless it is fundamental and would affect all users. It is in the interest of the project to dedicate our available time to implementing cool new features.

Please remember that this is an open-source project.

If you need to restore a private NuGet package as part of the build project compilation, you have to provide the feed password in your build environment and adapt the bootstrapping scripts as follows:

###########################################################################
# CONFIGURATION
###########################################################################

...

$env:FEED_SOURCE = "https://nuget.pkg.github.com/nuke-build/index.json"
$env:FEED_USERNAME = "nuke-bot"

###########################################################################
# EXECUTION
###########################################################################

...

if (Test-Path env:FEED_PASSWORD) {
    ExecSafe { & $env:DOTNET_EXE nuget add source $env:FEED_SOURCE --username $env:FEED_USERNAME --password $env:FEED_PASSWORD }
}

Write-Output "Microsoft (R) .NET Core SDK version $(& $env:DOTNET_EXE --version)"

ExecSafe { & $env:DOTNET_EXE build $BuildProjectFile /nodeReuse:false /p:UseSharedCompilation=false -nologo -clp:NoSummary --verbosity quiet }
ExecSafe { & $env:DOTNET_EXE run --project $BuildProjectFile --no-build -- $BuildArguments }

###########################################################################
# CONFIGURATION
###########################################################################

...

export FEED_SOURCE="https://nuget.pkg.github.com/nuke-build/index.json"
export FEED_USERNAME="nuke-bot"

###########################################################################
# EXECUTION
###########################################################################

...

if [[ ! -z ${FEED_PASSWORD+x} && "$FEED_PASSWORD" != "" ]]; then
    "$DOTNET_EXE" nuget add source "$FEED_SOURCE" --username "$FEED_USERNAME" --password "$FEED_PASSWORD" --store-password-in-clear-text
fi

echo "Microsoft (R) .NET SDK version $("$DOTNET_EXE" --version)"

"$DOTNET_EXE" build "$BUILD_PROJECT_FILE" /nodeReuse:false /p:UseSharedCompilation=false -nologo -clp:NoSummary --verbosity quiet
"$DOTNET_EXE" run --project "$BUILD_PROJECT_FILE" --no-build -- "$@"