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

[Mehdi Amini]

> On Jul 30, 2015, at 3:46 PM, Eric Christopher <echristo at gmail.com> wrote:
> 
> 
> 
> On Thu, Jul 30, 2015 at 3:36 PM Philip Reames <listmail at philipreames.com <mailto: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”.

+1 for me.

Applying a strict policy on the current API while it currently mixes “binding-like” functionality with element of a stable API seems like a heavy constraint. I’d rather have an opt-in policy rather than opt-out.
Deprecating all the current C API in 3.8 and considering “unstable” after 3.9 seems reasonable and leave some time to opt-in what has to be stable after 3.9 (3.10 or 4.0? I don’t know the numbering policy).

— 
Mehdi



> 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 <mailto: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 list
>> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu>         http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/>
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150730/2e6ed39c/attachment.html>