Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Document NativeAOT support. Fixes #18585. #19362

Merged
merged 9 commits into from
Nov 9, 2023
Merged

[docs] Document NativeAOT support. Fixes #18585. #19362

Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
73e3c0f
[docs] Document NativeAOT support. Fixes #18585.
rolfbjarne Oct 26, 2023
a3beb93
Update docs/nativeaot.md
rolfbjarne Oct 27, 2023
a8bd099
Update docs/nativeaot.md
rolfbjarne Oct 27, 2023
a73ea3c
Update docs/nativeaot.md
rolfbjarne Oct 27, 2023
b8964e7
Update docs/nativeaot.md
rolfbjarne Oct 27, 2023
461b33e
Misc improvements
rolfbjarne Oct 27, 2023
499a062
Misc improvements
rolfbjarne Oct 27, 2023
17507dc
Update docs/nativeaot.md
rolfbjarne Nov 2, 2023
fb8cb38
Reword a bit.
rolfbjarne Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/nativeaot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# 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.

However, 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].

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not exactly confidence inspiring. If I were reading this, I would like to know under what circumstances this would generate larger or slower apps rather than leaving it up to me to profile.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately there's no easy way to predict how an app will turn out. The fact that projects are trimmed (linked) means that adding a single line of code somewhere can have a tremendous cascading effect, preventing a lot of other code from being removed. Then add the effect of different AOT compilers (Mono's AOT might generate bigger code in particular when it comes to generics, but there might be other code patterns that may have the opposite effect) multiplied by whatever code patterns is used by all the code that was brought in by that single line of extra code in the project... the answer really is that each project is different, and that developers must test their projects to see the effect of turning on NativeAOT. I'm not sure how to phrase it in a way that inspires more confidence?

Copy link
Member

@ivanpovazan ivanpovazan Nov 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rolfbjarne maybe something like this might help you phrase it in the right way:

Suggested change
Our initial testings shows significant improvements both in size (up
to 50% smaller) and startup (up to 50% faster) compared to the default offering with the Mono runtime (for more information please checkout [.NET 8 Performance Improvements in .NET MAUI][3]).
However, it is important to point out that NativeAOT requires trimming whole applications `<MtouchLink>Full</MtouchLink>` (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 with crashes at runtime. To warn users about when this can happen, adequate trimming and AOT warnings are produced and they should not be neglected. Instead, all such warnings should be addressed, code adapted accordingly, application 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, `<MtouchLink>SdkOnly</MtouchLink>` can be specified on the project level and could help as a workaround. This does affect 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.

PS I might have some grammatical mistakes as I am not a native speaker, but hope this helps :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated it according to Ivan's suggestion, @stephen-hawley does it look better now?

## How to enable NativeAOT?

NativeAOT is enabled by setting the `PublishAot` property to `true` in the project file:

```xml
<PropertyGroup>
<PublishAot>true</PublishAot>
</PropertyGroup>
```

## 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
<PropertyGroup>
<PublishAot>true</PublishAot>
<_IsPublishing>true</_IsPublishing>
</PropertyGroup>
```

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/pending_link_to_blog_post