[llvm-dev] [LLVMdev] [RFC] Developer Policy for LLVM C API

[deadal nix via llvm-dev]

Let's not get this die. The C API is too valuable to let this die.

I propose the following plan:
 - Add tests for the current API. This will allow to make sure that
everything works and would ensure that changes are made intentionally, nto
accidentally.
 - For area that do not exist in the C API right now, and for which support
seems needed, we establish a plan to support it according to current
functionality and planned evolution.
 - It is understood that the C API require more stability than the C++ one
as it is often used accross language boundary where type checking cannot be
done. On the other hand, no promise of stability is made so LLVM can still
evolve at "ludicrous speed". If a change to LLVM cannot be mapped to the
current API, the API is updated.

Deal ?

2015-08-17 16:50 GMT-07:00 deadal nix <deadalnix at gmail.com>:

>
>
> 2015-08-17 13:47 GMT-07:00 David Blaikie <dblaikie at gmail.com>:
>
>>
>>
>>
>>>
>>> I'd propose that the only 100% strict rule should be that if the ABI/API
>>> changes, it is done in a way that *loudly* breaks old programs -- e.g. they
>>> fail to compile, link, or run (depending on how the other-lang wrappers are
>>> accessing the API functions) -- not that you get some random weird
>>> misbehavior because a function's argument types or return type has been
>>> changed.
>>>
>>> Ideally, if you're going to remove an API, you'd deprecate it first, if
>>> you can see the problem coming. Otherwise, oh well -- it's not reasonable
>>> to hold up LLVM development to adhere to deprecation policy on the C API.
>>>
>>> That is:
>>> 1) Adding new functions for new LLVM functionality: great.
>>> 2) Removing old functions: if it's required -- after careful
>>> deliberation.
>>> 3) Modifying the signature of existing functions: no way.
>>>
>>> A couple of concrete examples:
>>>
>>> - Let's say you run out of space in an existing enum type (ahem,
>>> LLVMAttribute...).
>>>
>>> You should introduce new function names, taking a better type (perhaps
>>> some sort of set type, instead of a fixed-width integer...), mark the old
>>> ones deprecated so that users will update to the new functions. But, keep
>>> the old ones around so that old code can keep working. There's no real need
>>> to remove the old deprecated functions -- they'll keep working as well as
>>> they ever did with the smaller-valued attributes.
>>>
>>
>> But does it? What if the code is checking if two functions have the same
>> attributes (perhaps this is an invalid notion in the absence of information
>> about specific attributes) - if you compare the smaller-ranged attributes,
>> you might incorrectly conclude that these two functions have the same
>> attributes. Similarly for "no attributes specified" - you look at the enum,
>> see that none are set & conclude that it's a plain, uninteresting function
>> - so you create another plain, no-attributes function you think you can
>> make equivalent.
>>
>>
>
> The attribute situation is fairly symptomatic of the state of the C API.
> You have 2 person in this thread that tried to improve that part of the API
> but eventually gave up. You have more person in that thread saying they'd
> need it and have to do various workaround to get things done without it.
>
>
>
>>
>>> - Let's say you remove types from pointers.
>>>
>>> This is a change that can be seen coming up. So, one should fairly early
>>> on add an LLVMBuildGEP2 function that takes the extra type argument. Leave
>>> the old function name around for now (deprecated), because with the current
>>> state of LLVM, it can continue to work just fine.
>>>
>>> When LLVM is changed to *actually* remove all pointer types in its core,
>>> then the LLVMBuildGEP function cannot reasonably continue to exist. It
>>> simply cannot work, if pointers don't have types, and the type isn't
>>> provided. So, remove it.
>>>
>>
>> Yep, this is one we /might/ be able to manage - because we'll probably
>> have to keep typed pointer information around for old bitcode
>> deserialization. (but it does make the API awkward - when we finally do
>> remove LLVMBuildGEP, do we rename LLVMBuildGEP2? Do we leave it there? &
>> then we need LLVMBuildGEP3, etc, as things evolve?))
>>
>>
> LLVMBuildTypedGEP or something and we can be done with it. When The old
> way is not supported anymore, LLVMBuildGEP can be removed, and eventually
> recycled if the need arise.
>
>
>> Also this works for writing, but not for reading - if code was expecting
>> to read IR and assumed that pointers had types and bitcasts were present,
>> etc - it's going to have a Bad Time reading new IR... the APIs wouldn't
>> make any sense (there would be no getPointeeType on PointerType anymore -
>> there would be no Type that could be returned in response to that query)
>>
>> That's part of Eric's point, I think, once the API is low level enough,
>> it will churn with every change in LLVM or possible require some heroics to
>> avoid that churn which will slow down LLVM's API velocity (which is
>> somewhere around "ludicrous speed"), which is something we rather like. The
>> only way to make the C API more stable is to make it higher level (see
>> libLTO for an example) so that we can own the migration & shelter users
>> from it through that abstraction. If it's low level, it's going to churn or
>> slow us down (and probably both).
>>
>>
> Most of it won't move from one version to another. If something
> fundamental changes in LLVM from one version to the other, it is not a big
> deal to update the C API to reflect it. I do not think it is going to need
> anything heroic to keep it in place.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150818/9cb1f020/attachment.html>