[docs] Add building iOS-like native libraries with NativeAOT #43397

ivanpovazan · 2024-11-11T09:07:08Z

Summary

This PR adds documentation describing how to build and consume native libraries with NativeAOT targeting iOS-like platforms.

Fixes dotnet/runtime#96742
Contributes to: dotnet/runtime#96664

Internal previews

📄 File	🔗 Preview link
docs/core/deploying/native-aot/index.md	Native AOT deployment
docs/core/deploying/native-aot/ios-like-platforms/creating-and-consuming-custom-frameworks.md	Create and consume custom frameworks for iOS-like platforms
docs/core/deploying/native-aot/ios-like-platforms/index.md	Native AOT support for iOS-like platforms
docs/navigate/devops-testing/toc.yml	docs/navigate/devops-testing/toc

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md

jkotas · 2024-11-11T19:39:40Z

#43399 (comment) applies to this change as well.

docs/core/deploying/native-aot/libraries/index.md

Co-authored-by: Jan Kotas <[email protected]>

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md

Co-authored-by: Michal Strehovský <[email protected]>

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md

jkotas · 2024-11-13T07:24:26Z

#43399 (comment) applies to this change as well.

Do you have thoughts about moving this doc to where the rest iOS-like specific native AOT docs live?

I understand that those are MAUI specific docs. However, a lot of content in there is more generally applicable than MAUI. We seem to be making simplifying assumption that everything mobile specific falls under MAUI.

ivanpovazan · 2024-11-13T09:11:19Z

Do you have thoughts about moving this doc to where the rest iOS-like specific native AOT docs live?

I can see advantages and disadvantages with that approach:

advantages
- all NativeAOT iOS-like specific docs are in one place
disadvantages
- it may sound confusing describing a feature that does not require mobile workloads to be installed under MAUI docs, as if MAUI is a requirement, which is not
- in this scenario we are explicitly targeting TFMs without OS-specific APIs, if someone would confuse a class library which specifies net9.0-ios publishing such library currently does not really do anything useful. Again, it seems confusing as MAUI utilizes OS-specific TFMs
- MAUI does not support tvOS while Native AOT does (I admit I was not mentioning this in the doc, I can correct it if we decide to keep the docs here)
- nit: In this scenario we still need to specify PublishAotUsingRuntimePack which we don't mention in MAUI docs as it is handled by mobile SDK

jkotas · 2024-11-13T19:19:21Z

targeting TFMs without OS-specific APIs,

I would not be optimizing the docs layout around the fact that we do not have support for Objective-C interop in NAOT published libraries. It is not a fundamental limitation, it is just something that we have not found time for.

MAUI does not support tvOS while Native AOT does

Right, and this doc problem exists for Mono too. We do not seem to mention existence of the tvos workload anywhere in the docs.

nit: In this scenario we still need to specify PublishAotUsingRuntimePack which we don't mention in MAUI docs as it is handled by mobile SDK

Right, and it is also applicable to building raw iOS apps without mobile SDK. It is not specific to building libraries without mobile SDK.

After thinking about this some more, I would like to avoid the mainline docs to be cluttered with platform or app-model specific content. It makes them look complicated. At the same time, we should make the platform specific content more discoverable. For example, https://review.learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/?branch=pr-en-us-43397&tabs=windows%2Cnet9plus mentions iOS as supported, but it does not point you to a place where you can find anything more about it.

How about we move the platform-specific to its own hives at the end, like:

Native AOT deployment
- ...
- AOT warnings
- iOS-like platforms
  - Overview - this can mention RIDs to use, and that you need the PublishAotUsingRuntimePack if you use the RID that is not iOS specific, it can have a link to MAUI docs. It can be linked from the main page where iOS is mentioned as supported.
  - Creating and consuming a custom framework - the doc in your PR
  - ...
- Android
  - potential future Android specific topics
- WASI
  - potential future WASI specific topics

ivanpovazan · 2024-11-14T11:09:25Z

How about we move the platform-specific to its own hives at the end, like:

Thats sounds like a good idea, I will look into it.
For experimental/unsupported platforms (Android, WASI) should we introduce a placeholder pages in this PR?

jkotas · 2024-11-14T14:45:32Z

For experimental/unsupported platforms (Android, WASI) should we introduce a placeholder pages in this PR?

I do not think we have placeholder pages like that anywhere in the official docs.

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md

gewarren

Thanks for this great article @ivanpovazan. I left some grammatical suggestions.

docs/core/deploying/native-aot/libraries/index.md

docs/core/deploying/native-aot/libraries/xcode-add-framework-reference.png

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md

Co-authored-by: Genevieve Warren <[email protected]>

ivanpovazan · 2024-11-21T15:48:21Z

@jkotas I restructured the doc as suggested, could you please give it another look?

jkotas · 2024-11-21T15:51:28Z

docs/navigate/devops-testing/toc.yml

@@ -503,6 +503,12 @@ items:
            href: ../../core/deploying/native-aot/interop.md
          - name: Build native libraries
            href: ../../core/deploying/native-aot/libraries.md
+          - name: iOS-like platforms


I would put this and future OS-specific topics at the end of "Native AOT deployment model" list.

jkotas · 2024-11-21T15:54:28Z

docs/core/deploying/native-aot/ios-like-platforms/index.md

