Trimming, ReadyToRun and NativeAOT

A published app is the assemblies, the runtime it needs and a host. The publisher can trim the assemblies, precompile them for the target machine, or compile the whole program to native code ahead of time. This lesson runs the three modes on one small program, and the third one stops at a missing tool, which is a real result of this image.

The program

A published app needs nothing special; the lesson uses two lines that show it runs and which runtime it carries:

Console.WriteLine("hello from a published app"); Console.WriteLine($"runtime {Environment.Version}");

Trimming

Trimming removes the code the program does not reach. It only applies to a self-contained publish, because a framework-dependent app uses the assemblies of the shared runtime. The command names the target runtime, turns on self-contained and trimming, and writes to a folder:

dotnet publish app.csproj -c Release -r linux-musl-x64 --self-contained -p:PublishTrimmed=true -o trimmed

  Determining projects to restore...
  Restored /tmp/cs/pub2/app.csproj (in 546 ms).
  app -> /tmp/cs/pub2/bin/Release/net10.0/linux-musl-x64/app.dll
  Optimizing assemblies for size. This process might take a while.
  app -> /tmp/cs/pub2/trimmed/

The folder holds 30 files and 23 710 171 bytes, most of them the trimmed runtime:

du -sb trimmed; ls trimmed | wc -l

23710171    trimmed
30

./trimmed/app

hello from a published app
runtime 10.0.15

The app ran without a dotnet command in front of it, because the runtime is in the folder next to it. The version it printed is the runtime it carries, which is the same 10.0.15 as the SDK of this container. The trimmer emitted no warning for this program: its code and its annotations are simple enough for the analysis. A program that finds a type by a name in a string gets an IL2xxx warning instead, because the trimmer cannot see the type it will ask for.

ReadyToRun

ReadyToRun precompiles the assemblies for the target processor, so the runtime starts with native code instead of JIT-compiling everything on the first call. The publish stays framework-dependent unless --self-contained is added, so the folder is small:

dotnet publish app.csproj -c Release -r linux-musl-x64 -p:PublishReadyToRun=true -o r2r

  Determining projects to restore...
  Restored /tmp/cs/pub2/app.csproj (in 543 ms).
  app -> /tmp/cs/pub2/bin/Release/net10.0/linux-musl-x64/app.dll
  app -> /tmp/cs/pub2/r2r/

du -sb r2r; ls r2r | wc -l

95946    r2r
5

Five files and 95 946 bytes: the app host of 78 224 bytes, the precompiled assembly, its runtime configuration and two small files. The machine still needs the .NET runtime, because only the app is precompiled; the shared framework is not in the folder. A container that uses this mode starts from the runtime image and copies the five files.

NativeAOT and the real error

NativeAOT compiles the whole program, runtime included, into one native executable with no JIT. The publish restores the ILCompiler package and then needs a C linker, and this image has neither gcc nor clang:

dotnet publish app.csproj -c Release -r linux-musl-x64 -p:PublishAot=true -o aot

  Determining projects to restore...
  Restored /tmp/cs/pub2/app.csproj (in 981 ms).
  app -> /tmp/cs/pub2/bin/Release/net10.0/linux-musl-x64/app.dll
/home/agent/.nuget/packages/microsoft.dotnet.ilcompiler/10.0.15/build/Microsoft.NETCore.Native.Unix.targets(316,5): error : Platform linker ('clang' or 'gcc') not found in PATH. Ensure you have all the required prerequisites documented at https://aka.ms/nativeaot-prerequisites. [/tmp/cs/pub2/app.csproj]

The restore succeeded, because the ILCompiler package was in the NuGet cache of the image; the build stopped on the linker, and the message names both candidates and the page with the prerequisites. The path before the error is the machine path of the build, as the paths in a stack trace are. On a machine with clang installed the same command produces a native executable; this lesson cannot show that executable, and does not pretend to.

The next part starts the first capstone, a CSV log report, where the programs are longer and every part is measured on a real file.

Exercises

  1. Publish the program with --self-contained false and compare the folder size with the trimmed one.
  2. Publish with -p:PublishSingleFile=true and read the size of the one file.
  3. Add a reflection call that finds a type by name and read the trim warning.
  4. Install clang on a machine of your own and run the NativeAOT publish.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does PublishTrimmed do?

    Answer

    Removes the code the program does not reach

    The trimmed self-contained folder of the measured app was 23.7 MB.

  2. Why does trimming need a self-contained publish?

    Answer

    A framework-dependent app uses the assemblies of the shared runtime

    There is nothing to trim in the shared runtime, only in the app and its own dependencies.

  3. How large was the trimmed folder in the measurement?

    Answer

    23 710 171 bytes in 30 files

    The du output on the page is that number.

  4. What does ReadyToRun precompile?

    Answer

    The assemblies of the app for the target processor

    The app starts with native code and the runtime still JIT-compiles what it needs.

  5. Why was the ReadyToRun folder smaller than the trimmed one?

    Answer

    It stays framework-dependent and carries no runtime

    The runtime is installed on the machine, not copied into the folder.

  6. What is NativeAOT?

    Answer

    Compiling the program and the runtime into one native executable

    The result needs no .NET runtime and no JIT.

  7. On what did the NativeAOT publish stop in this image?

    Answer

    The missing platform linker clang or gcc

    The error line on the page names the linker and the prerequisites page.

  8. What does this program print? Console.WriteLine("hello from a published app");

    Answer

    hello from a published app

    The published app of the lesson printed that line.

  9. Which mode produced a program that runs without a dotnet command?

    Answer

    The trimmed self-contained publish

    The runtime is in the folder, so ./trimmed/app ran directly.

  10. Why does a reflection-based program risk a trimming warning?

    Answer

    The trimmer cannot see which type a string will name

    The analysis keeps only what it can prove is used, and a name in a string is not proof.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image