[LLVMdev] [RFC] Developer Policy for LLVM C API

[Eric Christopher]

On Thu, Jul 30, 2015 at 3:36 PM Philip Reames <listmail at philipreames.com>
wrote:

> It's sounds like we've reached two rough conclusions:
> 1) We need both a stable and a non-stable fully featured C API.  It's a
> somewhat open question whether both or either should be part of the main
> tree.
>

I'm fine with the stable API being in the main tree. I proposed moving it
out originally so that it could get some work before moving it in. I'm
reasonably confident that we can get something working in tree for a stable
API by the next release though.


> 2) Everyone seemed okay with the proposed deprecation policy for the
> stable API.
>
>
Yes.


> Given this, I would propose we designate the existing C API as the
> "hopefully stable, but subject to future clean up per policy..."  Update
>

This is where we disagree. I've tried to lay out a design that I think
would be good for a stable API and the current one does not meet any
guidelines there. It's too much a thin wrapper on top of the existing C++
API. There's no clear delineation for when/how/whether we extend it. It's
already easy to subtly break the existing one.

My proposal here is simply thus:

We deprecate the existing API as "moving to unstable". For the next release
cycle, as a new C API comes into existence, we continue our best effort
toward keeping the existing API as stable as possible ("best effort") just
like we always have. At the next release we flip the switch that says "this
is now not stable, please use X". In the mean time we can either a) move a
bindings level C API into a separate directory starting with the existing
wrapped C++ API that we have as part of the C API, or b) expand in the
current directory and copy a set of APIs off to another directory. How to
do this with minimal churn in external projects is important - this is why
I'm inclined to say that the bindings API reside in the current C API
directory, but others are more hesitant, I'm just not sure in their mind
how the final transition from "best effort stable" to "stable".

-eric


> the documentation to note that LLVM does not currently have a fully
> featured C API.  Update the docs to reflect the deprecation policy for the
> existing C API.
>
> We can then start discussing how we should create the fully featured API.
> I'd lean towards a tool like Swig, but we could also do it purely on
> demand.  For example, I could add some shims for the experimental GC
> support without committing to supporting the current APIs long term.
>
> Philip
>
>
> On 07/30/2015 01:47 PM, Reid Kleckner wrote:
>
> On Thu, Jul 30, 2015 at 1:04 PM, Eric Christopher <echristo at gmail.com>
> wrote:
>
>> I think the idea of having a (hopefully not too) fluid C API that can
>> encompass everything people want to be able to do in the language of their
>> choice and calls into LLVM to do work sounds like a great idea. I think it
>> would be useful to expand the number of people who are able to do research
>> and development with LLVM without having to reinvent LLVM. That said, this
>> is directly at odds with our desire to have a stable C API that can be
>> supported long term (as you said at the end of the email). I.e. where do we
>> draw the line on what can or should be added to the C API? What if the
>> people that want the functionality are willing to deal with it being
>> (occasionally) unstable?
>>
>
> Yeah, splitting the concerns of API completeness and API stability seems
> like a good idea. Right now we have clients like llgo that want to generate
> new debug info, and are perfectly happy to keep up to date with changes.
> They need a complete API, not a stable API, and our insistence on a stable
> C API has actually gotten in the way here.
>
>
>> I don't agree with you that no one will take the time to design a well
>> thought out C API. We've managed to get a lot of real world experience
>> lately at both how these things will be used, and how we'll maintain such a
>> thing. I think Juergen and others are a good group to come up with an
>> answer to our engineering challenge.
>>
>
> Sure, if people are planning to design a stable API that leave LLVM with
> more flexibility, then I'm all in favor of switching over to it. So far I
> haven't heard any new suggestions. I think any such design would probably
> be write-only, and revolve around sharing the bitcode auto-upgrade logic.
>
>
> _______________________________________________
> LLVM Developers mailing listLLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.eduhttp://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150730/f5353e5f/attachment.html>