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

[Eric Christopher via llvm-commits]

On Tue, Sep 15, 2015 at 10:46 AM James Y Knight <jyknight at google.com> wrote:

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


> 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.
>
>
The use here is a stable JIT API or a stable LTO api that can be used by
existing clients. These interfaces (outside of IR building) have actually
been reasonably stable for some time. Now some of that is that these
portions of code are also not being worked on much.


> 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.)
>
>
For a good portion of the people not-me that seem to care about it you also
have a) webkit, b) graphics drivers. I, honestly, don't care other than
that I don't want the C++ API to have to suffer for the C API.


> 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").
>

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.

-eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150915/dac7446d/attachment.html>