Extending the build
How the SDK plugs into MSBuild, what makes a build incremental, and how to add your own steps without fighting it.
Package layout
AsmFoundation.Sdk.<version>.nupkg (package type MSBuildSdk) contains:
Sdk/Sdk.props imported first: switches off the managed build
Sdk/Sdk.targets imported last: wires in everything below
Sdk/AsmFoundation.Sdk.Version.props generated at pack time: SDK and default toolchain versions
targets/AsmFoundation.Properties.targets defaults, RIDs, output names, toolchain selection
targets/AsmFoundation.Build.targets items, toolchain checks, RID dispatch, assemble, stubs, link
targets/AsmFoundation.References.targets ProjectReference handling in both directions
targets/AsmFoundation.Pack.targets native package layout per RID and consumer props
buildTransitive/AsmFoundation.Sdk.targets the .NET consumer targets (runtimes/<rid>/native/, deps.json)
include/asmsdk.inc, include/asmsdk-gnu.inc the platform layer for NASM and llvm-mc sources
stubs/*.symbols the C library and kernel32 symbol lists
stubs/crt1*, wincrt-*, nonshared-*, winstdio-* startup code and the archives a C runtime would supply
tasks/netstandard2.0/AsmFoundation.Sdk.Tasks.dll the SDK's MSBuild tasks
Design choices:
- It rides on
Microsoft.NET.Sdk, the way Microsoft's NoTargets SDK does. That brings the standard restore,PackageReference,ProjectReference,Version,dotnet packand solution builds. - It replaces only the steps that assume a managed assembly:
CoreCompile,CreateManifestResourceNames,CopyFilesToOutputDirectory,GetTargetPathWithTargetPlatformMoniker,GetCopyToOutputDirectoryItemsandGetCopyToPublishDirectoryItems. MSBuild keeps the last definition of a target, so the SDK's files are imported afterMicrosoft.NET.Sdk's targets.
The target graph
Build (no RuntimeIdentifier: the RID outer build)
└─ _AsmBuildEachRuntimeIdentifier ── _AsmCheckRuntimeIdentifiers
└─ Build with RuntimeIdentifier=<rid>, for each RID
Build (an inner build, RuntimeIdentifier=<rid>)
└─ CoreBuild
├─ ResolveProjectReferences (standard; builds referenced projects for this RID)
├─ CoreCompile = AsmAssemble ; AsmLink
│ AsmAssemble ── AsmPrepare ── _AsmCheckRuntimeIdentifiers, _AsmResolveToolchain
│ └─ _AsmResolveProjectReferences ── ResolveProjectReferences
│ AsmLink ────── AsmAssemble, _AsmBuildSystemLibraries, _AsmBuildCrt
└─ CopyFilesToOutputDirectory (prints "<Project> -> <output>")
Pack (per target framework)
└─ _AsmPackNativeContent ── _AsmGetRidPackContent in each RID's inner build
| Target | Inputs → outputs | Condition |
|---|---|---|
AsmAssemble |
the sources selected for the RID, @(_AsmDependency), the project file, the SDK's targets → %(ObjectFile), batched per source |
always |
_AsmBuildSystemLibraries |
the SDK's symbol lists and stub sources, the project file → obj/…/asm/stubs/: the C library stand-in, kernel32.lib |
a shared library or executable that uses the C library, and every Windows one |
_AsmBuildCrt |
stubs/crt1.asm, crt1-arm64.s or wincrt-<arch> → obj/…/asm/stubs/crt1.o or wincrt.obj |
a Linux or Windows libc executable without StartupObject |
AsmLink |
@(_AsmObject), @(_AsmLinkInput), the ExportsFile, the project file → $(TargetPath), $(AsmStaticLibraryPath) |
OutputType is not Objects |
AsmPrepare computes, once:
- every object path, mirroring the source's subfolder, so
a/x.asmandb/x.asmdon't collide; - the include directories, local ones first, each with a trailing
/; - the dependency list:
@(AsmInclude), plus every**/*.incunder include directories that carryAsmOrigin; - the
-Darguments fromDefineConstants, to whichProperties.targetshas appendedDEBUGorRELEASE, andFREESTANDINGorLIBC; - the
ExportsFile(--version-script) andLinkerArgarguments of the link; - the link inputs, from
@(AsmLinkLibrary).
All paths handed to tools use forward slashes. A trailing backslash before a closing
quote ("C:\dir\") would escape the quote under Windows command-line rules and merge two
arguments into one.
Incremental builds
An object is up to date when it is newer than its source, every dependency
.incand the project file. Editing any.incin the dependency list reassembles every source of the project. That is coarse, but never stale.A link is up to date when the output is newer than every object, every link input and the project file. A rebuild of a referenced library re-links its consumers.
A no-change rebuild runs no tool at all. The one exception is the
chmod +xon Linux and macOS hosts.What is not tracked:
Not tracked Effect Fix .incfiles in your ownAsmIncludeDirectoryitems outside the projectstale objects list them as AsmIncludeitemsincbinfilesstale objects list them as AsmIncludeitems: any file works as a dependencyinclude files without the .incextensionstale objects the same Directory.Build.propsand other imported filesa changed define does not reassemble anything rebuild ( dotnet build --no-incremental) after changing them
How references are resolved
asm → asm:
ResolveProjectReferencesbuilds the referenced project._AsmResolveProjectReferencescalls itsGetAsmLinkInputstarget.- The returned items carry
AsmItemType.IncludeDirectoryitems are added toAsmIncludeDirectory, andLinkInputitems toAsmLinkLibrary, all withAsmOrigin="Project".
Transitive project references, which the .NET SDK adds, are processed the same way.
csproj → asm:
- The
.csprojcallsGetTargetPathWithTargetPlatformMoniker, which returns nothing, so no assembly reference is added and noMSB3246occurs. - Its consumer targets (
buildTransitive/AsmFoundation.Sdk.targets, through the implicitPackageReferenceto the SDK) pick the RIDs to build: the reference'sRuntimeIdentifiersfor a portable build, the best match by the RID graph for a RID-specific one. - It calls
GetCopyToOutputDirectoryItemsandGetCopyToPublishDirectoryItems, which return each RID's shared library withPreserveNewest: underruntimes/<rid>/native/in a portable build (also added todeps.json), flat in a RID-specific one.
- The
Restore: the
.asmproj's target frameworks stand fornetstandard1.0(freestanding) andnetstandard2.0(libc), which every.csprojmay reference. A.csprojgets thelibcbuild of a project that targets both. The asm project's ownPackageReferences flow to the.csprojas transitive dependencies, as they would for any project.
Extending the build
Hook your targets with BeforeTargets or AfterTargets on the public targets
(AsmPrepare, AsmAssemble, AsmLink). Underscore targets are internal and may change
between releases.
Generate an include file before assembling:
<Target Name="GenerateVersionInc" BeforeTargets="AsmPrepare">
<WriteLinesToFile File="$(IntermediateOutputPath)gen/version.inc"
Lines="%25define BUILD_VERSION "$(Version)""
Overwrite="true" WriteOnlyWhenDifferent="true" />
<ItemGroup>
<AsmIncludeDirectory Include="$(IntermediateOutputPath)gen/" />
<AsmInclude Include="$(IntermediateOutputPath)gen/version.inc" />
<FileWrites Include="$(IntermediateOutputPath)gen/version.inc" />
</ItemGroup>
</Target>
%25is MSBuild's escape for%. An unescaped%dewould be decoded as byte0xDE.WriteOnlyWhenDifferentkeeps the file's timestamp when its content is unchanged, so incremental builds stay incremental.- Run it before
AsmPrepare, so that the items exist when the include path and the dependencies are computed.
Generate a source file (for example a table computed by a .NET 10 file-based app):
<Target Name="GenerateTables" BeforeTargets="AsmPrepare" Inputs="tools/gen_tables.cs" Outputs="$(IntermediateOutputPath)gen/tables.asm">
<MakeDir Directories="$(IntermediateOutputPath)gen" /> <!-- a clean obj/ has no gen/ yet -->
<Exec Command="dotnet run tools/gen_tables.cs -- "$(IntermediateOutputPath)gen/tables.asm"" />
<ItemGroup>
<AsmSource Include="$(IntermediateOutputPath)gen/tables.asm" />
<FileWrites Include="$(IntermediateOutputPath)gen/tables.asm" />
</ItemGroup>
</Target>
With Inputs and Outputs on a target, MSBuild still runs the target's item groups when
it skips the target as up to date. The AsmSource item exists either way.
Keep tools out of design-time builds. IDEs run Compile and CoreCompile on every
project load with DesignTimeBuild=true (see IDEs). A target hooked to
AsmPrepare, AsmAssemble or AsmLink, as above, never runs then: CoreCompile, which
leads to them, is skipped. A target hooked anywhere else that runs a tool needs
Condition="'$(DesignTimeBuild)' != 'true'".
Post-link steps (strip a copy, sign, compute a checksum):
<Target Name="StripCopy" AfterTargets="AsmLink" Condition="'$(Configuration)' == 'Release'">
<Copy SourceFiles="$(TargetPath)" DestinationFiles="$(TargetDir)debug/$(TargetFileName)" />
<!-- the shipped file is linked with -s via a LinkerArg item; the copy keeps symbols for debugging -->
</Target>
Change a link line:
- Use
LinkerArgitems for flags,ExportsFilefor a version script, andAsmLinkLibraryitems for inputs. - Don't override
AsmLink. To change the whole link, set<OutputType>Objects</OutputType>and link in your own target, afterAsmAssemble, from@(AsmSource->'%(ObjectToolPath)').
Inspecting a build
dotnet build -v:nprints every NASM and linker command exactly as run. Copy one and re-run it from the project folder to experiment.dotnet msbuild X.asmproj -getProperty:TargetFileName -getProperty:AsmToolchainDirectoryshows evaluated properties, without building.dotnet msbuild X.asmproj -getItem:AsmSource -getItem:AsmIncludeDirectoryshows the items, as JSON.dotnet build -blwritesmsbuild.binlog. Open it in the MSBuild Structured Log Viewer to see every target, its skip reason (up to date) and every property.inspect_output.pyshows what came out.