diff --git a/docs/nativeaot.md b/docs/nativeaot.md new file mode 100644 index 000000000000..8475a52fc057 --- /dev/null +++ b/docs/nativeaot.md @@ -0,0 +1,82 @@ +# NativeAOT + +We've added *experimental* support for using [NativeAOT][1] when publishing iOS, +tvOS, Mac Catalyst and macOS apps in .NET 8. + +NativeAOT may produce smaller and/or faster apps - or it may not. It's very +important to test and profile to determine the results of enabling NativeAOT. + +Our initial testing shows significant improvements both in size (up +to 50% smaller) and startup (up to 50% faster). For more information about +performance see [.NET 8 Performance Improvements in .NET MAUI][3]. + +However, it is important to point out that NativeAOT requires trimming whole +applications (using `Full`, which is enabled by +default) and is much more restrictive and aggressive in removing code which is +not AOT compatible. As a result, if the applications is using some AOT +incompatible constructs (e.g. dynamically referencing code for which a +dependency cannot be statically determined), NativeAOT compiler might remove +them during build time, which can result in crashes at runtime. To warn users +about when this can happen, trimming and AOT warnings are produced and they +should not be neglected. Instead, all such warnings should be addressed, code +adapted accordingly, and the application must be tested and profiled in this +configuration. Only then it is safe to assume that the application is +compatible with NativeAOT and should not cause any unexpected behaviour. + +Finally, there could be cases when fixing mentioned trimming and AOT warnings +is not possible, i.e. warnings coming from referenced frameworks or +third-party libraries. In such cases, `SdkOnly` can +be specified on the project level and could help as a workaround. This affects +the application size, but even in this mode NativeAOT tends to produce up to +28% smaller applications compared to Mono showing a great potential of this +new experimental feature. + +## How to enable NativeAOT? + +NativeAOT is enabled by setting the `PublishAot` property to `true` in the project file: + +```xml + + true + +``` + +## Notes + +NativeAOT is only used when publishing (`dotnet publish`). In particular +`dotnet build -t:Publish` is _not_ equivalent to `dotnet publish`, only +`dotnet publish` will enable NativeAOT. + +**Unsupported** workaround: set the `_IsPublishing` property to `true` to make +`dotnet build` think it's `dotnet publish`: + +```xml + + true + <_IsPublishing>true + +``` + +This can be useful to install and run apps with `NativeAOT` from the IDE, +because it's not possible to use `dotnet publish` when running from the IDE. + +## Compatibility and limitations + +There are no known issues specific to our platforms with NativeAOT; but the +[limitations][2] are exactly the same as for other supported platforms. + +Nevertheless, we would like to point out a few features that are not available +with NativeAOT, that are with Mono, when targeting Apple platforms: + +- NativeAOT does not support managed debugging. + +- There's no interpreter when using NativeAOT, and as such the + `UseInterpreter` and `MtouchInterpreter` properties have no effect. + +- NativeAOT requires trimming, and `MAUI` isn't trimmer-safe, and thus + unfortunately `MAUI` projects don't typically work with NativeAOT (we hope + to rectify this situation for .NET 9). + +[1]: https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot +[2]: https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#limitations-of-native-aot-deployment +[3]: https://devblogs.microsoft.com/dotnet/dotnet-8-performance-improvements-in-dotnet-maui/