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

[Philip Reames]

On 07/30/2015 03:46 PM, Eric Christopher 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".
I have no real objection to this, but I am also not a consumer of the 
existing C API.  I think this is a big enough change that we'd need to 
make sure this got widely disseminated via a top-level RFC email, LLVM 
Weekly, and the release notes.
> 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".
I'm having a hard time parsing this paragraph.  Specifically "expand" 
what?  and which API is transitioning?  If I'm reading the rest of your 
proposal right, we effectively won't have *any* stable API in tree after 
the current one is downgraded to "unstable C binding".  What did I miss?
>
> -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://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150731/4bab7018/attachment.html>