Table of Contents

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 (AsmRuntimeFile metadata).

    • BinariesCopyPath places the libraries, as it does for a .NET app: the reference's value, then the property, then Auto, 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_PATH to run such a program.

  • dotnet run runs asm programs. It builds the program and starts the build this machine can run, with the arguments after -- unchanged. The order:

    1. this machine's own RID, or another build it runs natively (on Linux, one whose loader is installed);
    2. one it emulates: win-x64 on Windows on Arm, osx-x64 under Rosetta 2;
    3. on Windows, a Linux build through WSL;
    4. 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, and RunArguments and RunCommand as in .NET. Errors: ASM0090 (not a program), ASM0091 (nothing here can run any build, with what was tried), ASM0092 (not built), ASM0093 (unknown AsmRunIn). Measured on Windows x64: win-x64 natively, linux-x64 through WSL, linux-musl-x64, linux-arm64 and linux-musl-arm64 in Docker, with quotes and spaces in the arguments intact.

  • dotnet publish publishes asm programs and libraries:

    • -r <rid> publishes that RID into .NET's folder (or -o);
    • without -r, every RID the project lists, each into publish/<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 BinariesCopyPath put them, and the files marked CopyToPublishDirectory or CopyToOutputDirectory. It holds nothing the managed pipeline would add: not obj/<name>.dll (the MSB3030 of 0.3.0), and not a package's runtimes/ 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 in deps.json; a RID-specific build gets its RID's next to the app. BinariesCopyPath places it, and its libraries keep their place relative to it, because its run path depends on that. The app finds it through NATIVE_DLL_SEARCH_DIRECTORIES (the guide has the code).
    • An asm program that references an asm program copies it, with its libraries, where its BinariesCopyPath says, on Windows too.
    • dotnet pack of a program puts each RID's program and libraries in runtimes/<rid>/native/, with props that deliver it to an asm consumer (AsmReferencedProgram items).
    • 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 with ASM0051.
    • 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.

  • PackAsTool packs a program as a .NET tool, in the package kinds the .NET 10 SDK writes for a platform-specific tool:

    • the top-level DotnetTool package (tools/any/any/) names the command and the package of each RID;
    • one DotnetToolRidPackage per RID (tools/any/<rid>/) holds the program, its libraries and data files, with Runner="executable".

    dotnet tool install -g <id> installs the machine's package, and the command starts the program, with no .NET runtime. ToolCommandName names 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 $ORIGIN still finds the library.

  • linux-musl-arm64, the eighth runtime identifier: musl distributions such as Alpine on ARM64 (AWS Graviton, Ampere, Linux VMs on Apple silicon). It works like linux-musl-x64:

    • ARM64 code is assembled for llvm-mc's aarch64-linux-musl, with the MUSL define;
    • a qualified .s file builds every RID its qualifier names, x64 ones too (as GNU-syntax x86-64). So a .s qualified linux-musl now applies to both musl RIDs, and musl ARM64 code beside a name.linux-musl.asm takes the RID qualifier, name.linux-musl-arm64.s. Otherwise both files claim linux-musl-x64, and ASM0020 names the fix;
    • a libc build links against musl's libc.musl-aarch64.so.1, and its programs start with /lib/ld-musl-aarch64.so.1. The SDK's ARM64 crt1 and atexit serve musl as they serve glibc: musl's __libc_start_main takes the same first three arguments and ignores the rest.

    A .NET app built for linux-musl-arm64 now gets that build itself. Until now NuGet's fallback gave it the linux-arm64 build, which serves code without the C library but names glibc's libc.so.6 otherwise. Measured on Alpine ARM64 (under QEMU): a libc program, and a .NET app that loads the RID's library.

  • 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 with linux-musl-arm64 (84 before it), all passing, with a negative control (NativeAOT without the generated loader must fail).

  • Scenario tests (tests/scenarios): whole small repositories, built and run as a user would. Each folder is a .slnx with .csproj and .asmproj projects, plus a scenario.json that lists the commands to run on it. The commands can be dotnet build, run, test, publish, pack and tool install, or the programs they produce. For each command the file says the exit status, the output and the files it must leave. ScenarioTests runs every scenario as one test, in a fresh copy under artifacts/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.Client talking 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

  • Update and Remove of default items work in an .asmproj. The default AsmSource, AsmInclude and None globs were declared after the project body, so <None Update="data.txt" CopyToOutputDirectory="PreserveNewest" /> matched nothing and was silently ignored. They are now declared in Sdk.props, before the body, where .NET declares its own. EnableDefaultAsmItems and EnableDefaultNoneItems set in the body still turn them off: MSBuild evaluates every property before any item.
  • CopyToOutputDirectory and CopyToPublishDirectory work in an .asmproj. The SDK's CopyFilesToOutputDirectory copied nothing but printed the output's path. Marked files now reach every RID's output folder and publish folder, at their TargetPath.

