Table of Contents

Build Definitions

A build definition is the central entry point for an Atom build. It declares which targets exist, what parameters are available, and how the build host is configured. For consumer builds, the recommended approach is an interface that extends IBuildDefinition; use a partial class when the build needs class-specific host configuration.

Define the build as an interface annotated with [BuildDefinition] and [GenerateEntryPoint]:

[BuildDefinition]
[GenerateEntryPoint]
internal interface IBuild : IBuildDefinition
{
    Target SayHello => t => t
        .DescribedAs("Prints a greeting")
        .Executes(() => Logger.LogInformation("Hello, World!"));
}

This pattern is recommended because the build can compose targets, parameters, and host configuration from module interfaces without putting all implementation in one type. The generated entry point discovers the interface members and runs the build.

Alternative: partial class builds

Use a partial class when the build itself needs class members, such as the optional OnConfigureHostBuilder host hook (an interface-based build can add them to its generated partial class Build instead):

[BuildDefinition]
[GenerateEntryPoint]
internal partial class Build : BuildDefinition
{
    Target SayHello => t => t
        .DescribedAs("Prints a greeting")
        .Executes(() => Logger.LogInformation("Hello, World!"));
}

The class must be partial so source generators can augment it, and it must derive from BuildDefinition or WorkflowBuildDefinition. It can also implement module interfaces in the same way as an interface-based build.

What the Source Generator Does

When you apply [BuildDefinition], the Atom source generator automatically:

  • Discovers all Target properties (including those from implemented interfaces) and populates the TargetDefinitions dictionary.
  • Discovers all [ParamDefinition] / [SecretDefinition] properties and populates the ParamDefinitions dictionary.
  • Generates the AccessParam method so the framework can inspect parameter values.

This means you never need to manually register targets or parameters — just declare them and the generator wires everything up.

[GenerateEntryPoint]

Adding this attribute causes the source generator to emit a Program.cs with a Main method:

// Auto-generated
AtomHost.Run<Build>(args);

If you need custom host configuration, omit [GenerateEntryPoint] and write your own entry point:

var builder = AtomHost.CreateAtomBuilder<Build>(args);
// customise builder.Services, builder.Configuration, etc.
builder.Build().UseAtom().Run();

Composing module interfaces

Targets and parameters are typically defined in interfaces so they can be shared across builds or published in module packages:

public interface IMyTargets : IBuildAccessor
{
    [ParamDefinition("greeting", "The greeting message")]
    string Greeting => GetParam(() => Greeting, "Hello");

    Target SayGreeting => t => t
        .DescribedAs("Says a greeting")
        .Executes(() => Logger.LogInformation(Greeting));
}

[BuildDefinition]
[GenerateEntryPoint]
internal partial class Build : BuildDefinition, IMyTargets { }

The source generator discovers SayGreeting and Greeting from IMyTargets and includes them in the build model.

[GenerateSolutionModel]

When applied alongside [BuildDefinition], this attribute generates a typed model of your solution's projects, giving you compile-time access to project paths.

OnConfigureHostBuilder / OnConfigureHost

Implement the optional static partial method OnConfigureHostBuilder on your build class to register additional services before the build runs, and OnConfigureHost to configure the built host:

static partial void OnConfigureHostBuilder(IHostApplicationBuilder builder) =>
    builder.Services.AddSingleton<IMyService, MyService>();

They run after the hooks of the module interfaces the build implements, without constructing the build definition. See Hosting for details, including interface-based builds.

Caching per-build values

BuildCache<T> is a thread-safe cache keyed by an IBuildAccessor (typically the build definition), for values that are expensive to compute and should be computed once per build:

private static readonly BuildCache<string> ChangelogCache = new();

string Changelog => ChangelogCache.GetOrAdd(this, _ => File.ReadAllText("CHANGELOG.md"));

Keys use reference equality, and entries live as long as the cache instance. Use Set, TryGetValue, Remove and Clear for explicit control.

Next steps