Changelog
All notable changes to AsmFoundation.Sdk and the AsmFoundation.Toolchain packages. The format follows Keep a Changelog, and versions follow Semantic Versioning.
The toolchain packages carry their own version (toolchain/versions.json).
Each SDK release names the one it was tested with.
[Unreleased]
Added
Programs get the asm shared libraries they link. A program that links an asm shared library (a
ProjectReference, or a package) gets it in each RID's output folder, with the run path that finds it there:- Linux:
DT_RUNPATH$ORIGIN; - macOS:
LC_RPATH@loader_path; - Windows: the program's own folder, which the loader searches first.
On Windows the program links the import library, and the DLL behind it is copied: referenced projects and packages now name that file (
AsmRuntimeFilemetadata).BinariesCopyPathplaces the libraries, as it does for a .NET app: the reference's value, then the property, thenAuto, which for a program means its own folder. The run path follows the folder ($ORIGIN/lib/linux-x64).- On Windows a folder other than the program's own is
ASM0047, since Windows has no run path. - A program that links no shared library is linked as before.
ASM0048(a warning) names an import library whose DLL a 0.3.0 package does not name.
Tests no longer set
LD_LIBRARY_PATHto run such a program.- Linux:
dotnet runruns asm programs. It builds the program and starts the build this machine can run, with the arguments after--unchanged. The order:- this machine's own RID, or another build it runs natively (on Linux, one whose loader is installed);
- one it emulates:
win-x64on Windows on Arm,osx-x64under Rosetta 2; - on Windows, a Linux build through WSL;
- a Linux build in a Docker container (
debian:stable-slim,alpine:3, another CPU under QEMU).
dotnet run -r <rid>runs that RID. Settings:AsmRunIn(Auto,Host,Wsl,Docker),AsmRunWslDistribution,AsmRunDockerImage, andRunArgumentsandRunCommandas in .NET. Errors:ASM0090(not a program),ASM0091(nothing here can run any build, with what was tried),ASM0092(not built),ASM0093(unknownAsmRunIn). Measured on Windows x64:win-x64natively,linux-x64through WSL,linux-musl-x64,linux-arm64andlinux-musl-arm64in Docker, with quotes and spaces in the arguments intact.dotnet publishpublishes asm programs and libraries:-r <rid>publishes that RID into .NET's folder (or-o);- without
-r, every RID the project lists, each intopublish/<rid>/(-o <folder>gives<folder>/<rid>/), or only the RIDs a referencing project asks for.
A publish holds the output, its PDB, a program's libraries where
BinariesCopyPathput them, and the files markedCopyToPublishDirectoryorCopyToOutputDirectory. It holds nothing the managed pipeline would add: notobj/<name>.dll(the MSB3030 of 0.3.0), and not a package'sruntimes/files copied flat. Release by default, as for .NET 8 projects (PublishRelease).A program as a dependency, the helper-process case:
- A .NET project that references an asm program, or its package, gets it with the libraries
it links. A portable build gets every RID's program in
runtimes/<rid>/native/, listed indeps.json; a RID-specific build gets its RID's next to the app.BinariesCopyPathplaces it, and its libraries keep their place relative to it, because its run path depends on that. The app finds it throughNATIVE_DLL_SEARCH_DIRECTORIES(the guide has the code). - An asm program that references an asm program copies it, with its libraries, where its
BinariesCopyPathsays, on Windows too. dotnet packof a program puts each RID's program and libraries inruntimes/<rid>/native/, with props that deliver it to an asm consumer (AsmReferencedProgramitems).PrivateAssets="all"on a .NET library's reference to a program puts the program inside the library's package.- A program's own references default to
PrivateAssets="all", since it carries what it needs. A consumer no longer gets the program's libraries a second time as references of its own, and the program's package depends on nothing. - A packed program keeps its libraries next to it: NuGet copies
runtimes/files flat into an app built for one RID. Libraries in a subfolder stop the pack withASM0051. - Two files with the same bytes on one path (a library that the app references and that a
program's bundle also holds) are one file, not an
ASM0044.
Measured: a .NET app (portable, RID-specific, and
tools/{rid}) and an asm program started or carried the program, from a project reference, its package, and a .NET library's package.- A .NET project that references an asm program, or its package, gets it with the libraries
it links. A portable build gets every RID's program in
PackAsToolpacks a program as a .NET tool, in the package kinds the .NET 10 SDK writes for a platform-specific tool:- the top-level
DotnetToolpackage (tools/any/any/) names the command and the package of each RID; - one
DotnetToolRidPackageper RID (tools/any/<rid>/) holds the program, its libraries and data files, withRunner="executable".
dotnet tool install -g <id>installs the machine's package, and the command starts the program, with no .NET runtime.ToolCommandNamenames the command.dotnet pack -r <rid>packs one RID's package. Errors:ASM0052(settings file),ASM0053(not a program, or several target frameworks). Measured: installed and run on Windows x64, and in the .NET SDK containers for glibc and Alpine, where the command is a symbolic link into the tool store and$ORIGINstill finds the library.- the top-level
linux-musl-arm64, the eighth runtime identifier: musl distributions such as Alpine on ARM64 (AWS Graviton, Ampere, Linux VMs on Apple silicon). It works likelinux-musl-x64:- ARM64 code is assembled for llvm-mc's
aarch64-linux-musl, with theMUSLdefine; - a qualified
.sfile builds every RID its qualifier names, x64 ones too (as GNU-syntax x86-64). So a.squalifiedlinux-muslnow applies to both musl RIDs, and musl ARM64 code beside aname.linux-musl.asmtakes the RID qualifier,name.linux-musl-arm64.s. Otherwise both files claimlinux-musl-x64, and ASM0020 names the fix; - a
libcbuild links against musl'slibc.musl-aarch64.so.1, and its programs start with/lib/ld-musl-aarch64.so.1. The SDK's ARM64crt1andatexitserve musl as they serve glibc: musl's__libc_start_maintakes the same first three arguments and ignores the rest.
A .NET app built for
linux-musl-arm64now gets that build itself. Until now NuGet's fallback gave it thelinux-arm64build, which serves code without the C library but names glibc'slibc.so.6otherwise. Measured on Alpine ARM64 (under QEMU): alibcprogram, and a .NET app that loads the RID's library.- ARM64 code is assembled for llvm-mc's
tests/qa/delivery-matrix.cs, the delivery QA matrix that proved 0.3.0, as a .NET file-based app:dotnet run tests/qa/delivery-matrix.cs. It covers every way a .NET project gets an asm library:- a direct reference, or one through a class library, with or without
PrivateAssets="all"; - the asm package itself;
- a .NET package with the binaries inside, or one that depends on the asm package.
Each is built and published for every RID, in every layout. Every case is then checked by file, by object format (llvm-readobj), by
deps.json, and by running the program wherever the machine can: natively, in Linux containers, and for ARM64 under QEMU. On a Windows x64 machine with Docker that is 94 cases withlinux-musl-arm64(84 before it), all passing, with a negative control (NativeAOT without the generated loader must fail).- a direct reference, or one through a class library, with or without
Scenario tests (
tests/scenarios): whole small repositories, built and run as a user would. Each folder is a.slnxwith.csprojand.asmprojprojects, plus ascenario.jsonthat lists the commands to run on it. The commands can bedotnet build,run,test,publish,packandtool install, or the programs they produce. For each command the file says the exit status, the output and the files it must leave.ScenarioTestsruns every scenario as one test, in a fresh copy underartifacts/scenarios. The test's name lists every command, and its log shows each with its output. Adding a scenario needs no C#, and--filter-trait "Scenario=<Name>"runs one alone. The first eight:- a C# app with an asm library;
- xunit unit tests of asm code (
dotnet test); - an asm program that links an asm library;
- NumSharp arrays computed on by asm kernels;
KvAsm.Clienttalking to the KvAsm server image, with an asm checksum;- an OptunaSharp study that tunes an asm function;
- a C# app that starts an asm program it references;
- an asm program packed as a .NET tool and installed.
Our other projects' packages come from nuget.org at the versions pinned in
tests/scenarios/Directory.Packages.props, so the scenarios also restore under central package management. See Scenario tests.
Fixed
UpdateandRemoveof default items work in an.asmproj. The defaultAsmSource,AsmIncludeandNoneglobs were declared after the project body, so<None Update="data.txt" CopyToOutputDirectory="PreserveNewest" />matched nothing and was silently ignored. They are now declared inSdk.props, before the body, where .NET declares its own.EnableDefaultAsmItemsandEnableDefaultNoneItemsset in the body still turn them off: MSBuild evaluates every property before any item.CopyToOutputDirectoryandCopyToPublishDirectorywork in an.asmproj. The SDK'sCopyFilesToOutputDirectorycopied nothing but printed the output's path. Marked files now reach every RID's output folder and publish folder, at theirTargetPath.
[0.3.0] — 2026-11-21
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).AsmLlvmMcFlagsandAsmLlvmMcCommandfor 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.crt1for x64 and ARM64. - macOS:
libSystem.tbd; dyld callsmain(LC_MAIN).AsmMacOSMinimumVersion(default 11.0). - Windows:
ucrtbase.lib(the Universal C Runtime) withmainCRTStartup, andasmsdk_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 implicitPackageReferencetoAsmFoundation.Sdk, whosebuildTransitivetargets reach the .NET projects that reference it:- a portable build gets every RID's library under
runtimes/<rid>/native/, listed indeps.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) andASM0044(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 plainnativeassets 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 ignoresruntimeTargets, 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 getsobj/.../AsmNativeLibraryLoader.g.cs, anAssemblyLoadContext.ResolvingUnmanagedDllhandler 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 markedPrivate="false"and delivered through its own copy and publish lists, withExcludeFromSingleFilefor single-file publishes), because whatGetCopyToOutputDirectoryItemshands 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 consumersBinariesCopyPathwithout 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 (versionedCRC32C_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, againstBitOperations.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 withBinariesCopyPathnative/{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-noimplibunless 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 onlyASM0007andMSB3073. 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_hardwareandcrc32c_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 keepsatexitinlibc_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 reports
ASM0007with 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.
0.2.0 — 2026-11-18
An .asmproj now uses the .NET property of the same purpose wherever one exists, and 0.1.0's
own names are gone, without a compatibility layer. A project
that still sets one fails with an error that names the replacement (ASM0100 to ASM0108),
all of them in one build. Migration:
| 0.1.0 | 0.2.0 |
|---|---|
<AsmLibraryName>hello</AsmLibraryName> |
<AssemblyName>hello</AssemblyName> (still libhello.so, libhello.a, hello) |
<AsmRuntime>Freestanding</AsmRuntime> (the default) |
<TargetFramework>freestanding</TargetFramework> (still the default) |
<AsmRuntime>Libc</AsmRuntime> |
<TargetFramework>libc</TargetFramework> |
<AsmDefineConstants>A;B=1</AsmDefineConstants>, <AsmDefine Include="C" /> |
<DefineConstants>A;B=1;C</DefineConstants> |
<AsmDebugInfo>true</AsmDebugInfo> |
<DebugSymbols>true</DebugSymbols> (<DebugType>none</DebugType> turns it off) |
<AsmEntryPoint>my_entry</AsmEntryPoint> |
<StartupObject>my_entry</StartupObject> |
<AsmLinkFlags>-z defs --version-script=x.map</AsmLinkFlags> |
<LinkerArg Include="-z defs" /> and <ExportsFile>x.map</ExportsFile> |
<AsmOutputKind>StaticLibrary</AsmOutputKind> |
<OutputType>StaticLibrary</OutputType> |
outputs in bin/<Configuration>/ |
outputs in bin/<Configuration>/<TargetFramework>/, as in .NET |
PackageId defaults to AssemblyName, as in .NET, and 0.1.0's AsmLibraryName did not
touch it. Two projects that share an AssemblyName (a static and a shared build of one
library) therefore restore with Ambiguous project name: give each its own PackageId.
Added
- IDE integration, like a
.csproj: Rider, Visual Studio and VS Code show an.asmproj's files, and opening a solution no longer assembles or links anything.- The asm item types are declared (
AvailableItemName): IDEs show only the item types they know plus those, so in 0.1.0 Rider showed every.asmprojempty.AsmSourceandAsmIncludeare also offered as build actions. - Every other file of the project folder is a
Noneitem, as in a.csproj(a linker script, a C header, a README).EnableDefaultNoneItems=false, .NET's own switch, turns it off. The managed SDK'sNoneglob could not be reused: with no language source extension, it removes every file it included. - Design-time builds run no tool. IDEs build a project's design-time view on every
load, calling
CompileandCoreCompilewithDesignTimeBuildandSkipCompilerExecution. 0.1.0 assembled and linked there: slow loads, races with the real build, and errors such as lld's "cannot open libgrpcasm.a" shown as project warnings when a referenced project was not built yet.CoreCompilenow honors both properties, as Csc does. - The fast up-to-date checks of Visual Studio and Rider get
UpToDateCheckInput(the sources, includes andExportsFile) andUpToDateCheckBuilt(the output), so editing a.asmfile makes the IDE call MSBuild.
- The asm item types are declared (
- The tooling is .NET only. The end-to-end test is the xunit v3 project
tests/AsmSdk.Tests(dotnet test, 48 tests), and the toolchain is staged bytoolchain/fetch.cs, a .NET 10 file-based app (dotnet run toolchain/fetch.cs -- --rid win-x64). Neither the repository nor CI needs Python.- The tests cover what
tests/run.pychecked, one test per expectation, plus IDE integration. Through MSBuild they check the declared item types, that every file is one item, the up-to-date inputs and outputs, and a replay of Rider's design-time build against a control build that does run the tools. fetch.csdecodes.tar.xzwith SharpCompress (.NET has no xz decoder). On the 901 MB Windows LLVM archive it took 83.5 s against 78.0 s for Python's lzma, and staged byte-identical tools.VERSIONS.txtnow ends its lines with LF on every build machine.
- The tests cover what
- Target frameworks:
freestandingandlibc, and<TargetFrameworks>freestanding;libc</TargetFrameworks>to build both, exactly like a multi-targeted.csproj. Behind the names, freestanding is netstandard1.0 and libc is netstandard2.0, so NuGet's own rules say who may use what:- a libc project may reference freestanding projects and packages;
- a freestanding project that references a libc-only project fails at restore with
NU1201, and a libc-only package withNU1202; - a project or package that targets both gives each consumer the nearest build. A .NET project gets the libc build.
- Implicit preprocessor symbols, as in C#:
DEBUGorRELEASE(the configuration), andFREESTANDINGorLIBC(the target framework), appended after the project body, so settingDefineConstantsnever drops them.DisableImplicitConfigurationDefinesandDisableImplicitFrameworkDefinesturn them off. - NativeAOT's names for extra link input:
LinkerArgitems, andExportsFilefor the version script (with--export-dynamicfor an executable, as NativeAOT does). Editing the version script relinks. - Package layout per target framework:
build/<framework>/,buildTransitive/<framework>/, an emptylib/<framework>/_._marker,native/linux-x64/<tfm>/, and, when a project multi-targets,runtimes/linux-x64/nativeassets/<framework>/for its shared libraries. tests/projects: test projects for the compatibility errors, the removed settings,StartupObject,ExportsFile,LinkerArg,DefineConstants,DebugSymbols, a multi-targeted project referencing a single-targeted one, and a libc package consumed by version.tests/AsmSdk.Testsbuilds them all, and runs the executables.- The
Hello.Librarysample targets both frameworks and reports which build it is (hello_uses_libc), soHello.Netproves it was given the libc build. - The documentation site, https://asmfoundation.github.io/AsmSdk/: guides, the
complete
.asmprojreference, the toolchain and the ecosystem. It is built with DocFX fromdocs/, with DocFX pinned in.config/dotnet-tools.json, and deployed to GitHub Pages by.github/workflows/docs.yml.
Changed
docs/asmproj.mdis now the complete reference: evaluation order, every item and its metadata, link lines, the libc stub, and generated files.Two corrections in it:
- NASM's messages become MSBuild errors with file and line only with
-Xvc.lld's messages always do. - A function missing from the libc stub fails executables, not shared libraries.
- NASM's messages become MSBuild errors with file and line only with
The package's project URL points at the documentation site, from the next release.
Outputs go to
bin/<Configuration>/<TargetFramework>/andobj/<Configuration>/<TargetFramework>/, as in .NET:bin/Release/libc/hello-libcinstead ofbin/Release/hello-libc.Debug information follows
DebugSymbolsandDebugType: DWARF in Debug, none in Release, as before;DebugSymbols=trueadds it to Release, andDebugType=noneremoves it.Every page of the documentation site, the samples and the package readme use the 0.2.0 names.
Removed
tests/run.pyandtoolchain/fetch.py, replaced bytests/AsmSdk.Testsandtoolchain/fetch.cs(see Added).AsmLibraryName,AsmRuntime,AsmDefineConstants,AsmDefineitems,AsmDebugInfo,AsmEntryPoint,AsmLinkFlagsandAsmOutputKind. See the table above.- The hidden
netstandard2.0target framework of every 0.1.0 project. A project that sets it now fails withASM0003.
Fixed
- The build targets' comment on
reloc-abs-qwordsaid that a shared object always resolves adqof a label at load time. That holds only in a writable section:.data, or.data.rel.rodeclaredwrite. In.rodata, or in any section without the write flag, the link of a shared library or a Libc executable fails. The comment now says so, and explains why the warning can stay off: the linker rejects every case that cannot work. Only the comment changed; the build does the same. - The guide's jump-table rule now covers Libc executables, which are PIEs, as well as
shared libraries. It also says that a Freestanding executable, linked
-static, accepts adqof a label in any section. - Multi-targeting never worked in 0.1.0. The SDK set
TargetFrameworkbefore the project body, which turned anyTargetFrameworksinto a single-target build, and Microsoft.NET.Sdk gives the outer build of a project with an unknown extension the single-target common targets ("Non-CrossTargeting GetTargetFrameworks target should not be used in cross targeting (outer) build"). The default is now applied after the body, and the outer build getsMicrosoft.Common.CrossTargeting.targets. - A referenced
.asmprojcould be built with the referencing project'sTargetFramework._AsmResolveProjectReferencesnow removes the same global properties thatResolveProjectReferencesremoves. - A 0.1.0 package counted as compatible with every framework, because it had no
lib/folder. Thelib/<framework>/_._markers narrow it to the frameworks it was built for.
0.1.0 — 2026-11-17
The first release.
Added
.asmprojprojects (<Project Sdk="AsmFoundation.Sdk">). NASM sources become a Linux x86-64 shared library, static library or executable, or just objects, chosen with the csproj-styleOutputType.Two runtimes:
Freestanding(the default): raw system calls, nothing linked;Libc: glibc linked dynamically through a generatedlibc.so.6stub, so no sysroot is needed. ALibcexecutable starts inmainthrough the SDK'scrt1.
References:
ProjectReferencebetween.asmprojprojects adds the include folders and links the library;ProjectReferencefrom a.csprojcopies the shared library next to the program;PackageReferenceto an asm package adds the package's include folders and library.
dotnet packwrites native packages:include/;native/linux-x64/*.a;runtimes/linux-x64/native/*.so;- optional
src/; - generated
build/andbuildTransitive/props.
Exact incremental builds: a rebuild without changes starts no tool; an include file change reassembles the sources that can include it.
AsmFoundation.Toolchain0.1.0 forwin-x64,linux-x64andosx-arm64:- NASM 3.02: the official binary on Windows, built from source on Linux (statically) and on macOS (arm64);
- LLVM 23.1.5's
lld,llvm-arandllvm-readobj.
Every download is pinned by SHA-256 and verified before use.
Samples and an end-to-end test (
tests/run.py) that CI runs on Windows, Linux and macOS.- It checks every output's ELF properties: type, SONAME,
DT_NEEDED, interpreter, exports and archive members. - It runs the executables and a C# program that P/Invokes two asm shared libraries.
- It verifies the incremental builds.
- It checks every output's ELF properties: type, SONAME,