[docs] Document NativeAOT support. Fixes #18585.

[rolfbjarne]

Fixes #18585.

[rolfbjarne]

CC @MichalStrehovsky

[charlesroddie]

(can't delete this from github app)

[ivanpovazan]

Suggested change

	Note that 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).
	There are no known issues specific to our platforms with NativeAOT; but the
	[limitations][2] are exactly the same as for other platforms.
	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).

[ivanpovazan]

@rolfbjarne regarding the issue with MAUI not being trimmer-safe, do we want to mention that setting TrimMode=partial could help?

On that note, should we maybe generalise the problem to all non-trimmable assemblies?

[rolfbjarne]

I never tested MAUI projects, but I was under the impression they didn't work, no workaround possible?

[ivanpovazan]

I will take a look, I believe I had an example where TrimMode=partial helped, and still produced smaller app than Mono - I will double-check.
I just felt that don't typically work is a bit harsh (even though its most-probably true).

[ivanpovazan]

Here is the gist with analysis of building/running 5 different MAUI iOS apps with NativeAOT using different trimming modes: https://gist.github.com/ivanpovazan/4756bdb65a34366f0944e99f601379f3

I did not go deeper with examining why something failed, but just wanted to give an overview regarding TrimMode=partial vs TrimMode=full

[stephen-hawley]

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.

[rolfbjarne]

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?

[ivanpovazan]

@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 :)

[rolfbjarne]

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

[ivanpovazan]

LGTM, Thank you!