NuGet package 10.0.0-beta

[NickStrupat]

Does anyone know/remember what's remaining to get this package up to 10.0.0?

[tannergooding]

The raw bindings (https://github.com/microsoft/LLVMSharp/tree/master/sources/LLVMSharp/Interop) and minimal wrapper API (https://github.com/microsoft/LLVMSharp/tree/master/sources/LLVMSharp/Interop.Extensions) should be stable and could be published as a 10.0.0 package.

The proper managed wrapper (such as https://github.com/microsoft/LLVMSharp/tree/master/sources/LLVMSharp/Values, https://github.com/microsoft/LLVMSharp/tree/master/sources/LLVMSharp/Types however is not and would likely need to be ifdef'd out or pulled out to a separate library.

[NickStrupat]

Would this mean one package for raw bindings and one package for managed wrappers? Raw could be LLVMSharp.Interop and managed wrapper could be LLVMSharp.Managed.

Apologies for my confusion, but it sounds like the managed wrappers need to be updated to match the raw binding changes caused by an API change from LLVM 9 -> 10. Is that correct? In other words, can I approximate what work needs to be done by diffing the relevant raw binding changes for the commit(s) that correspond to the update from 9 -> 10?

Thanks!

[tannergooding]

Raw could be LLVMSharp.Interop and managed wrapper could be LLVMSharp.Managed.

Yes, that could be a possibility. Although I think LLVMSharp and LLVMSharp.Interop might be better.

Apologies for my confusion, but it sounds like the managed wrappers need to be updated to match the raw binding changes caused by an API change from LLVM 9 -> 10

Not quite. The API surface was changed pretty drastically between 5.0.0 and 8.0.0-beta. Namely the interop bindings went through some breaking changes to make them easier to generate and maintain.

The high level managed wrapper is also a complete rewrite and is being designed to more closely match the LLVM C++ bindings (i.e. https://llvm.org/doxygen/classllvm_1_1LLVMContext.html, https://llvm.org/doxygen/classllvm_1_1Type.html, https://llvm.org/doxygen/classllvm_1_1Value.html). However, there is a lot of surface that hasn't been defined yet and that still needs work before it could be considered stable.

So LLVMSharp.Interop could be marked as stable and have a 10.0.0 package. While LLVMSharp (the high level managed API) would still be 10.0.0-beta.

@mjsabby, do you see any issues with making this split so we can have stable interop bindings without requiring the managed wrapper to have the same stability?

[NickStrupat]

Ok thanks. I'll take a look at the C++ bindings to get some more context.

A bit of a tangent, but have you looked at using ClangSharp to consume the C++ bindings and try to generate the managed wrapper classes automatically? I'm guessing you have, but I had to ask :)

[mjsabby]

I personally don't like the idea of two assemblies for essentially the same functionality. It is sort of expected that the LLVM C APIs are somewhat stable, but not completely. I mean LLVM makes a lot of breaking changes (or at least did in the past). Couldn't we follow the same model?

Also is the -beta thing more of an annoyance or does it cause grievance when including in a product (because it is called beta)?

[ericsink]

Possibly clueless question:

Is it true that the reason these two things have different notions of stability is because the raw bindings are auto-generated while the proper managed wrapper requires stuff to be done by hand?

[tannergooding]

The raw bindings are auto-generated and since they are generated as 1-to-1 they should always be "correct" and therefore are basically stable from the moment they are checked in (minus minor bugs or issues that can easily be patched).

The higher level bindings however, are a manually written API that has a higher chance of introducing bugs or mistakes and which might not be in the right shape based on user feedback. Breaks introduced here might also be more painful to respond to.

[tannergooding]

I mean LLVM makes a lot of breaking changes (or at least did in the past). Couldn't we follow the same model?

I'm not worried about introducing breaks between 10.0.0 and 11.0.0, as that just follows the standard SemVer model.

I am concerned with saying the current managed wrapper is "stable" at 10.0.0 and then breaking it in 10.0.1 because some more work was done and we found things weren't done the right way.

Using 10.1.0 might be easier, but if LLVM itself ships a 10.1, then it might get confusing as to how things match up.

[NickStrupat]

I personally don't like the idea of two assemblies for essentially the same functionality. It is sort of expected that the LLVM C APIs are somewhat stable, but not completely. I mean LLVM makes a lot of breaking changes (or at least did in the past). Couldn't we follow the same model?

Also is the -beta thing more of an annoyance or does it cause grievance when including in a product (because it is called beta)?

Currently it's an annoyance for myself, but it will develop into a grievance as my project progresses.

Valid technical issues aside, I think the beta tag causes some doubt about the authority of the LLVMSharp package. When a package of a project on github.com/microsoft sits in beta for many months, it signals to package consumers that it may have been abandoned or at least isn't receiving the attention one would prefer/expect.

[NickStrupat]

The raw bindings are auto-generated and since they are generated as 1-to-1 they should always be "correct" and therefore are basically stable from the moment they are checked in (minus minor bugs or issues that can easily be patched).

The higher level bindings however, are a manually written API that has a higher chance of introducing bugs or mistakes and which might not be in the right shape based on user feedback. Breaks introduced here might also be more painful to respond to.

Could we not, in principle, walk the declarations of the LLVM C++ API using ClangSharp and generate managed wrappers?

[ericsink]

The raw bindings are auto-generated and since they are generated as 1-to-1 they should always be "correct" and therefore are basically stable from the moment they are checked in (minus minor bugs or issues that can easily be patched).

The higher level bindings however, are a manually written API that has a higher chance of introducing bugs or mistakes and which might not be in the right shape based on user feedback. Breaks introduced here might also be more painful to respond to.

For this reason, I think of these as two rather different pieces of software, and having them be separate packages would make sense to me.

[tannergooding]

Could we not, in principle, walk the declarations of the LLVM C++ API using ClangSharp and generate managed wrappers?

Not easily. There isn't a 1-to-1 mapping (or even always a clear mapping) between the C types and APIs exposed and the available C++ APIs.

It's really a best effort approach after examining the C API and comparing to what the C++ API exposes.
In some cases, you can also define an additional library (like we do with libClangSharp for ClangSharp) to help fill some gaps (with appropriate issues and proposals to try and contribute them back to libClang and libLLVM proper, of course).

I haven't had as much time to invest into LLVMSharp which is why its managed wrapper isn't as far done as the ClangSharp version is.

LLVM 11 will also be coming out soon (I think just one blocking bug) and so versions off both projects should be coming out shortly after that.

[tannergooding]

I haven't had as much time to invest into LLVMSharp which is why its managed wrapper isn't as far done as the ClangSharp version is.

That being said, now that .NET 5 work is slowing down as we prepare for the November release; I might be able to put some more effort in here to try and finish rounding it out.

[tannergooding]

I've split the project into LLVMSharp and LLVMSharp.Interop.

The LLVMSharp.Interop bindings should be generally "stable" each release and so I'll likely be publishing 12.0.0 as "stable" tomorrow. LLVMSharp is the managed wrapper over the interop bindings and is not yet "stable", so it will continue to be beta.