Repository navigation
Releases
AsmFoundation.Sdk 0.3.0
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:
- `sa...
AsmFoundation.Sdk 0.2.0
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.AsmSourceand
AsmIncludeare 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, callingCompileandCoreCompilewithDesignTimeBuildand
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.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 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.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.DisableImplicitConfigurationDefinesand
DisableImplicitFrameworkDefinesturn 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.Testsand
toolchain/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's
TargetFramework._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.
AsmFoundation.Sdk 0.1.0
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-x64and
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-arandllvm-readobj.
Every download is pinned by SHA-256 and verified before use.
- NASM 3.02: the official binary on Windows, built from source on Linux
-
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,