[llvm-dev] An Update on the C API

[Eric Christopher via llvm-dev]

"Documentation:

We’re going to document this policy in the developer documentation. In
addition, any changes to the C API will require documentation in the
release notes so that it’s clear to external users who do not follow the
project how the C API is changing and evolving."

So, yes?

-eric

On Thu, Nov 19, 2015 at 5:55 PM Sean Silva <chisophugis at gmail.com> wrote:

> Are you going to propagate this info into
> http://llvm.org/docs/DeveloperPolicy.html ?
>
> On Thu, Nov 19, 2015 at 1:56 PM, Eric Christopher via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>
>>
>> Hi All,
>>
>> I wanted to send a follow-up mail to the C API discussion/BoF that we had
>> at the latest developer meeting and nicely hosted by Justin and Juergen.
>>
>> We were able to reach consensus on a number of questions/concerns about
>> the C API so I’m going to go ahead and list them for posterity and for any
>> further discussion here:
>>
>> Stability Guarantees:
>>
>> The C API is, in general, a “best effort” for stability. This means that
>> we’ll make every attempt to keep the C API stable, but that stability will
>> be limited by the abstractness of the interface and the stability of the
>> C++ API that it wraps. In practice, this means that things like “create
>> debug info” or “create this type of instruction” is likely to be less
>> stable than “take this IR file and JIT it for my current machine”.
>> Release stability:
>> We won’t break the C API on the release branch with patches that go on
>> that branch - in general.
>> Exception: If we fix an unintentional C API break that will keep us
>> consistent with both the previous and next release.
>>
>> Including new things into the API:
>>
>> We’re going to adopt a policy of “if a particular LLVM subcomponent has a
>> C API already included, then expanding that API is acceptable”, but we’re
>> also going to institute a better policy of “please test the API that you’ve
>> just expanded”. Hopefully this will get the C API better tested as time
>> goes on to remove accidental breakage so that any time we break the C API
>> we know about it.
>>
>> Adding C API for subcomponents that don’t currently have one is also
>> fine, and the details of how best to do that should be discussed on the
>> mailing list as they come up.
>>
>> Documentation:
>>
>> We’re going to document this policy in the developer documentation. In
>> addition, any changes to the C API will require documentation in the
>> release notes so that it’s clear to external users who do not follow the
>> project how the C API is changing and evolving.
>>
>> What we expect this means in practice is that APIs like libLTO and other
>> APIs based on reading IR are going to remain highly stable and that more
>> wrapper like APIs (IR creation, etc) are going to both be added and change
>> as the underlying IR changes.
>>
>> Please feel free to follow up to this thread with any concerns.
>>
>> Thanks!
>>
>> -eric (with Justin and Juergen)
>>
>>
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20151120/89c58cd8/attachment.html>