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

Activity

1. ivanpovazan

   added

   documentationDocumentation bug or enhancement, does not impact product or test codeDocumentation bug or enhancement, does not impact product or test code

   area-NativeAOT-coreclr

   on Feb 15, 2023
2. ivanpovazan

   added this to the 8.0.0 milestone on Feb 15, 2023
4. AustinWise commented on Feb 27, 2023

   

   AustinWise

   on Feb 27, 2023

   Last edited by AustinWise

   Contributor

   More actions

   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.
5. MichalStrehovsky commented on Feb 28, 2023

   

   MichalStrehovsky

   on Feb 28, 2023

   Member

   More actions

   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.

   👍React with 👍1Reacted by Jan Kotas
6. agocke commented on Feb 28, 2023

   

   agocke

   on Feb 28, 2023

   Member

   More actions

   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.
7. agocke

   modified the milestones: 8.0.0, Future on Feb 28, 2023
8. AustinWise commented on Mar 1, 2023

   

   AustinWise

   on Mar 1, 2023

   Contributor

   More actions

   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.
9. ivanpovazan commented on Mar 1, 2023

   

   ivanpovazan

   on Mar 1, 2023

   MemberAuthor

   More actions

   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?
10. agocke

    added this to AppModelon Mar 6, 2023
11. AustinWise commented on Jun 25, 2023

    

    AustinWise

    on Jun 25, 2023

    Contributor

    More actions

    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.
12. ivanpovazan commented on Jun 29, 2023

    

    ivanpovazan

    on Jun 29, 2023

    MemberAuthor

    More actions

    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?
13. jkotas commented on Jun 29, 2023

    

    jkotas

    on Jun 29, 2023

    Member

    More actions

    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.

    👍React with 👍1Reacted by Michal Strehovský
14. ivanpovazan commented on Jul 25, 2023

    

    ivanpovazan

    on Jul 25, 2023

    MemberAuthor

    More actions

    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.
15. ivanpovazan

    closed this as completedon Jul 25, 2023
16. ghost locked as resolved and limited conversation to collaborators on Aug 24, 2023