Table of Contents

Projects

An .asmproj behaves like an SDK-style .csproj:

  • properties go in a <PropertyGroup>, items in an <ItemGroup>;
  • the properties a .csproj uses mean the same here: TargetFramework(s), OutputType, AssemblyName, DefineConstants, DebugSymbols, DebugType and StartupObject;
  • Version, PackageId, Configuration, Directory.Build.props, Directory.Packages.props and nuget.config all 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 own bin/<Configuration>/<tfm>/<rid>/ folders.

  • One source for both: NASM gets -DFREESTANDING or -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
    %endif
    
  • Who may reference whom is NuGet's decision, as for a .csproj: a libc project may use freestanding projects and packages, never the reverse (NU1201, NU1202). A project that targets both gives each consumer its nearest build, and a .NET project the libc one.

  • 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> is AssemblyName, which defaults to the project name, as in a .csproj. Libraries get the lib prefix on Linux and macOS, which -l<name> and .NET's [DllImport("<name>")] both look for. On Windows, [DllImport("<name>")] looks for <name>.dll.
  • AsmProduceStaticLibrary=true also 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/ and obj/, as in .NET: bin/Debug/freestanding/linux-x64/, bin/Release/libc/win-arm64/.
  • The SDK sets OutputType back to Library after 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 **/*.asm and **/*.s is an AsmSource, and every **/*.inc is an AsmInclude. bin/ and obj/ are excluded. Set EnableDefaultAsmItems=false to list them yourself. Listing a default source again is ASM0024.

  • Name include files .inc. An .asm file 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:

    1. NASM tries the working directory first, which is the project folder.
    2. Then it tries the -I folders in order: the project's include/, the project folder, then the include folders of referenced projects and packages, then the SDK's own (asmsdk.inc, asmsdk-gnu.inc). llvm-mc gets the same folders.

    NASM does not look in the folder of the file that holds the %include. In a source at src/x86/a.asm, %include "b.inc" finds neither src/x86/b.inc nor 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 what dotnet pack ships. A project without an include/ 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.inc leaves the old objects in place: the build reports up to date, but it is stale.
  • What counts as a dependency: the project's own AsmInclude items, 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-separated NAME or NAME=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> keeps DEBUG too. DisableImplicitConfigurationDefines=true drops DEBUG/RELEASE, and DisableImplicitFrameworkDefines=true drops FREESTANDING/LIBC and 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; %de would decode to the byte 0xDE.

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=true adds -w+error.
  • <AsmFlags>-w-label-orphan</AsmFlags> silences one warning. The name of each warning is printed in brackets after it.
  • AsmLlvmMcFlags passes extra arguments to llvm-mc, as AsmFlags does 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.props and other imported files. After changing a define there, rebuild with dotnet 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 .asmproj needs the generic MSBuild project type:

    <Project Path="Hello/Hello.asmproj" Type="13B669BE-BB05-4DDF-9536-439F39A36129" />
    

    Without it, dotnet build fails with MSB4025 … ProjectType '' not found.

  • dotnet sln add refuses .asmproj files. Add the line by hand.

  • Classic .sln: an entry needs two parts:

    • the Project("{13B669BE-BB05-4DDF-9536-439F39A36129}") = … line;
    • ProjectConfigurationPlatforms lines for Debug and Release.

    Without the configuration lines, the build skips the project and still reports 0 errors. Prefer .slnx.