Faithlife.Build 5.30.0

Faithlife.Build

Faithlife.Build is a build automation system using C# build scripts.

Overview

This library allows developers to use C# to write build scripts. It is similar to Cake and NUKE, but simpler, providing a thin wrapper over some of the libraries acknowledged below.

• define named targets with dependencies, descriptions, and actions
• add custom command-line flags and options
• run command-line apps with automatic argument escaping
• run dotnet commands
• run specific versions of MSBuild
• find files and directories using globs
• copy files from one directory to another
• get information about the build environment
• report custom build errors
• define standard targets for .NET builds that build, test, package, and generate documentation for your libraries

Most importantly, since the build script is a full-fledged .NET app with access to any compatible NuGet package, you can do just about anything, in a language and framework you already know well.

Usage

To use this library for your automated build, create a .NET Console App project in tools/Build that references the latest Faithlife.Build NuGet package. Optionally add the project to your Visual Studio solution file. See Build.csproj for an example project.

The Main method of the console app should call BuildRunner.Execute or BuildRunner.ExecuteAsync with the args and a delegate that defines the build targets and any desired command-line options by calling methods on the provided BuildApp.

using Faithlife.Build;
using static Faithlife.Build.DotNetRunner;

internal static class Build
{
	public static int Main(string[] args) => BuildRunner.Execute(args, build =>
	{
		build.Target("build")
			.Describe("Builds the solution")
			.Does(() => RunDotNet("build", "-c", "Release", "--verbosity", "normal"));
	});
}

Perform the build by running the Build project. This can be done directly via dotnet run, e.g. dotnet run --project tools/Build -- test, but builds are more easily run from a simple bootstrapper, usually named build.ps1, build.cmd, and/or build.sh.

Specify the desired targets on the command line, e.g. ./build package. Use --help to list the available build targets and command-line options. These command-line arguments are always supported:

• -n or --dry-run : Don't execute target actions.
• -s or --skip-dependencies : Don't run any target dependencies.
• --skip <targets> : Skip the comma-delimited target dependencies.
• --parallel : Run targets in parallel.
• --no-color : Disable color output.
• --show-tree : Show the dependency tree.
• --verbose : Show verbose output.
• -? or -h or --help : Show build help.

Consult the source code for additional details.

Create .NET Targets

To create standard targets for a .NET build, call DotNetBuild.AddDotNetTargets with custom settings as needed. See Build.cs for an example.

The supported targets include:

• clean : Deletes all build output.
• restore : Restores NuGet packages.
• build : Builds the solution.
• test : Runs the unit tests.
• coverage : Runs tests with coverage and generates coverage reports, if coverage settings are configured or coverage.runsettings exists.
• package : Builds NuGet packages.
• publish : Publishes NuGet packages and documentation.
• cleanup : Runs JetBrains CleanupCode if jetbrains.resharper.globaltools is installed as a local or global tool, or if solution settings are present.
• inspect : Runs JetBrains InspectCode if jetbrains.resharper.globaltools is installed as a local or global tool, or if solution settings are present.

The supported command-line options include:

• -c <name> or --configuration <name> : The configuration to build (default Release).
• -p <name> or --platform <name> : The solution platform to build.
• -v <level> or --verbosity <level> : The build verbosity (q[uiet], m[inimal], n[ormal], d[etailed]).
• --version-suffix <suffix> : Generates a prerelease NuGet package.
• --nuget-output <path> : Directory for the generated NuGet package (default release).
• --trigger <name> : The git branch or tag that triggered the build.
• --build-number <number> : The automated build number.
• --no-test : Skip the unit tests.

The supported DotNetBuildSettings include:

• SolutionName : The name of the solution file; defaults to the only solution in the directory.
• SolutionPlatform : The default solution platform to build.
• Verbosity : The default build verbosity.
• NuGetApiKey : The NuGet API key with which to push packages.
• NuGetSource : The NuGet source to which to push packages, if not the standard source.
• DocsSettings : Used to generate Markdown documentation from XML comments.
• MSBuildSettings : Set to use MSBuild instead of dotnet to build the solution.
• TestSettings : Settings for running unit tests.
• CoverageSettings : Settings for running unit tests with coverage.
• PackageSettings : Settings for creating and publishing NuGet packages.
• CleanSettings : Settings for cleaning projects.
• MaxCpuCount : The maximum number of CPUs to use when building.
• ExtraProperties : A function that returns any extra properties for the specified build target.
• ShowSummary : True if a build summary should be displayed.
• BuildNumber : The build number, if not specified on the command line.

For details on exactly what each target does and how the settings and command-line options affect the build, read the DotNetBuild source code.

Automatic MSBuild Properties

When using DotNetBuild.AddDotNetTargets, Faithlife.Build will set the following MSBuild properties automatically; you should not set them in Project.csproj or Directory.Build.props:

• AllowedOutputExtensionsInPackageBuildOutputFolder: set to include .pdb files.
• AssemblyVersion: set to $(VersionPrefix).$(BuildNumber) if BuildNumber is provided.
• ContinuousIntegrationBuild: set to true if a CI environment is detected.
• PublishRepositoryUrl: set to true to include repository URL in NuGet package metadata.

Additionally, this property and item come from the .NET SDK and should not be set manually:

• EmbedUntrackedFiles: set to true.
• SourceLinkGitHubHost: ContentUrl="https://raw.githubusercontent.com" is added for GitHub.com repositories.

To check the exact MSBuild properties and items being used, read the Runtime.Directory.Build.targets source code.

Package README Links

If a package reuses the repository README.md as its NuGet package README, relative links in that README will not work when rendered on nuget.org. Set RewritePackageReadmeLinks to true to generate a package-specific copy of the README during dotnet pack; repository-relative Markdown links are rewritten to absolute GitHub links, while same-document anchors and absolute links are left unchanged.

<PropertyGroup>
	<PackageReadmeFile>README.md</PackageReadmeFile>
	<RewritePackageReadmeLinks>true</RewritePackageReadmeLinks>
</PropertyGroup>

<ItemGroup>
	<None Include="..\..\README.md" Pack="true" PackagePath="\" />
</ItemGroup>

The generated README is packed as README.md; the source README remains unchanged. The package project must set RepositoryUrl or equivalent repository metadata so the generated links can point to the correct GitHub repository.

Coverage

Set DotNetBuildSettings.CoverageSettings, or place coverage.runsettings in the working directory, to add a standard coverage target that runs test projects under tests/**/*.csproj with Coverlet and generates reports with dotnet dnx dotnet-reportgenerator-globaltool.

build.AddDotNetTargets(new DotNetBuildSettings
{
	CoverageSettings = new DotNetCoverageSettings
	{
		TargetFramework = "net10.0",
	},
});

The target writes test results under artifacts/Coverage/TestResults, writes reports to artifacts/Coverage/Report, and uses coverage.runsettings automatically when that file exists. Each run uses a fresh test-results subdirectory so stale coverage files are not included.

Contributing

See Contributing for setup and contribution guidelines. For a history of notable changes, see the Release Notes.

Acknowledgements

Special thanks to the libraries and tools used by Faithlife.Build:

• Bullseye
• Glob
• LibGit2Sharp
• McMaster.Extensions.CommandLineUtils
• Polly
• SimpleExec

Also thanks to Paul Knopf for this article, which inspired us to think beyond Cake.