Projects
An .asmproj behaves like an SDK-style .csproj:
- properties go in a
<PropertyGroup>, items in an<ItemGroup>; - the properties a
.csprojuses mean the same here:TargetFramework(s),OutputType,AssemblyName,DefineConstants,DebugSymbols,DebugTypeandStartupObject; Version,PackageId,Configuration,Directory.Build.props,Directory.Packages.propsandnuget.configall work as usual.
This page covers what is specific to assembly. Every setting is in the reference.
A project folder
Hello/
Hello.asmproj <Project Sdk="AsmFoundation.Sdk"> ... </Project>
include/hello.inc public include files: referencing projects and package consumers get them
hello.asm every *.asm is an x64 source (one NASM run per RID)
hello.s every *.s is a GNU-syntax source, the ARM64 code (one llvm-mc run per RID)
util/strings.asm subfolders too; each object keeps the subfolder: obj/Debug/freestanding/linux-x64/asm/obj/util/strings.o
bin/Debug/freestanding/linux-x64/libhello.so
bin/Debug/freestanding/win-x64/hello.dll
Runtime identifiers
A project lists the platforms its code supports with .NET's property, and dotnet build
builds each one, into its own bin/<Configuration>/<tfm>/<rid>/ folder:
<RuntimeIdentifiers>win-x64;win-arm64;linux-x64;linux-arm64;osx-arm64</RuntimeIdentifiers>
A project that lists none is built for the RIDs its referencing projects ask for, or for
-r <rid>; otherwise it fails with ASM0010. Which source builds which RID is decided by the
file name: .asm is NASM for the x64 RIDs, .s is GNU syntax for the ARM64 ones, and a
qualifier (hello.linux.asm, hello.win-arm64.s) narrows a file further.
Platforms and runtime identifiers covers all of it.
Target frameworks
The target framework says what the code links against, the way net10.0 says which .NET a
.csproj runs on:
TargetFramework |
The code | Runs on |
|---|---|---|
freestanding (the default) |
links no C library: Linux system calls, kernel32 on Windows | any Linux kernel of its CPU; any Windows. macOS has no freestanding programs, only libraries |
libc |
links the platform's C library: glibc or musl, the Universal C Runtime, libSystem; a program starts at main |
glibc 2.34 or later, musl, Windows 10 or later, macOS 11 or later |
Build both with
<TargetFrameworks>freestanding;libc</TargetFrameworks>, exactly like a multi-targeted.csproj. Each build has its ownbin/<Configuration>/<tfm>/<rid>/folders.One source for both: NASM gets
-DFREESTANDINGor-DLIBC(llvm-mc--defsym LIBC=1). In a Linux source:%ifdef LIBC call puts PLT ; the C library %else mov eax, 1 ; write(2) syscall %endifWho may reference whom is NuGet's decision, as for a
.csproj: alibcproject may usefreestandingprojects and packages, never the reverse (NU1201,NU1202). A project that targets both gives each consumer its nearest build, and a .NET project thelibcone.Runtimes and linking covers what each one links and how.
Output kinds and names
OutputType |
Windows | Linux | macOS |
|---|---|---|---|
Library (default) |
<name>.dll and its import library <name>.dll.lib |
lib<name>.so |
lib<name>.dylib |
StaticLibrary |
<name>.lib |
lib<name>.a |
lib<name>.a |
Exe |
<name>.exe |
<name>, with no extension |
<name> (libc only) |
Objects |
nothing; the objects stay in obj/ |
the same | the same |
All of them go to bin/<Configuration>/<tfm>/<rid>/. A Windows output built with debug
symbols also gets <name>.pdb.
<name>isAssemblyName, which defaults to the project name, as in a.csproj. Libraries get thelibprefix on Linux and macOS, which-l<name>and .NET's[DllImport("<name>")]both look for. On Windows,[DllImport("<name>")]looks for<name>.dll.AsmProduceStaticLibrary=truealso writes the static library next to the shared one. That suits a library that ships both: programs that load it (P/Invoke,dlopen) take the shared library, and assembly projects that link statically take the static one.- The target framework and RID folders are appended to
bin/andobj/, as in .NET:bin/Debug/freestanding/linux-x64/,bin/Release/libc/win-arm64/. - The SDK sets
OutputTypeback toLibraryafter reading it, so that the .NET SDK never builds an apphost. Its internal_AsmOutputKind(SharedLibrary,StaticLibrary,Executable,Objects) keeps the kind; a target of your own can read it, but it is not a stable API.
A ProjectReference to an Objects project links its object files into the referencing
project, for each of the referencing project's RIDs. (0.1.0 and 0.2.0 passed their paths
relative to the wrong project, and the link failed.) A StaticLibrary does the same job, and
the linker takes only the archive members it needs.
Sources and include files
Default items: every
**/*.asmand**/*.sis anAsmSource, and every**/*.incis anAsmInclude.bin/andobj/are excluded. SetEnableDefaultAsmItems=falseto list them yourself. Listing a default source again is ASM0024.Name include files
.inc. An.asmfile that another file%includes is still a source, so its symbols are linked twice:duplicate symbol. Rename it, or remove it from the sources with<AsmSource Remove="helpers.asm" />.Where
%include "x.inc"looks:- NASM tries the working directory first, which is the project folder.
- Then it tries the
-Ifolders in order: the project'sinclude/, the project folder, then the include folders of referenced projects and packages, then the SDK's own (asmsdk.inc,asmsdk-gnu.inc).llvm-mcgets the same folders.
NASM does not look in the folder of the file that holds the
%include. In a source atsrc/x86/a.asm,%include "b.inc"finds neithersrc/x86/b.incnor anything else there. Write%include "src/x86/b.inc", or add<AsmIncludeDirectory Include="src/x86/" />.Public include files belong in
include/. It is what referencing projects get on their include path, and whatdotnet packships. A project without aninclude/folder packs no include files.
Include folders outside the project
<ItemGroup>
<AsmIncludeDirectory Include="../common/include/" /> <!-- the -I path -->
<AsmInclude Include="../common/include/**/*.inc" /> <!-- makes edits rebuild -->
</ItemGroup>
- Write both lines. With only the first, editing
../common/include/x.incleaves the old objects in place: the build reports up to date, but it is stale. - What counts as a dependency: the project's own
AsmIncludeitems, plus the include folders of packages and referenced projects.
Defines and configurations
| Debug | Release | |
|---|---|---|
| defined | DEBUG, and FREESTANDING or LIBC |
RELEASE, and FREESTANDING or LIBC |
| debug information (DWARF; CodeView and a PDB on Windows) | yes | no |
Every build also defines its platform: WINDOWS, LINUX or MACOS (plus MUSL on
linux-musl-x64), and X64 or ARM64. ASMSDK_EXPORTS_FILE marks a project with an
ExportsFile, and ASMSDK_EXECUTABLE a program.
Add symbols with
DefineConstants, as in C#: semicolon-separatedNAMEorNAME=VALUE, each passed to NASM as-D, and to llvm-mc as--defsym NAME=1(numeric values only):<DefineConstants>$(DefineConstants);FAST_PATH;LEVEL=3</DefineConstants>The configuration and target framework symbols are never lost. Like C#, the SDK appends them after reading your project, so
<DefineConstants>FAST_PATH</DefineConstants>keepsDEBUGtoo.DisableImplicitConfigurationDefines=truedropsDEBUG/RELEASE, andDisableImplicitFrameworkDefines=truedropsFREESTANDING/LIBCand the platform symbols.Debug information follows
DebugSymbols:<DebugSymbols>true</DebugSymbols>adds it to Release builds, and<DebugType>none</DebugType>removes it from Debug builds. Unlike .NET, whose Release builds still write a PDB, a Release build carries no debug information unless you ask.In MSBuild text,
%starts an escape sequence. A target that writes%define …into a file must write%25define;%dewould decode to the byte0xDE.
Warnings and diagnostics
NASM runs with -w+all, except for two warnings that position-independent code always
triggers (reloc-rel-dword and reloc-abs-qword).
TreatWarningsAsErrors=trueadds-w+error.<AsmFlags>-w-label-orphan</AsmFlags>silences one warning. The name of each warning is printed in brackets after it.AsmLlvmMcFlagspasses extra arguments to llvm-mc, asAsmFlagsdoes to NASM.
Tip
By default, NASM's messages are printed as plain text above an MSB3073: The command … exited with code 1 error, and -v:q hides them. Add <AsmFlags>-Xvc</AsmFlags>: NASM
then reports file.asm(12): error : …, which MSBuild counts as an error or warning, and
which IDEs link to the right line.
Incremental builds
- An object is rebuilt when its source, any include file in its dependency list, or the project file is newer.
- The link reruns when an object, a link input or the project file is newer.
- A rebuild with no changes runs no tool.
- Not tracked: changes to
Directory.Build.propsand other imported files. After changing a define there, rebuild withdotnet build --no-incremental.
Settings for every assembly project
UsingAsmFoundationSdk is already true when Directory.Build.props is read, so a single
file can hold settings for both the C# and the assembly projects of a solution:
<Project>
<PropertyGroup Condition="'$(UsingAsmFoundationSdk)' == 'true'">
<TargetFramework>libc</TargetFramework> <!-- every asm project links its C library -->
<AsmFlags>-Xvc</AsmFlags> <!-- NASM messages become MSBuild errors -->
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup Condition="'$(UsingAsmFoundationSdk)' == 'true' and $(RuntimeIdentifier.StartsWith('linux-'))">
<LinkerArg Include="-z defs" /> <!-- undefined symbols fail the link -->
</ItemGroup>
</Project>
-z defs is explained in Runtimes and linking.
Solutions
.slnx: each.asmprojneeds the generic MSBuild project type:<Project Path="Hello/Hello.asmproj" Type="13B669BE-BB05-4DDF-9536-439F39A36129" />Without it,
dotnet buildfails withMSB4025 … ProjectType '' not found.dotnet sln addrefuses.asmprojfiles. Add the line by hand.Classic
.sln: an entry needs two parts:- the
Project("{13B669BE-BB05-4DDF-9536-439F39A36129}") = …line; ProjectConfigurationPlatformslines for Debug and Release.
Without the configuration lines, the build skips the project and still reports 0 errors. Prefer
.slnx.- the