- Building
- High Level Overview
- Visual Studio Solutions
- Convenience Visual Studio "repro" project
- Running tests
- Design Documentation
- Further Reading
The Native AOT toolchain can be currently built for Linux (x64/arm64), macOS (x64) and Windows (x64/arm64).
- Install pre-requisites
- Run
build[.cmd|.sh] clr.aot+libs -rc [Debug|Release]from the repo root to build binaries for local development. This will build individual components, but not the NuGet packages and builds much faster.
The paths to major components can be overridden using IlcToolsPath, IlcSdkPath, IlcFrameworkPath, IlcFrameworkNativePath and IlcMibcPath properties for dotnet publish. For example, /p:IlcToolsPath=<repo root>\artifacts\bin\coreclr\windows.x64.Debug\ilc can be used to override the compiler with a local debug build for troubleshooting or quick iterations.
The component that writes out object files (objwriter.dll/libobjwriter.so/libobjwriter.dylib) is based on LLVM and doesn't build in the runtime repo. It gets published as a NuGet package out of the dotnet/llvm-project repo (branch objwriter/12.x). If you're working on ObjWriter or bringing up a new platform that doesn't have ObjWriter packages yet, as additional pre-requisites you need to build objwriter out of that repo and replace the file in the output.
Run build[.cmd|.sh] -c Release from the repo root to build the NativeAOT toolchain packages. The build will place the toolchain packages at artifacts\packages\Release\Shipping. To publish your project using these packages:
- Add the package directory to your
nuget.configfile. For example, add<add key="local" value="C:\runtime\artifacts\packages\Release\Shipping" /> - Run
dotnet publish --packages pkg -r [win-x64|linux-x64|osx-64] -c [Debug|Release]to publish your project.--packages pkgoption restores the package into a local directory that is easy to cleanup once you are done. It avoids polluting the global nuget cache with your locally built dev package.
Native AOT is a stripped down version of the CoreCLR runtime specialized for ahead of time compilation, with an accompanying ahead of time compiler.
The main components of the toolchain are:
- The AOT compiler (ILC/ILCompiler) built on a shared codebase with crossgen2 (src/coreclr/tools/aot). Where crossgen2 generates ReadyToRun modules that contain code and data structures for the CoreCLR runtime, ILC generates code and self-describing datastructures for a stripped down version of CoreCLR into object files. The object files use platform specific file formats (COFF with CodeView on Windows, ELF with DWARF on Linux, and Mach-O with DWARF on macOS).
- The stripped down CoreCLR runtime (NativeAOT specific files in src/coreclr/nativeaot/Runtime, the rest included from the src/coreclr). The stripped down runtime is built into a static library that is linked with object file generated by the AOT compiler using a platform-specific linker (link.exe on Windows, ld on Linux/macOS) to form a standalone executable.
- The bootstrapper library (src/coreclr/nativeaot/Bootstrap). This is a small native library that contains the actual native
main()entrypoint and bootstraps the runtime and dispatches to managed code. Two flavors of the bootstrapper are built - one for executables, and another for dynamic libraries. - The core libraries (src/coreclr/nativeaot): System.Private.CoreLib (corelib), System.Private.Reflection.* (the implementation of reflection), System.Private.TypeLoader (ability to load new types that were not generated statically).
- The dotnet integration (src/coreclr/nativeaot/BuildIntegration). This is a set of .targets/.props files that hook into
dotnet publishto run the AOT compiler and execute the platform linker.
The AOT compiler typically takes the app, core libraries, and framework libraries as input. It then compiles the whole program into a single object file. Then the object file is linked to form a runnable executable. The executable is standalone (doesn't require a runtime), modulo any managed DllImports.
The executable looks like a native executable, in the sense that it can be debugged with native debuggers and have full-fidelity access to locals, and stepping information.
The compiler also has a mode where each managed assembly can be compiled into a separate object file. The object files are later linked into a single executable using the platform linker. This mode is mostly used in testing (it's faster to compile this way because we don't need to recompiling the same code from e.g. CoreLib). It's not a shipping configuration and has many problems (requires exactly matching compilation settings, forfeits many optimizations, and has trouble around cross-module generic virtual method implementations).
The repository has a number of Visual Studio Solutions files (*.sln) that are useful for editing parts of the repository. Build the repo from command line first before building using the solution files. Remember to select the appropriate configuration that you built. By default, build.cmd builds Debug x64 and so Debug and x64 must be selected in the solution build configuration drop downs.
Solutions related to this:
src\coreclr\nativeaot\nativeaot.sln. This solution is for the runtime libraries.src\coreclr\tools\aot\ilc.sln. This solution is for the compiler.
Typical workflow for working on the compiler:
- Open
ilc.slnin Visual Studio - Set "ILCompiler" project in solution explorer as your startup project
- Set Working directory in the project Debug options to your test project directory, e.g.
C:\test - Set Application arguments in the project Debug options to the response file that was generated by regular native aot publishing of your test project, e.g.
@obj\Release\net6.0\win-x64\native\HelloWorld.ilc.rsp - Build & run using F5
Typical native AOT runtime developer scenario workflow is to native AOT compile a short piece of C# and run it. The repo contains helper projects that make debugging the AOT compiler and the runtime easier.
The workflow looks like this:
- Build the repo using the Building instructions above
- Open the ilc.sln solution described above. This solution contains the compiler, but also an unrelated project named "repro". This repro project is a small Hello World. You can place any piece of C# you would like to compile in it. Building the project will compile the source code into IL, but also generate a response file that is suitable to pass to the AOT compiler.
- Make sure you set the solution configuration in VS to the configuration you just built (e.g. x64 Debug).
- In the ILCompiler project properties, on the Debug tab, set the "Application arguments" to the generated response file. This will be a file such as "C:\runtime\artifacts\bin\repro\x64\Debug\compile-with-Release-libs.rsp". Prefix the path to the file with "@" to indicate this is a response file so that the "Application arguments" field looks like "@some\path\to\file.rsp".
- Build & run ILCompiler using F5. This will compile the repro project into an
.objfile. You can debug the compiler and set breakpoints in it at this point. - The last step is linking the object file into an executable so that we can launch the result of the AOT compilation.
- Open the src\coreclr\tools\aot\ILCompiler\reproNative\reproNative.vcxproj project in Visual Studio. This project is configured to pick up the
.objfile we just compiled and link it with the rest of the runtime. - Set the solution configuration to the tuple you've been using so far (e.g. x64 Debug)
- Build & run using F5. This will run the platform linker to link the obj file with the runtime and launch it. At this point you can debug the runtime and the various System.Private libraries.
If you haven't built the tests yet, run src\tests\build.cmd nativeaot [Debug|Release] tree nativeaot on Windows, or src/tests/build.sh -nativeaot [Debug|Release] -tree:nativeaot on Linux. This will build the smoke tests only - they usually suffice to ensure the runtime and compiler is in a workable shape. To build all Pri-0 tests, drop the tree nativeaot parameter. The Debug/Release parameter should match the build configuration you used to build the runtime.
To run all the tests that got built, run src\tests\run.cmd runnativeaottests [Debug|Release] on Windows, or src/tests/run.sh --runnativeaottests [Debug|Release] on Linux. The Debug/Release flag should match the flag that was passed to build.cmd in the previous step.
To run an individual test (after it was built), navigate to the artifacts\tests\coreclr\[Windows|Linux|OSX[.x64.[Debug|Release]\$path_to_test directory. $path_to_test matches the subtree of src\tests. You should see a [.cmd|.sh] file there. This file is a script that will compile and launch the individual test for you. Before invoking the script, set the following environment variables:
- CORE_ROOT=$repo_root\artifacts\tests\coreclr[Windows|Linux|OSX].x64.[Debug|Release]\Tests\Core_Root
- CLRCustomTestLauncher=$repo_root\src\tests\Common\scripts\nativeaottest[.cmd|.sh]
$repo_root is the root of your clone of the repo.
Sometimes it's handy to be able to rebuild the managed test manually or run the compilation under a debugger. A response file that was used to invoke the ahead of time compiler can be found in $repo_root\artifacts\tests\coreclr\obj\[Windows|Linux|OSX].x64.[Debug|Release]\Managed.
For more advanced scenarios, look for at Building the Tests and Building the Core_Root
Build library tests by passing the libs.tests subset together with the /p:TestNativeAot=true to build the libraries, i.e. clr.aot+libs+libs.tests /p:TestNativeAot=true together with the full arguments as specified above. Then, to run a specific library, go to the tests directory of the library and run the usual command to run tests for the library (see Running tests for a single library) but add the /p:TestNativeAot=true and the build configuration that was used, i.e. dotnet.cmd build /t:Test /p:TestNativeAot=true -c Release.
If you want to know more about working with NativeAOT in general, you can check out their more in-depth docs in the src/coreclr/nativeaot subtree.