[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. RuntimeIdentifiers lists the platforms; each is an inner build with the global RuntimeIdentifier, 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>. Errors ASM0010 (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. Errors ASM0020 (a tie), ASM0021 (a NASM file for ARM64 only), ASM0023 (a RID no source builds), ASM0024 (a source listed twice). AsmLlvmMcFlags and AsmLlvmMcCommand for llvm-mc.
  • The platform layer, on every include path:
    • asmsdk.inc (NASM): FUNCTION, LOCAL_FUNCTION and HIDDEN_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_FILE with an ExportsFile, and ASMSDK_EXECUTABLE in a program.
  • TargetFramework=libc on every RID, with no sysroot or platform SDK: the SDK writes the stand-ins from symbol lists in stubs/ (AsmWriteCLibraryStub).
    • Linux: a stub libc.so.6 (glibc) or libc.musl-x86_64.so.1 (musl, with musl's loader), and libasmsdk_nonshared.a with atexit, which glibc keeps out of libc.so.6. crt1 for x64 and ARM64.
    • macOS: libSystem.tbd; dyld calls main (LC_MAIN). AsmMacOSMinimumVersion (default 11.0).
    • Windows: ucrtbase.lib (the Universal C Runtime) with mainCRTStartup, and asmsdk_winstdio.lib: printf, fprintf, sprintf, snprintf, their v forms, sscanf and atexit, which the UCRT headers define inline and ucrtbase.dll does not export.
    • kernel32 is linked into every Windows output, the stable way to the OS (Windows system call numbers change between releases).
    • AsmLibcSymbol adds names on every OS. A macOS freestanding program is ASM0015: Apple supports no static executables.
  • One ExportsFile for every OS: a version script on Linux, -export: names on Windows (and FUNCTION then writes no directive), -exported_symbol on macOS. ASM0030 for what only ELF can express.
  • .NET consumers get the right binary. Every .asmproj carries an implicit PackageReference to AsmFoundation.Sdk, whose buildTransitive targets 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;
    • DisableAsmConsumerTargets turns it off.
  • Packages for every RID: runtimes/<rid>/native/ and native/<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, or ASM0060. 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: ASM0080 for 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), ASM0081 for a fixup in a read-only Mach-O segment (a text relocation, from the rebase or bind opcodes or the chained fixups), ASM0082 for an unreadable image. A failed check deletes the image, so the next build checks again.
  • Toolchain 0.2.0: llvm-mc; packages for win-arm64 (native LLVM, NASM's x64 build under emulation) and linux-arm64 (NASM built from source). Intel Macs and musl hosts have no package (LLVM publishes no binaries for them): ASM0006 names AsmToolchain=System. ASM0004 for a .s source with a toolchain without llvm-mc, ASM0005 for a Windows or macOS RID, or the Linux RID of the other architecture, with the System toolchain's GNU ld.
  • BinariesCopyPath: where a .NET project keeps the asm libraries, for build and publish: on a ProjectReference to an .asmproj, on a PackageReference to 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), then Auto. Errors ASM0043 (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); warning ASM0046 (two libraries in between disagree).
  • The app finds them wherever they go, with no code of its own: its deps.json lists every asm library with localPath, as runtimeTargets in a portable app and as plain native 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 without localPath the 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, an AssemblyLoadContext.ResolvingUnmanagedDll handler that runs only after .NET's own probing and any resolver of yours failed. It is how a NativeAOT program finds native/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=false turns it off.
  • PrivateAssets="all" packs the asm binaries into a .NET library's package: every RID's library under runtimes/<rid>/native/, with no dependency on the asm package; without it, the reference stays a package dependency, as NuGet makes any ProjectReference. 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's BinariesCopyPath put 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 ExcludeFromSingleFile for single-file publishes), because what GetCopyToOutputDirectoryItems hands 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 BinariesCopyPath without 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 new localPath into deps.json itself.
  • Realistic samples, each a complete program:
    • samples/Crc32C: CRC-32C as a freestanding shared library for all seven RIDs: x64 in NASM through asmsdk.inc, ARM64 in GNU syntax. ExportsFile keeps five names (versioned CRC32C_1.0 on Linux). The first call picks one of three paths: a table, the hardware CRC instruction (SSE4.2 crc32, ARM64 crc32cx), 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, IsProcessorFeaturePresent on Windows, always the 3-way path on Apple silicon.
    • samples/Crc32C.Net: its C# API ([LibraryImport], SuppressGCTransition for inputs up to 4 KiB, DisableRuntimeMarshalling), packed as Samples.Crc32C.Net, which depends on the asm package Samples.Crc32C.
    • samples/Crc32C.Tests (xunit v3, 21 tests: every path against a bit-at-a-time C# reference) and samples/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: wc on glibc, with libc calls through the PLT, stderr through the GOT, warn/warnx added with AsmLibcSymbol, and SSE2 counting.
    • samples/HexDump: xxd without libc, in system calls alone; its output is byte-identical to xxd'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, ASM0005 for 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 with BinariesCopyPath native/{rid} and RidFolders), NativeLayoutTests (every BinariesCopyPath value and where it comes from, builds for one RID, self-contained, single-file and NativeAOT publishes that run, ASM0043 and ASM0044, 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), and ExampleTests for 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.txt and a Markdown copy of every page (page.html.md), written after each site build by docs/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 main made main an export, and a Windows .exe then got a stray import library. A Windows program links -noimplib unless its ExportsFile exports 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 default x.asm:12: error: (no column) was plain output: the IDE showed only ASM0007 and MSB3073. A NASM warning now counts as an MSBuild warning, so a build with -warnaserror fails 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 explicit OutDir. A global output folder is never extended by the RID, and the RIDs overwrote each other's files.
  • The default sources are **/*.asm and **/*.s.
  • AsmToolchainVersion defaults to 0.2.0.
  • The Crc32C sample's paths are named for every CPU: crc32c_append_hardware and crc32c_append_hardware_3way, and Crc32CPath.Hardware and HardwareThreeWay in C#.
  • samples/consumer moved to samples/consumers/Hello.Consumer, next to Crc32C.App.
  • samples/global.json selects Microsoft.Testing.Platform for dotnet test, which the samples' xunit v3 project needs.

Fixed

  • A glibc program that called atexit linked but did not start: glibc keeps atexit in libc_nonshared.a, not libc.so.6. The SDK now links its own.
  • A ProjectReference to an OutputType=Objects project 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 ASM0007 with 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=true put it neither in the bundle nor beside it (NETSDK1236), and the program failed with DllNotFoundException. On Linux and macOS, IncludeNativeLibrariesForSelfExtract left lib<name>.so and .dylib outside the bundle. The .NET SDK decides by AssetType, which GetCopyToPublishDirectoryItems drops: the consumer targets now mark the asm libraries AssetType=native, as NuGet marks a package's. The library goes beside the bundle, or inside it with IncludeNativeLibrariesForSelfExtract.
  • A RID-specific build or publish through a class library (app → C# library → .asmproj) carried every RID's runtimes/<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 own bin/; the app's folder gets the copies.
  • dotnet publish -p:PublishAot=true or -p:PublishTrimmed=true stopped 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.props now declares the .NET publish switches TreatAsLocalProperty and sets them to false.
  • AsmToolchain=System for the Linux RID of the other architecture failed in GNU ld with "file in wrong format" (an x64 machine's ld links x64 ELF only). It stops with ASM0005, which names ld.lld or a cross ld.

Removed

  • AsmTargetRid and AsmFormat: 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 .asmproj empty. AsmSource and AsmInclude are also offered as build actions.
    • Every other file of the project folder is a None item, as in a .csproj (a linker script, a C header, a README). EnableDefaultNoneItems=false, .NET's own switch, turns it off. The managed SDK's None glob 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 Compile and CoreCompile with DesignTimeBuild and SkipCompilerExecution. 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. CoreCompile now honors both properties, as Csc does.
    • The fast up-to-date checks of Visual Studio and Rider get UpToDateCheckInput (the sources, includes and ExportsFile) and UpToDateCheckBuilt (the output), so editing a .asm file makes the IDE call MSBuild.
  • 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 by toolchain/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.py checked, 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.cs decodes .tar.xz with 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.txt now ends its lines with LF on every build machine.
  • Target frameworks: freestanding and libc, 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 with NU1202;
    • 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#: DEBUG or RELEASE (the configuration), and FREESTANDING or LIBC (the target framework), appended after the project body, so setting DefineConstants never drops them. DisableImplicitConfigurationDefines and DisableImplicitFrameworkDefines turn them off.
  • NativeAOT's names for extra link input: LinkerArg items, and ExportsFile for the version script (with --export-dynamic for an executable, as NativeAOT does). Editing the version script relinks.
  • Package layout per target framework: build/<framework>/, buildTransitive/<framework>/, an empty lib/<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.Tests builds them all, and runs the executables.
  • The Hello.Library sample targets both frameworks and reports which build it is (hello_uses_libc), so Hello.Net proves it was given the libc build.
  • The documentation site, https://asmfoundation.github.io/AsmSdk/: guides, the complete .asmproj reference, the toolchain and the ecosystem. It is built with DocFX from docs/, with DocFX pinned in .config/dotnet-tools.json, and deployed to GitHub Pages by .github/workflows/docs.yml.

Changed

  • docs/asmproj.md is 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.
  • The package's project URL points at the documentation site, from the next release.

  • Outputs go to bin/<Configuration>/<TargetFramework>/ and obj/<Configuration>/<TargetFramework>/, as in .NET: bin/Release/libc/hello-libc instead of bin/Release/hello-libc.

  • Debug information follows DebugSymbols and DebugType: DWARF in Debug, none in Release, as before; DebugSymbols=true adds it to Release, and DebugType=none removes it.

  • Every page of the documentation site, the samples and the package readme use the 0.2.0 names.

Removed

  • tests/run.py and toolchain/fetch.py, replaced by tests/AsmSdk.Tests and toolchain/fetch.cs (see Added).
  • AsmLibraryName, AsmRuntime, AsmDefineConstants, AsmDefine items, AsmDebugInfo, AsmEntryPoint, AsmLinkFlags and AsmOutputKind. See the table above.
  • The hidden netstandard2.0 target framework of every 0.1.0 project. A project that sets it now fails with ASM0003.

Fixed

  • The build targets' comment on reloc-abs-qword said that a shared object always resolves a dq of a label at load time. That holds only in a writable section: .data, or .data.rel.ro declared write. 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 a dq of a label in any section.
  • Multi-targeting never worked in 0.1.0. The SDK set TargetFramework before the project body, which turned any TargetFrameworks into 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 gets Microsoft.Common.CrossTargeting.targets.
  • A referenced .asmproj could be built with the referencing project's TargetFramework. _AsmResolveProjectReferences now removes the same global properties that ResolveProjectReferences removes.
  • A 0.1.0 package counted as compatible with every framework, because it had no lib/ folder. The lib/<framework>/_._ markers narrow it to the frameworks it was built for.

0.1.0 — 2026-11-17

The first release.

Added

  • .asmproj projects (<Project Sdk="AsmFoundation.Sdk">). NASM sources become a Linux x86-64 shared library, static library or executable, or just objects, chosen with the csproj-style OutputType.

  • Two runtimes:

    • Freestanding (the default): raw system calls, nothing linked;
    • Libc: glibc linked dynamically through a generated libc.so.6 stub, so no sysroot is needed. A Libc executable starts in main through the SDK's crt1.
  • References:

    • ProjectReference between .asmproj projects adds the include folders and links the library;
    • ProjectReference from a .csproj copies the shared library next to the program;
    • PackageReference to an asm package adds the package's include folders and library.
  • dotnet pack writes native packages:

    • include/;
    • native/linux-x64/*.a;
    • runtimes/linux-x64/native/*.so;
    • optional src/;
    • generated build/ and buildTransitive/ props.
  • Exact incremental builds: a rebuild without changes starts no tool; an include file change reassembles the sources that can include it.

  • AsmFoundation.Toolchain 0.1.0 for win-x64, linux-x64 and osx-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-ar and llvm-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.