Getting started
This page builds three things:
- a shared library written in assembly, for seven platforms;
- a program that prints through the C library, for the same seven;
- a C# program that calls the library, and runs on any of them.
All three go in one solution, built with dotnet build.
What you need
- The .NET SDK. AsmSdk's own CI uses .NET 10.
.slnxsolutions need the .NET 9.0.200 SDK or later. - A build machine with a bundled toolchain: Windows (x64 or Arm64), Linux (x64 or ARM64, glibc) or an Apple silicon Mac. For anything else, see supported build machines.
You don't install an assembler or a linker: restore downloads them. Every build machine builds for all seven platforms. What it can run is its own platform's build, plus the x64 builds under emulation on Windows on Arm and on Apple silicon (Rosetta 2).
1. Name the SDK
Create global.json next to where your solution will be:
{ "msbuild-sdks": { "AsmFoundation.Sdk": "0.3.0" } }
MSBuild resolves <Project Sdk="AsmFoundation.Sdk"> through this entry, from nuget.org.
2. A shared library
Hello/Hello.asmproj:
<Project Sdk="AsmFoundation.Sdk">
<PropertyGroup>
<AssemblyName>hello</AssemblyName>
<RuntimeIdentifiers>win-x64;win-arm64;linux-x64;linux-arm64;linux-musl-x64;osx-x64;osx-arm64</RuntimeIdentifiers>
</PropertyGroup>
</Project>
Hello/hello.asm, the x64 code:
default rel
%include "asmsdk.inc"
section .text
FUNCTION hello_add, 2 ; int hello_add(int a, int b)
lea eax, [ARG1 + ARG2] ; rcx + rdx on Windows, rdi + rsi elsewhere
RETURN
ENDFUNCTION
%ifdef LINUX
section .note.GNU-stack noalloc noexec nowrite progbits
%endif
Hello/hello.s, the ARM64 code:
.include "asmsdk-gnu.inc"
FUNCTION hello_add // int hello_add(int a, int b)
add w0, w0, w1 // the same registers on Windows, Linux and macOS
ret
ENDFUNCTION hello_add
.ifdef LINUX
.section .note.GNU-stack,"",%progbits
.endif
Build it:
dotnet build Hello/Hello.asmproj
The first build restores AsmFoundation.Sdk and the toolchain package for your machine.
It then builds each platform into its own folder:
Hello/bin/Debug/freestanding/win-x64/hello.dll
Hello/bin/Debug/freestanding/win-arm64/hello.dll
Hello/bin/Debug/freestanding/linux-x64/libhello.so
Hello/bin/Debug/freestanding/linux-arm64/libhello.so
Hello/bin/Debug/freestanding/linux-musl-x64/libhello.so
Hello/bin/Debug/freestanding/osx-x64/libhello.dylib
Hello/bin/Debug/freestanding/osx-arm64/libhello.dylib
A Windows DLL also gets its import library, hello.dll.lib, for native code that links it, and in
Debug its hello.pdb.
- The properties are .NET's own.
AssemblyNamenames the output, as it names a.csproj's DLL; each OS adds its own prefix and extension.RuntimeIdentifierslists the platforms, by .NET's runtime identifiers. A project lists the ones its code supports. A project that lists none is built for what its referencing projects ask for, or fails with ASM0010, which names the ways to choose. - The target framework is
freestandingwhen the project sets none: the code links no C library. It is thefreestandingfolder in the output path, asnet10.0is in a.csproj's. - The file name picks the platforms. Every
*.asmand*.sin the project folder is a source, the way every*.csis compiled in a.csproj..asmfiles are NASM, and build the x64 platforms..sfiles are GNU syntax, assembled byllvm-mc, and build the ARM64 ones. A qualifier narrows a file further (hello.linux.asm,hello.win-arm64.s): see Sources per platform. asmsdk.incandasmsdk-gnu.incare the platform layer.FUNCTIONdeclares and exports a function the way each OS does. In x64 code,ARG1andARG2are the first two argument registers of the OS being built. ARM64 needs no such names: all three OSes pass arguments inx0-x7.- A second
dotnet buildwith no changes runs no tool at all.
Tip
default rel and the %ifdef LINUX around .note.GNU-stack matter more than they look.
They are two of the rules in Writing NASM for AsmSdk: the first decides
whether code links into a shared library, and the second whether it assembles for macOS.
3. A program
HelloApp/HelloApp.asmproj:
<Project Sdk="AsmFoundation.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>libc</TargetFramework>
<AssemblyName>hello-app</AssemblyName>
<RuntimeIdentifiers>win-x64;win-arm64;linux-x64;linux-arm64;linux-musl-x64;osx-x64;osx-arm64</RuntimeIdentifiers>
</PropertyGroup>
</Project>
HelloApp/main.asm: an ordinary C main that prints a line with puts.
default rel
%include "asmsdk.inc"
extern puts
section .rodata
message: db "hello from assembly", 0
section .text
FUNCTION main ; int main(void)
sub rsp, SHADOW_SPACE + 8 ; rsp 16-aligned for the call, plus Windows' shadow space
lea ARG1, [message]
call puts PLT
add rsp, SHADOW_SPACE + 8
xor eax, eax ; exit status 0
RETURN
ENDFUNCTION
%ifdef LINUX
section .note.GNU-stack noalloc noexec nowrite progbits
%endif
HelloApp/main.s: the same program for ARM64.
.include "asmsdk-gnu.inc"
RODATA
message: .asciz "hello from assembly"
FUNCTION main // int main(void)
stp x29, x30, [sp, #-16]! // save the frame pointer and the return address
mov x29, sp
ADDRESS x0, message
CALL puts
mov w0, #0 // exit status 0
ldp x29, x30, [sp], #16
ret
ENDFUNCTION main
.ifdef LINUX
.section .note.GNU-stack,"",%progbits
.endif
dotnet build HelloApp/HelloApp.asmproj writes HelloApp/bin/Debug/libc/<rid>/hello-app
(hello-app.exe on Windows). Each one is linked against its platform's C library: the
Universal C Runtime on Windows, glibc or musl on Linux, libSystem on macOS. Run the one for
your machine:
./HelloApp/bin/Debug/libc/win-x64/hello-app.exe # Windows x64
./HelloApp/bin/Debug/libc/osx-arm64/hello-app # Apple silicon
./HelloApp/bin/Debug/libc/linux-x64/hello-app # Linux x64
From Windows, the Linux build runs in a container. Files built on Windows have no execute bit, so set it first:
docker run --rm -v "$PWD:/w" -w /w mcr.microsoft.com/dotnet/runtime:10.0 \
sh -c 'chmod +x HelloApp/bin/Debug/libc/linux-x64/hello-app && ./HelloApp/bin/Debug/libc/linux-x64/hello-app'
Note
Not released yet: on the main branch, dotnet run --project HelloApp builds the
program and runs the build for this machine, and dotnet run -r linux-x64 runs a Linux
build through WSL or in Docker. dotnet publish writes one folder per RID, and
PackAsTool packs the program as a .NET tool. See Programs.
SHADOW_SPACEis 32 on Windows and 0 elsewhere. An x64 call needsrsp16-byte aligned, and on Windows the caller also reserves 32 bytes above the return address for the callee.puts PLTcalls through the PLT on Linux, and is a plain call elsewhere.ADDRESSandCALLspell an address and a call the way the OS's object format wants them. Mach-O, for one, names C functions with a leading underscore.- A
freestandingprogram links no C library and talks to the OS itself: system calls on Linux, kernel32 on Windows. macOS supports no programs without libSystem. See Runtimes and linking and the C library per platform.
4. Call it from C#
App/App.csproj: a normal console app with a ProjectReference to the assembly project.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks> <!-- [LibraryImport] generates unsafe code -->
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="../Hello/Hello.asmproj" />
</ItemGroup>
</Project>
App/Program.cs:
using System.Runtime.InteropServices;
Console.WriteLine(Native.HelloAdd(40, 2));
internal static partial class Native
{
// "hello": hello.dll on Windows, libhello.so on Linux, libhello.dylib on macOS
[LibraryImport("hello", EntryPoint = "hello_add")]
internal static partial int HelloAdd(int a, int b);
}
What the reference does:
- it builds
Hellofirst, for each of its platforms; - it copies each platform's library into
runtimes/<rid>/native/besideApp.dll, and lists them inApp.deps.json, on build and ondotnet publish. The .NET host loads the one for the machine it runs on, as it does for a NuGet package's native libraries; - it adds no assembly reference.
A build for one platform (dotnet publish -r linux-arm64, or a RuntimeIdentifier in the
.csproj) gets that platform's library alone, copied beside App.dll, and NuGet's RID rules
pick it. See Calling assembly from .NET. To keep the
libraries somewhere else, such as native/<rid>/, set BinariesCopyPath on the reference
(Where the binaries go).
Running it works on any of the seven platforms:
dotnet run --project App
It prints 42. From Windows, the Linux build runs in a container as well:
docker run --rm -v "$PWD:/w" -w /w mcr.microsoft.com/dotnet/runtime:10.0 dotnet App/bin/Debug/net10.0/App.dll
5. One solution
App.slnx:
<Solution>
<Project Path="Hello/Hello.asmproj" Type="13B669BE-BB05-4DDF-9536-439F39A36129" />
<Project Path="HelloApp/HelloApp.asmproj" Type="13B669BE-BB05-4DDF-9536-439F39A36129" />
<Project Path="App/App.csproj" />
</Solution>
- The
TypeGUID is required. It is the generic MSBuild project type. Without it,dotnet build App.slnxfails withMSB4025 … ProjectType '' not found. - Add the entries by hand.
dotnet sln addrefuses.asmprojfiles ("unknown project type").
dotnet build App.slnx now builds everything.
Next steps
- Platforms and runtime identifiers: which file builds which platform, the calling-convention macros, exports, and the C library of each OS.
- Examples: complete programs built the same way: a CRC-32C library
with hardware paths for x64 and ARM64, called from C# and shipped through NuGet; a
wcon glibc; anxxdwithout libc. - Projects: output kinds, include folders, defines and configurations.
- References and packages: share a library between projects, or as a NuGet package by version.
- The Claude Code plugin:
new_asmproj.pyscaffolds any of the projects above, andcheck_asmproj.pylints them.