Repository navigation
One .asmproj now builds for seven runtime identifiers from any build machine: win-x64,
win-arm64, linux-x64, linux-arm64, linux-musl-x64, osx-x64 and osx-arm64. x64
code is NASM (.asm), ARM64 code GNU syntax (.s) for the bundled llvm-mc. A C# project
that references an .asmproj gets the binary of the platform it is built or run for, chosen
by .NET's own runtime identifier rules. Toolchain 0.2.0 comes with it: llvm-mc, and build
machines for Windows on Arm and Linux ARM64. CI runs on all five build machines, each running
its own platform's outputs.
Migration from 0.2.0, without a compatibility layer:
| 0.2.0 | 0.3.0 |
|---|---|
| no RID: Linux x64 implied | <RuntimeIdentifiers>linux-x64</RuntimeIdentifiers>, or more. Required: a project that lists none is built for what its referencing projects ask for, or for -r, or stops with ASM0010, which names all three ways |
outputs in bin/<Configuration>/<tfm>/ |
outputs in bin/<Configuration>/<tfm>/<rid>/, as for dotnet build -r |
AsmTargetRid, AsmFormat (fixed at linux-x64, elf64) |
removed: RuntimeIdentifier decides the format and the linker |
packages with native/linux-x64/<tfm>/ and runtimes/linux-x64/native/ |
native/<rid>/<tfm>/ and runtimes/<rid>/native/ for every RID the project builds |
global f:function, call f wrt ..plt, section .note.GNU-stack in every source |
the same in Linux-only files. A source for several OSes uses asmsdk.inc (FUNCTION f, call f PLT) and wraps the note in %ifdef LINUX: macho64 stops on all three |
call helper wrt ..plt (or a hidden helper) for a call within one .so |
a plain call helper links: Linux shared libraries are linked -Bsymbolic. The PLT is for other libraries |
Added
- Runtime identifiers, as in .NET.
RuntimeIdentifierslists the platforms; each is an
inner build with the globalRuntimeIdentifier, and a build without one (the RID outer
build) builds each, the way a multi-targeted project builds each framework. Each inner
build prints<Project> -> <output>. ErrorsASM0010(no RID),ASM0011(a RID outside
the seven),ASM0012(a RID the project does not list). In a solution build, a project
that lists no RID builds nothing by itself, with a message. - Sources per RID, by file name. The extension is the language:
.asm(NASM) builds the
x64 RIDs,.s(GNU syntax, llvm-mc) the ARM64 ones. A qualifier before the extension
narrows a file: a RID (x.win-x64.asm), an OS family (win,linux,linux-musl,
osx),unix, or a CPU (x64,arm64). For each RID, the most specific file of a name
wins. ErrorsASM0020(a tie),ASM0021(a NASM file for ARM64 only),ASM0023(a RID
no source builds),ASM0024(a source listed twice).AsmLlvmMcFlagsand
AsmLlvmMcCommandfor llvm-mc. - The platform layer, on every include path:
asmsdk.inc(NASM):FUNCTION,LOCAL_FUNCTIONandHIDDEN_FUNCTION(exported,
file-local, global but exported from no image),RETURN,ENDFUNCTION, with exports per
object format and the callee-saved registers each OS expects;ARG1..ARG6(and their
32-, 16- and 8-bit forms),SHADOW_SPACE,PLT.asmsdk-gnu.inc(llvm-mc):FUNCTION,LOCAL_FUNCTION,HIDDEN_FUNCTION,ENDFUNCTION,
CALL,TAILCALL,ADDRESS,RODATA.- Defines
WINDOWS,LINUX,MACOS,MUSL,X64,ARM64;ASMSDK_EXPORTS_FILEwith
anExportsFile, andASMSDK_EXECUTABLEin a program.
TargetFramework=libcon every RID, with no sysroot or platform SDK: the SDK writes the
stand-ins from symbol lists instubs/(AsmWriteCLibraryStub).- Linux: a stub
libc.so.6(glibc) orlibc.musl-x86_64.so.1(musl, with musl's loader),
andlibasmsdk_nonshared.awithatexit, which glibc keeps out oflibc.so.6.crt1
for x64 and ARM64. - macOS:
libSystem.tbd; dyld callsmain(LC_MAIN).AsmMacOSMinimumVersion
(default 11.0). - Windows:
ucrtbase.lib(the Universal C Runtime) withmainCRTStartup, and
asmsdk_winstdio.lib:printf,fprintf,sprintf,snprintf, theirvforms,
sscanfandatexit, which the UCRT headers define inline anducrtbase.dlldoes not
export. - kernel32 is linked into every Windows output, the stable way to the OS (Windows system
call numbers change between releases). AsmLibcSymboladds names on every OS. A macOS freestanding program isASM0015: Apple
supports no static executables.
- Linux: a stub
- One
ExportsFilefor every OS: a version script on Linux,-export:names on Windows
(andFUNCTIONthen writes no directive),-exported_symbolon macOS.ASM0030for what
only ELF can express. - .NET consumers get the right binary. Every
.asmprojcarries an implicit
PackageReferencetoAsmFoundation.Sdk, whosebuildTransitivetargets reach the .NET
projects that reference it:- a portable build gets every RID's library under
runtimes/<rid>/native/, listed in
deps.json(ASM0042), so the .NET host loads the right one; - a RID-specific build gets the RID that serves it best by the .NET SDK's RID graph, copied
flat (ASM0040,ASM0041); <ProjectReference … RuntimeIdentifiers="a;b" />narrows the RIDs built;- static libraries, programs and objects are skipped, and the app's publish properties
(SelfContained,PublishAot, …) are not passed on; DisableAsmConsumerTargetsturns it off.
- a portable build gets every RID's library under
- Packages for every RID:
runtimes/<rid>/native/andnative/<rid>/<tfm>/(static
libraries, and the import libraries of Windows DLLs). The generated props give an asm
consumer its RID's build by the RID graph, orASM0060. The implicit SDK dependency is
removed from the.nuspec(ASM0050). - Image checks (
AsmCheckImage), after each Windows and macOS link, for load-time fixups
the loader cannot apply but the linker accepts:ASM0080for a 32-bit absolute address in a
64-bit Windows image (lld-link links a DLL based at 0x180000000 with one, silently; MSVC's
linker refuses it),ASM0081for a fixup in a read-only Mach-O segment (a text relocation,
from the rebase or bind opcodes or the chained fixups),ASM0082for an unreadable image.
A failed check deletes the image, so the next build checks again. - Toolchain 0.2.0:
llvm-mc; packages forwin-arm64(native LLVM, NASM's x64 build
under emulation) andlinux-arm64(NASM built from source). Intel Macs and musl hosts have
no package (LLVM publishes no binaries for them):ASM0006namesAsmToolchain=System.
ASM0004for a.ssource with a toolchain withoutllvm-mc,ASM0005for a Windows or
macOS RID, or the Linux RID of the other architecture, with the System toolchain's GNUld. BinariesCopyPath: where a .NET project keeps the asm libraries, for build and publish:
on aProjectReferenceto an.asmproj, on aPackageReferenceto an asm package, or as
the project's property.Runtimes(runtimes/<rid>/native/),AppFolder,RidFolders
(<rid>/),Auto(the default: NuGet's layout,runtimes/portable and the app folder for
one RID), or any folder inside the output with an optional{rid}(native/{rid}). The
reference wins, then the property, then the choice of a .NET library the asm library comes
through (so the attribute on a wrapper library's reference shapes the app's output too),
thenAuto. ErrorsASM0043(a value that leaves the output or is malformed) and
ASM0044(two files on one path: a folder without{rid}in a build of several RIDs of one
OS); warningASM0046(two libraries in between disagree).- The app finds them wherever they go, with no code of its own: its
deps.jsonlists every
asm library withlocalPath, asruntimeTargetsin a portable app and as plainnative
assets in an app for one RID. Measured with .NET 10 on Windows and Linux: the host loads from
any folder so named, framework-dependent and self-contained; a self-contained app ignores
runtimeTargets, and withoutlocalPaththe host looks only beside the app. - A generated fallback loader for what reads no
deps.json: a C# project for .NET 5 or
later that puts an asm library anywhere but the app folder gets
obj/.../AsmNativeLibraryLoader.g.cs, anAssemblyLoadContext.ResolvingUnmanagedDll
handler that runs only after .NET's own probing and any resolver of yours failed. It is how
a NativeAOT program findsnative/x.dll, and how an app finds a library that reaches it
through a class library whose asm reference does not flow (PrivateAssets="all").
AsmGenerateNativeLibraryLoader=falseturns it off. PrivateAssets="all"packs the asm binaries into a .NET library's package: every RID's
library underruntimes/<rid>/native/, with no dependency on the asm package; without it,
the reference stays a package dependency, as NuGet makes anyProjectReference. Within the
solution, an app that references such a library by project gets neither the asm reference
nor AsmSdk's targets, and copies the files where the library'sBinariesCopyPathput them:
a .NET project hands its asm references' files on already laid out (they are marked
Private="false"and delivered through its own copy and publish lists, with
ExcludeFromSingleFilefor single-file publishes), because what
GetCopyToOutputDirectoryItemshands on is fixed before any later target could move it.- Packages with asm libraries carry .NET consumer targets (
buildTransitive/<tfm>/<id>.targets,
plain MSBuild, named for the package only), which give their .NET consumers
BinariesCopyPathwithout depending on AsmFoundation.Sdk (an asm package still does not:
NU1605 for consumers on an older SDK). They move NuGet's own items; the .NET SDK then writes
the newlocalPathintodeps.jsonitself. - Realistic samples, each a complete program:
samples/Crc32C: CRC-32C as a freestanding shared library for all seven RIDs: x64 in
NASM throughasmsdk.inc, ARM64 in GNU syntax.ExportsFilekeeps five names (versioned
CRC32C_1.0on Linux). The first call picks one of three paths: a table, the hardware
CRC instruction (SSE4.2crc32, ARM64crc32cx), or a 3-way kernel merged with
PCLMULQDQ or PMULL. The assemblers compute the table and the merge constants
(x^(8n−33) mod P). ARM64 detection per OS: the ID registers on Linux,
IsProcessorFeaturePresenton Windows, always the 3-way path on Apple silicon.samples/Crc32C.Net: its C# API ([LibraryImport],SuppressGCTransitionfor inputs
up to 4 KiB,DisableRuntimeMarshalling), packed asSamples.Crc32C.Net, which
depends on the asm packageSamples.Crc32C.samples/Crc32C.Tests(xunit v3, 21 tests: every path against a bit-at-a-time C#
reference) andsamples/Crc32C.Bench(BenchmarkDotNet, against
BitOperations.Crc32C), both on every platform.samples/consumers/Crc32C.App: a .NET program that uses the library through the two
packages, by version.samples/WordCount:wcon glibc, with libc calls through the PLT,stderrthrough the
GOT,warn/warnxadded withAsmLibcSymbol, and SSE2 counting.samples/HexDump:xxdwithout libc, in system calls alone; its output is
byte-identical toxxd's, from a static executable of about 4 KB.
- Tests:
CrossPlatformTests(formats, exports, qualifiers, the C library of each OS,
programs' exports, the .NET consumer per RID, packages, the RID errors, the image checks,
each machine's own build run natively, the x64 build under emulation on ARM64 machines,
-o),DotnetAppTests(a .NET program that reaches the asm project through a class
library: RID-specific build and publish,-o, single file with the library beside it and
inside it, the publish switches on the command line),DiagnosticsTests(NASM's errors at
their line,ASM0005for the System toolchain),InteropTests(the interop tour,
tests/projects/Interop: every way C# calls an asm library, 51 checks on x64 and 48 on
ARM64, run natively on each of the five CI machines, and again withBinariesCopyPath
native/{rid}andRidFolders),NativeLayoutTests(everyBinariesCopyPathvalue and
where it comes from, builds for one RID, self-contained, single-file and NativeAOT
publishes that run,ASM0043andASM0044, the generated loader, a private reference
through a class library in build, single-file publish and pack, and the .NET consumers of
both package kinds), andExampleTestsfor every fact the documentation states about the
samples. AsmSdk.Tests has 165 tests. - Documentation: a Platforms and runtime identifiers guide; every guide, the reference and
the toolchain pages for the seven RIDs; an Examples section that walks through the samples;
and, for AI tools,llms.txt,llms-full.txtand a Markdown copy of every page
(page.html.md), written after each site build bydocs/llms.cs.
Changed
- Linux shared libraries link
-Bsymbolic: a library's references to its own global
symbols bind to the library, as on Windows and macOS.<LinkerArg Include="-Bno-symbolic" />
restores ELF's interposition. - Programs export nothing without an
ExportsFile:FUNCTION mainmademainan export,
and a Windows.exethen got a stray import library. A Windows program links-noimplib
unless itsExportsFileexports something. - NASM reports in Visual C++'s format (
-Xvc):x.asm(12): error : …. MSBuild recognizes
it, so an error or warning is an MSBuild one with its file and line, which IDEs list and
open. NASM's defaultx.asm:12: error:(no column) was plain output: the IDE showed only
ASM0007andMSB3073. A NASM warning now counts as an MSBuild warning, so a build with
-warnaserrorfails on one. dotnet build -o <folder>of an asm project with several RIDs puts each RID in
<folder>/<rid>/(<folder>/<tfm>/<rid>/when it targets both frameworks), and so does an
explicitOutDir. A global output folder is never extended by the RID, and the RIDs
overwrote each other's files.- The default sources are
**/*.asmand**/*.s. AsmToolchainVersiondefaults to 0.2.0.- The Crc32C sample's paths are named for every CPU:
crc32c_append_hardwareand
crc32c_append_hardware_3way, andCrc32CPath.HardwareandHardwareThreeWayin C#. samples/consumermoved tosamples/consumers/Hello.Consumer, next toCrc32C.App.samples/global.jsonselects Microsoft.Testing.Platform fordotnet test, which the
samples' xunit v3 project needs.
Fixed
- A glibc program that called
atexitlinked but did not start: glibc keepsatexitin
libc_nonshared.a, notlibc.so.6. The SDK now links its own. - A
ProjectReferenceto anOutputType=Objectsproject failed to link (cannot open <referencing project>/obj/…/x.o): the object paths were relative to the wrong folder. - A failed assembler run could leave an empty object that later builds took as up to date.
The object is now deleted, and the build reportsASM0007with the source's name.
Found by a manual QA of C# with asm projects (2026-11-20: a solution of three asm projects and
three .NET projects, every interop technique, every build and publish mode, run on Windows,
Ubuntu, Alpine, Linux ARM64 and a clean Windows 11 with only the .NET SDK):
- A single-file publish lost the asm library.
dotnet publish -r win-x64 -p:PublishSingleFile=trueput it neither in the bundle nor beside it (NETSDK1236), and
the program failed withDllNotFoundException. On Linux and macOS,
IncludeNativeLibrariesForSelfExtractleftlib<name>.soand.dyliboutside the bundle.
The .NET SDK decides byAssetType, whichGetCopyToPublishDirectoryItemsdrops: the
consumer targets now mark the asm librariesAssetType=native, as NuGet marks a package's.
The library goes beside the bundle, or inside it withIncludeNativeLibrariesForSelfExtract. - A RID-specific build or publish through a class library (app → C# library →
.asmproj)
carried every RID'sruntimes/<rid>/native/copy. The class library is RID-agnostic, so it
is built portable and hands them on: 11 dead files in the QA solution, and Windows and macOS
libraries in Linux container images. They are now left out, as NuGet leaves out other RIDs'
assets. dotnet build -r <rid> -o <folder>through a class library failed to link: the global
output folder reached the asm projects, every RID of the portable build wrote into it, and a
link read another machine's static library ("machine type x64 conflicts with arm64"). The
consumer targets no longer pass the app's output folder (OutputPath,OutDir) to asm
projects, which build in their ownbin/; the app's folder gets the copies.dotnet publish -p:PublishAot=trueor-p:PublishTrimmed=truestopped NuGet's restore in
every asm project (NETSDK1207,NETSDK1124): a command-line property reaches every project
of the restore graph, where no consumer target can remove it.Sdk.propsnow declares the
.NET publish switchesTreatAsLocalPropertyand sets them tofalse.AsmToolchain=Systemfor the Linux RID of the other architecture failed in GNUldwith
"file in wrong format" (an x64 machine'sldlinks x64 ELF only). It stops withASM0005,
which namesld.lldor a crossld.
Removed
AsmTargetRidandAsmFormat: the RID decides the platform and the object format.stubs/libc.asm: the C library stand-ins are written from the symbol lists.