Samples
The samples/ folder of the
AsmSdk repository covers every kind of project. CI builds and checks all of them on five
build machines: Windows x64 and Windows on Arm, Linux x64 and ARM64, and Apple silicon. Crc32C
is built for all seven RIDs. The Hello.* samples, WordCount and HexDump are Linux x64 code
(Linux system calls, or glibc), and say so with <RuntimeIdentifiers>linux-x64</RuntimeIdentifiers>.
The small Hello.* samples show one kind of project each, in a few lines:
| Sample | Shows |
|---|---|
Hello.Library |
a shared library (libhello.so) with a public include/ file, built for both target frameworks (TargetFrameworks=freestanding;libc): one source, %ifdef LIBC |
Hello.Static |
a static library (libhellostatic.a) with public includes, packed as the NuGet package Hello.Static 1.0.0 |
Hello.App |
a freestanding executable that links Hello.Static through a ProjectReference |
Hello.Libc |
a main() program on glibc that calls printf |
Hello.LibcLibrary |
a shared library that calls strlen through its PLT |
consumers/Hello.Consumer |
an executable that consumes the Hello.Static package by version |
Hello.Net |
a C# program that P/Invokes both shared libraries, and checks that it was given the libc build of Hello.Library |
The realistic samples are complete programs, each walked through in the Examples:
| Sample | Shows |
|---|---|
Crc32C |
CRC-32C as a freestanding shared library for seven RIDs: x64 in NASM through asmsdk.inc, ARM64 in GNU syntax, ExportsFile, run-time CPU dispatch on each OS, constants computed by the assemblers, a 3-way kernel (SSE4.2 + PCLMULQDQ, or CRC32 + PMULL) |
Crc32C.Net, Crc32C.Tests, Crc32C.Bench |
its C# API ([LibraryImport], SuppressGCTransition), its xunit tests, its BenchmarkDotNet benchmark |
consumers/Crc32C.App |
a .NET program that uses the library through two NuGet packages, by version |
WordCount |
wc on glibc: PLT calls, a libc data object through the GOT, AsmLibcSymbol, SSE2 counting |
HexDump |
xxd with no libc: _start, raw system calls, a static executable of about 4 KB |
Samples.slnx holds them all except the two under consumers/, which sit outside the solution
because the packages they use must be packed first.
How they are checked
tests/AsmSdk.Tests,
an xunit v3 project, packs the SDK and the toolchain into a local feed, then builds the
samples against it, with a fresh NUGET_PACKAGES. Each of its 119 tests checks one
expectation:
- the seven RIDs (
CrossPlatformTests): one project's object format, exports and qualified sources per RID; the C library of each OS; programs that export what theirExportsFilelists; the .NET consumer, portable and per RID; the package layout; the RID errors; the image checks (ASM0080,ASM0081). Each machine also runs its own platform's build, and the x64 one under emulation on Windows on Arm and Apple silicon; - the ELF properties of every Linux output: type, SONAME,
DT_NEEDED, interpreter, exports and archive members; - that the executables run, and that the C# program's calls into both libraries return the right values;
- incremental builds: a rebuild without changes runs no tool, and an include-file change reassembles what depends on it;
- the package layouts of a single-target and a multi-target library;
- the projects in
tests/projects, which cover what the samples cannot: the target framework compatibility errors (NU1201,NU1202), the errors for settings removed in 0.2.0,StartupObject,ExportsFile,LinkerArg,DefineConstantsandDebugSymbols; - IDE integration: the declared item types, that every file of a project folder is one item, the up-to-date inputs and outputs, and that a design-time build runs no tool (see IDEs);
- the realistic samples (
ExampleTests): Crc32C's exports, constants, packages, own unit tests and NuGet consumer; WordCount's imports, counts and errors; HexDump's size, output and errors (see Examples); - whole small repositories (
ScenarioTests, not released yet): each folder oftests/scenariosis a solution taken through thedotnetcommands itsscenario.jsonlists. Asm libraries in C# apps, in unit tests, beside NumSharp, OptunaSharp and KvAsm.Client; asm programs that link libraries, that a C# app starts, and that are packed as .NET tools (see Scenario tests).
The .NET programs (Crc32C's tests, its benchmark's check, the NuGet consumer) run natively on
every machine: their portable output carries every RID's library. The Linux x64 programs run
natively on Linux x64, and elsewhere through WSL or Docker when available. Where neither is,
those tests are skipped with the reason (ASMSDK_TEST_RUN and ASMSDK_TEST_DOTNET_RUN
choose explicitly). Only the .NET SDK is needed:
dotnet run toolchain/fetch.cs -- --rid win-x64 # or win-arm64, linux-x64, linux-arm64, osx-arm64: stages the tools
dotnet test --project tests/AsmSdk.Tests/AsmSdk.Tests.csproj # packs, builds the samples, checks and runs them
Bytes on the home page
The block A on the home page is labelled with machine code from these functions:
- the mint blocks are
hello_addfromHello.Library:lea eax, [rdi + rsi]assembles to8D 04 37, andrettoC3; - the teal blocks are the first bytes of
sum_i32, the freestanding template in Writing NASM for AsmSdk, as assembled for Linux and macOS:xor eax, eax(31 C0),test rsi, rsi(48 85 F6),jle(7E 0F), thenmovsxd r8, …(4C 63 …).