[PATCH] D12685: Document the stability policy for LLVM-C APIs.

Tue Sep 15 14:05:51 PDT 2015

echristo added a reviewer: grosbach.
echristo added a comment.

In http://reviews.llvm.org/D12685#246351, @jyknight wrote:

> > > The LLVM C API use-case I'm most familiar with is other language frontends, themselves written in non-C languages. That use-case can basically tolerate the API changing over time, by using build or runtime conditionals (or just dropping support for the old version of llvm), but it's very useful to be able to be able to easily detect such API incompatibility. That use-case is what this policy intends to support, with the existing LLVM-C API.
>
> > 
>
> > 
>
> > I see something similar to this, but for external projects that just don't update frequently. I.e. I've got my own project, it needs a lot of C APIs to do approximately everything with llvm (or, hey, we could autogenerate all of the language bindings). We can't support that sort of C API use case at all, but that's the direction that a lot of the use is going. I say we can't support it because any sort of deprecation or attempt to keep stable scheme is going to lock down the C++ API in ways that are unacceptable (at least to me and anyone I've spoken to on the project).
>
>
> I 100% agree with that, the existence or maintenance policy for the LLVM-C API should not lock down the ability to change the C++ API. I disagree that this policy has the effect you're concerned about, however. I do not think this policy locks down the C++ API in any way.

Ah. I see what you mean. Basically codify "best effort" as the policy, but not any more strict than that.

On that note then, what would be the point of @deadalnix's patch to add testing to the C API? To make sure that nothing changes out from under people in behavior?

> > My problem is that the surface you're proposing to be even pseudo-stable is just too large and locks down too much of the API. I, honestly, don't even like the little bit of hack that we (Mehdi in this case) had to add in TargetMachine while working on the DataLayout requirement to support the existing C API.

> 

> 

> But that's exactly the point! That sort of hacky workaround to attempt to keep 100% stability is exactly what I'm trying to say is **not** required!

> 

> According to the policy written here (at least, what I meant, if it's not clear as written) all Mehhdi should've done in this instance was to delete the LLVMGetTargetMachineData function, because it no longer makes any sense. LLVM changed such that data layout is only an attribute of the module, not the target machine, so the old C API accessing it from the TargetMachine is nonsensical. Thus, remove it. End of story.

> 

> Ideally, LLVMGetTargetMachineData() could've been deprecated at the beginning of the process of starting to remove TargetMachine::getDataLayout (Early march?), before it was finally removed on Jul 24. But even that is no requirement, just a "nice thing to do if you remember".

OK, I mean sure, I'd like this too, but I think enough users at least care about the "being able to read" and probably "be able to execute" IR created by an older process when a newer llvm comes onto the system. I'm thinking in the graphics driver area that Mehdi works in. I think webkit even uses the C++ API for creation and the C API for the jit. Basically the stable C API could be the same as the bitcode guarantees + deprecation if we change something drastically - we support reading older IR and autoupgrading it to something that can be used.

I really don't like libLTO, but I think creating a new one is going to have issues, we should just deprecate it as lld comes on line.

Thoughts?

http://reviews.llvm.org/D12685