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

Wed Jul 29 15:45:20 PDT 2015

On Wed, Jul 29, 2015 at 3:28 PM, Eric Christopher <echristo at gmail.com>
wrote:

>
>
> On Mon, Jul 20, 2015 at 4:12 PM Juergen Ributzka <juergen at apple.com>
> wrote:
>
>> I also misunderstood your original transition proposal in this point. I
>> agree with Jim that we should keep the current C-API where it is and have a
>> separate location for the bindings. I envision that we will need the
>> current C-API and the new stable C-API to overlap for at least one release
>> cycle to allow a smooth transition without breaking all the clients out
>> there. Some clients only read the release notes, so this process will take
>> some time.
>>
>>
> I can see that, I don't really agree, but I can see the point. My idea was
> expanding the existing C API in the current place with no guarantees on it
> but we don't really change it much right? and then add a stable C API
> somewhere else as we design a good one. Basically status quo is that after
> a cycle or two the existing C API in the current location becomes unstable
> and any stable C API that comes up can be put into a new stable location. I
> don't see changing the existing C API (i.e. keep the current status quo on
> the existing directory of API) for the next release cycle at least and we
> can even put a README in the C API directory to state the policy for the
> directory going forward.
>
> This seems to keep things working for the longest time, we can provide a
> release note warning that the C API directory is going to be unstable in X
> release and expand the current directory. This means that current users of
> it in a bindings sort of way (honestly most users) won't have to migrate
> and that users that care deeply about stability can migrate to the new APIs
> as they make it in tree.
>
> Does this make sense? Are there any problems with this?
>

Jim's idea of keeping the current one as the stable one (since those users
are least amenable to changing their library, etc) seems like a good idea
to me, naively speaking. But my guess is that no one will ever actually sit
down & design a 'real' stable API here & we'll continue to play the same
games of making vague guesses at what things we can bake it - and sometimes
regret it & break the API in some way (either semantically (see old JIT
APIs that are now noops) or syntactically).

If the existing one already has a fuzzy implicit contract that some things
in there aren't /really/ stable - then we can easily rip those out & move
them into a proper unstable API?

just my 0.5c,

- Dave

>
>
>> I added an initial patch for discussion. There is one point I am not sure
>> about yet. You mentioned that existing API implementations might become
>> NOOPS. I agree that this is a viable and sometimes necessary path, but what
>> are the limitations for this? Which APIs can be safely converted to NOOPs?
>>
>>
> It depends on whether or not we're talking about functionality stability
> or existence stability. If we're talking about functionality stability the
> answer is "only if something else is already doing the work", otherwise
> "any time the api doesn't make sense any more but we want to keep stability"
>
> -eric
>
>
>> —Juergen
>>
>>
>>
>> On Jul 20, 2015, at 3:26 PM, Eric Christopher <echristo at gmail.com> wrote:
>>
>> On Mon, Jul 20, 2015 at 3:20 PM Jim Grosbach <grosbach at apple.com> wrote:
>>
>>> On Jul 20, 2015, at 2:24 PM, Jim Grosbach <grosbach at apple.com> wrote:
>>>
>>>
>>> On Jul 20, 2015, at 1:45 PM, Eric Christopher <echristo at gmail.com>
>>> wrote:
>>>
>>>
>>>
>>> On Mon, Jul 20, 2015 at 1:37 PM Juergen Ributzka <juergen at apple.com>
>>> wrote:
>>>
>>>> Wow, this went of topic very quickly ;-)
>>>>
>>>>
>>> It did. I am sorry about that :)
>>>
>>>
>>>> As you know I am very interested in an stable API (C and/or C++) for
>>>> LLVM, but maybe we should discuss this in a separate thread. Designing a
>>>> good stable API from scratch will take some time and until that point I
>>>> want to document our current “tribal knowledge”. I will post a patch as you
>>>> suggested.
>>>>
>>>>
>>> Thanks. Given the direction it's taken and the positive feedback I've
>>> gotten on the existing C API we might want to document it as "in flux" :)
>>>
>>> That said, here's how I see this happening if we were to go the
>>> direction I'm proposing:
>>>
>>> I think we should bite the bullet and say that the growth we've had in
>>> the C API is past what we were originally promising and just call the
>>> existing C API the "bindings" api. From there we can move the LTO headers
>>> to a new directory (insert bikeshed) and say that the existing code in
>>> llvm-c isn't stable.  We can then migrate the things we want to be stable
>>> into a new directory with real stability guarantees. I'm seeing an API
>>> (possibly versioned) with a much lower surface area here similar, possibly,
>>> to the LTO stuff or libclang.
>>>
>>>
>>> I’d prefer to do it the other way around. Make the new directory be for
>>> the bindings stuff. That way anything that works with what’s there as-is
>>> continues to do so. Any clients that need to move to the bindings API as we
>>> then work through deprecating things and otherwise cleaning up the stable
>>> API will be the ones that by definition want to opt-in to a less stable API
>>> and are thus more amenable to change. Changes for clients that are using
>>> the current API as a stable API will continue to work and will get the
>>> advance notice and transition planning from the deprecation process. If we
>>> make the stable API be in a new directory, that’s a build-time breaker
>>> right there for every client using the stable API. Let’s avoid that.
>>>
>>>
>>> To clarify (I hope), what I care about here is that there is a clean
>>> migration path from the current structure to whatever new structure (and
>>> accordant API) we have. IMO, that’s easiest if we leave the current headers
>>> where they are and deprecate like crazy, but there are other ways (leaving
>>> behind copies w/ the entire file marked deprecated, e.g.). So long as
>>> there’s a migration path that doesn’t involve a hard break where clients
>>> are just screwed from one revision to the next, we should be fine.
>>>
>>>
>> Totally in agreement here. I'm actually trying to minimize disruption for
>> the most people. My original thought was more of a "tell people what's
>> going on and do a slow degradation". I.e. leave the current C API where it
>> is, keep expanding it for the bindings folks and let people willing to take
>> a chance on the code not breaking just continue on while the stable API
>> folk add one and migrate users to it (the process of which I'm sure will
>> help define what a decent API should be :)
>>
>> I'm not too invested in how we get from a to b, it was mostly a "let's
>> try to minimize total code changes for everyone".
>>
>> -eric
>>
>>
>>
> _______________________________________________
> 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/20150729/3bcf7ff7/attachment.html>