[NativeAOT] Update documentation when building native libraries with a custom native host

[ivanpovazan]

The documentation for building native libraries with NativeAOT should be updated with the description of recently added feature: compiling a managed program as a static library linked with a custom native host application: #81873

/cc: @AustinWise @dotnet/ilc-contrib

[ghost]

Tagging subscribers to this area: @agocke, @MichalStrehovsky, @jkotas
See info in area-owners.md if you want to be subscribed.

Issue Details

---

The documentation for building native libraries with NativeAOT should be updated with the description of recently added feature: compiling a managed program as a static library linked with a custom native host application: #81873

/cc: @AustinWise @dotnet/ilc-contrib

Author:	ivanpovazan
Assignees:	-
Labels:	documentation, area-NativeAOT-coreclr
Milestone:	8.0.0

[AustinWise]

I'll eventually add this to the docs, but this is the short version of how to build a static library that also includes the executable entry point.

Add this property to your project:

<PropertyGroup>
  <IlcArg>-splitinit</IlcArg>
</PropertyGroup>

This will generate a symbol for the managed main function. You can call it by writing the following C declaration:

#if defined(_WIN32)
extern "C" int __managed__Main(int argc, wchar_t* argv[]);
#else
extern "C" int __managed__Main(int argc, char* argv[]);
#endif

Otherwise follow the instructions for linking the static library.

[MichalStrehovsky]

I wonder if we really need to document/support this outside Xamarin. The static library building experience is subpar and not something we suggest in general (need to worry about versions of C/C++ compiler and libc the runtime was built against and versions the user code is using). Dynamic libraries provide a better experience and most people should go with that.

Static libraries with custom main are a niche of a niche and it might be better to not overcomplicate the docs with that.

[agocke]

This seems like the kind of thing that could go in a runtime-repo doc file, but we wouldn't want to put in public documentation.

[AustinWise]

I agree it's a pretty niche feature.

The CustomNativeMain property might be more appropriate to document in a public place. It integrates nicely with the existing NativeAOT MSBuild targets.

[ivanpovazan]

I wonder if we really need to document/support this outside Xamarin. The static library building experience is subpar and not something we suggest in general (need to worry about versions of C/C++ compiler and libc the runtime was built against and versions the user code is using). Dynamic libraries provide a better experience and most people should go with that.

Static libraries with custom main are a niche of a niche and it might be better to not overcomplicate the docs with that.

I understand, I just wanted to avoid having this feature left undocumented.
Especially because it is the integration point for both Xamarin and AppleAppBuilder and would be useful for developers working on the integration to have it documented somewhere.

Would https://github.com/dotnet/runtime/blob/main/src/coreclr/nativeaot/docs/interop.md maybe be a better location or you would like to keep it private (internal) completely?

[AustinWise]

I made a sample for the CustomNativeMain property here:

https://github.com/AustinWise/SplitInit

I'll see about putting something in the official interop docs.

It looks like Xamarin is using the CustomNativeMain property, so there is probably no need to document the -splitinit flag to ILC.exe.

[ivanpovazan]

Thank you for the provided sample.
I wonder if the sample and/or the description explaining the CustomNativeMain property could be added to: https://github.com/dotnet/samples/tree/main/core/nativeaot instead.

Regarding the public documentation, I am not sure what should be the right solution.
It is true that we integrated Xamarin builds with NativeAOT, as we knew (or discovered) what flags need to be passed to achieve this, and there is an open issue on simplifying that process: #87187
Nevertheless, I think it would be useful to have (somewhere) a documentation explaining the integration process. Maybe the right place for such documentation is not dotnet/runtime, but rather Xamarin (and/or other app models) I am not sure.

@MichalStrehovsky @jkotas what do you think?

[jkotas]

I wonder if the sample and/or the description explaining the CustomNativeMain property could be added to: https://github.com/dotnet/samples/tree/main/core/nativeaot instead.

I agree with what Michal said in #82156 (comment) . I do not think it is worth it to complicate the mainstream documentation or samples with CustomNativeMain explanation.

I think it would be useful to have (somewhere) a documentation explaining the integration process. Maybe the right place for such documentation is not dotnet/runtime, but rather Xamarin (and/or other app models) I am not sure.

Having document in Xamarin that explains how all parts are put together (including the static registrar, etc.) sounds reasonable to me.

[ivanpovazan]

Having document in Xamarin that explains how all parts are put together (including the static registrar, etc.) sounds reasonable to me.

I am closing this issue in favour of: dotnet/macios#18585 which should track providing a public documentation regarding Xamarin+NativeAOT support. Please feel free to add more context there, if necessary, and review the changes once we get a PR for it.