Getting Started - installing NUKE in an existing project

Follow any of these methods to integrate NukeExt:

Method 1: Using the sqtech-build global tools

This is recommended for most Studios Quality tech projects. It is very extensible with a large number of built-in configuration parameters.

  1. Copy the .nuke folder and build.cmd script from NukeExt or another Git repo
  2. Copy the build.ps1 scripts from the samples folder and update the version number to the latest
  3. Update the .nuke/parameters.json file to point at the correct Visual Studio solution

Method 2: Custom build script

This builds on method 1, and in addition it uses a C# script file to allow for project-specific customizations.

  1. Complete method 1 to integrate NukeTool in your project
  2. Create a file named Build.cs next to the .nuke folder. See the example in the samples folder
  3. In the file define your own Build class and on the last line use typeof(MyBuild) to return it

Method 3: Custom build project

This involves setting up a C# project for the NUKE build, which allows overriding and adding new automation targets. First begin by reading the NUKE installation guide, and then see for example the build in NukeExt itself. Consider using this method only if method 1 does not satisfy your scenario.

  1. Install the NUKE global tool and run the nuke :setup command
  2. Verify the .nuke/parameters.json file points at the correct Visual Studio solution

Build and Test

  1. From the command line, run .\build.cmd or if you have the global tool installed, sqtech-build.exe
  2. For Visual Studio integration and other extensions, see the NUKE documentation.
  3. For example, to run unit tests, type .\build.cmd --target Test
  4. Or to reproduce the Azure DevOps CI build locally, type .\build.cmd --target CI

YAML Generation

Running one of the build scripts will by default generate the following YAML files:

  • azure-pipelines.yml: a CI or CI/CD pipeline to execute in Azure DevOps.
  • azure-pipelines.code-index.yml: a pipeline to enable code navigation in Azure DevOps.

For documentation pipelines, refer to the documentation section.

Proceed to the Azure DevOps pipeline documentation to learn more about using YAML files in Azure DevOps.

Configuration

Here are all the parameters for NukeExt and sqtech-build tool. These can be set on the command line, in C# code, or in the parameters.json file which is what's recommended for projects using sqtech-build.

--artifacts-directory     Output folder for artifacts.
--code-coverage-directory Output folder for code coverage.
--nuget-directory         Output folder for NuGet packages.
--publish-directory       Output folder for binaries.

--configuration           Configuration to build - 'Debug' (default for local build)
                          or 'Release' (default for server).
--platform                Platform to build - default depends on the solution.
--target-framework        .NET target framework to use - default depends on the
                          solution.

--publish-coverage-html   Whether to publish HTML to view test coverage.
--publish-frameworks      .NET target framework to publish - default depends on the
                          solution.
--run-lint-in-ci          Whether to lint source code in CI builds.
--run-pack-in-cd          Whether to publish NuGet artifacts in CD builds.
--run-publish-in-cd       Whether to publish binary artifacts in CD builds.
--test-collect            Data collector to use for the test run.
--test-filter             Filter for which tests to run.
--test-result-directory   Output folder for test results.

The following are additional custom parameters for Azure DevOps YAML.

--build-timeout-in-minutes  The build job timeout, in minutes, if any.
--code-inspector-id         This repository's service tree ID to use for code inspection.
--disable-deployment        Whether to disable deployment.
--deployment-model          The deployment model (StudiosQualityTech or XboxStudiosQuality)
--deployment-stage-template The path for an optional custom deployment stage YAML template.
--deploy-from-branch        The branch to deploy from.
--dotnet-sdks               The .NET SDKs to install before running the build.
--image-name                The Azure pipelines virtual machine image name, if valid.
--nuget-config-path         The NuGet config path to use.
--nuke-build-directory      The directory within the repo containing the Nuke build scripts.
--pool-name                 The Azure pipelines virtual machine pool name, if any.
--production-branch         The branch to deploy documentation to production from.
--project-name              The project name to use on SQTechDocs, or the container to deploy to.

These are also parameters for Azure DevOps YAML, which come built-in to Nuke.

--excluded-targets                  Any targets to exclude from the build.
--invoked-targets                   The targets to run during the build.
--non-entry-targets                 Any targets to run before the invoked targets.
--fetch-depth                       The Git history depth to fetch before builds.
--large-file-storage                Whether to install LFS content before builds.
--submodules                        Whether to check out submodules before builds.
--trigger-batch                     Whether triggered builds are batched together.
--trigger-branches-include          The branches to include when triggering builds.
--trigger-branches-exclude          The branches to exclude when triggering builds.
--trigger-disabled                  Disable triggering the build on pushes.
--trigger-paths-include             The paths to include when triggering builds.
--trigger-paths-exclude             The paths to exclude when triggering builds.
--trigger-tags-include              The tags to include when triggering builds.
--trigger-tags-exclude              The tags to exclude when triggering builds.
--pull-requests-auto-cancel         Whether pushing to a PR branch cancels builds.
--pull-requests-branches-include    The branches to include when building PRs.
--pull-requests-branches-exclude    The branches to exclude when building PRs.
--pull-requests-disabled            Disable triggering the build on PRs.

Variables

In addition to build parameters, some functionality can be controlled via environment variables. These settings are experimental and may break or be removed without recourse.

  • NUKE_COVERAGE_INLINE_STYLE -- set to true to enable inline styles in HTML coverage reports
  • NUKE_DOTNET_VERSION -- set to the .NET SDK version to install in Azure DevOps CI builds and override the default
  • NUKE_SKIP_CHECK_PIPELINE -- set to true to skip checking the generated pipeline YAML matches
  • NUKE_SKIP_LINT -- set to true to skip running lint in CI builds (overriding RunLintInCI)

This page was last modified on February 19 2025, 05:26 PM (UTC).