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

[James Y Knight via llvm-commits]

jyknight added a comment.

> FWIW I'm on the same track as Eric on this topic. 

>  Ideally, I would love to have a way for the "bindings" to be auto-generated as much as possible from the C++ public headers, and thus they couldn't have different stability guarantee than the C++ API.

> 

> Right now I'm not sure we take it by the right end, Who are the clients of a "stable" C API vs a binding API? what are the use cases to solve? A "stable" C API needs to have a smaller surface than the bindings (obviously), but to which extent?


What use-cases do you or Eric think would be well-served by an autogenerated C api which has no stability or compatibility guarantees at all? I just can't see that sort of completely-unstable api as being really usable for what people would like from a C API.

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.

On the other side, the "actually stable" API that's been discussed, I also don't really see a terribly large use-case for. "It would be nice" if all the APIs were stable, but I can't really see being able to say "this is stable" with confidence about enough parts of LLVM for that to be realistically useful, except in very special limited circumstances. E.g., if you can't expose the LLVM IR builder functions as "stable" (which I think you cannot, since the IR changes with some regularity), that just seems like a non-starter.

So, I'm not sure who the envisioned clients of a "stable" LLVM API are, other than perhaps ld64 (which, I think, seems like somewhat of a special case.)

Honestly, to me, the existing C API seems to be positioned in just about the right place, so I'd like to see a policy on how to maintain it sanely, and not a policy of replacing it with something less suitable in either direction (that is, neither "too unstable" nor "too restricted").


http://reviews.llvm.org/D12685