+
+Starting from .NET 8, Native AOT supports targeting iOS-like platforms. The term *iOS-like platforms* refers to Apple platforms that use similar APIs such as: iOS, MacCatalyst and tvOS.
+
+In the first release, the support was experimental, while in .NET 9 these platforms received full support with Native AOT.


I do not think we need to be going over the history and that we have shipped it as an experiment for one release. We should just say that this is supported starting .NET 9.

jkotas · 2024-11-21T15:56:34Z

docs/core/deploying/native-aot/ios-like-platforms/index.md

+
+For specifics of building and consuming native libraries on iOS-like platforms, see [How to create and consume custom frameworks with Native AOT for iOS-like platforms](./creating-and-consuming-custom-frameworks.md).
+
+## Support for applications and libraries referencing OS-specific APIs


This should be the first since it is the more common case.

Add building iOS-like native libraries with NativeAOT documentation

665aaa7

ivanpovazan requested review from rolfbjarne, agocke, jkotas and MichalStrehovsky November 11, 2024 09:07

ivanpovazan requested review from adegeo and a team as code owners November 11, 2024 09:07

dotnetrepoman bot added this to the November 2024 milestone Nov 11, 2024

dotnetrepoman bot added the dotnet-fundamentals/svc label Nov 11, 2024

ivanpovazan mentioned this pull request Nov 11, 2024

Add documentation for building native libraries with NativeAOT targeting iOS-like platforms dotnet/samples#6997

Closed

Add redirect url

1a6cd9a

ivanpovazan requested a review from vitek-karas November 11, 2024 10:05

jkotas reviewed Nov 11, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md Outdated Show resolved Hide resolved

jkotas reviewed Nov 11, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/index.md Outdated Show resolved Hide resolved

ivanpovazan and others added 2 commits November 12, 2024 09:23

Avoid using term: desktop platforms

48df885

Co-authored-by: Jan Kotas <[email protected]>

Clarify the use case

64973cb

MichalStrehovsky reviewed Nov 12, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md Outdated Show resolved Hide resolved

MichalStrehovsky reviewed Nov 12, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md Outdated Show resolved Hide resolved

ivanpovazan and others added 2 commits November 12, 2024 14:41

Feedback

a5b3f3c

Co-authored-by: Michal Strehovský <[email protected]>

Simplify publish instructions

41ba639

jkotas reviewed Nov 13, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md Outdated Show resolved Hide resolved

rolfbjarne approved these changes Nov 14, 2024

View reviewed changes

docs/core/deploying/native-aot/libraries/ios-like-native-libraries-with-nativeaot.md Outdated Show resolved Hide resolved

gewarren reviewed Nov 15, 2024

View reviewed changes

Apply grammatical suggestions from code review

6316f47

Co-authored-by: Genevieve Warren <[email protected]>

ivanpovazan added 6 commits November 20, 2024 17:09

Fix indent in source code sample

d7af207

wip: Restructuring

8cb303a

wip: Update TOC

6fda5dd

wip: Restructure clean up

2c882a8

wip: Adding overview page

ec65ba0

wip: clean up

b7df7aa

jkotas reviewed Nov 21, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add building iOS-like native libraries with NativeAOT #43397

[docs] Add building iOS-like native libraries with NativeAOT #43397

ivanpovazan commented Nov 11, 2024 •

edited by github-actions bot

Loading

jkotas commented Nov 11, 2024

jkotas commented Nov 13, 2024

ivanpovazan commented Nov 13, 2024

jkotas commented Nov 13, 2024

ivanpovazan commented Nov 14, 2024

jkotas commented Nov 14, 2024

gewarren left a comment

ivanpovazan commented Nov 21, 2024

jkotas Nov 21, 2024

jkotas Nov 21, 2024

jkotas Nov 21, 2024


		Starting from .NET 8, Native AOT supports targeting iOS-like platforms. The term iOS-like platforms refers to Apple platforms that use similar APIs such as: iOS, MacCatalyst and tvOS.

		In the first release, the support was experimental, while in .NET 9 these platforms received full support with Native AOT.


		For specifics of building and consuming native libraries on iOS-like platforms, see [How to create and consume custom frameworks with Native AOT for iOS-like platforms](./creating-and-consuming-custom-frameworks.md).

		## Support for applications and libraries referencing OS-specific APIs

[docs] Add building iOS-like native libraries with NativeAOT #43397

Are you sure you want to change the base?

[docs] Add building iOS-like native libraries with NativeAOT #43397

Conversation

ivanpovazan commented Nov 11, 2024 • edited by github-actions bot Loading

Summary

Internal previews

jkotas commented Nov 11, 2024

jkotas commented Nov 13, 2024

ivanpovazan commented Nov 13, 2024

jkotas commented Nov 13, 2024

ivanpovazan commented Nov 14, 2024

jkotas commented Nov 14, 2024

gewarren left a comment

Choose a reason for hiding this comment

ivanpovazan commented Nov 21, 2024

jkotas Nov 21, 2024

Choose a reason for hiding this comment

jkotas Nov 21, 2024

Choose a reason for hiding this comment

jkotas Nov 21, 2024

Choose a reason for hiding this comment

ivanpovazan commented Nov 11, 2024 •

edited by github-actions bot

Loading