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

deadal nix via llvm-dev llvm-dev at lists.llvm.org
Mon Aug 17 10:28:30 PDT 2015

2015-08-17 8:34 GMT-07:00 Reid Kleckner <rnk at google.com>:

> On Sun, Aug 16, 2015 at 10:34 PM, deadal nix via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>> 2015-08-16 21:51 GMT-07:00 Eric Christopher <echristo at gmail.com>:
>>> The promise of stability. We don't promise that the C++ API will stay
>>> stable.
>> Why was that promise be made in the first place ? Has it been made in the
>> first place ?
> It sounds like you're in favor of dropping C API stability then, if it's
> holding us back? That feedback is actually really helpful. :)
> There are really three goals here: flexibility to change LLVM IR,
> completeness of the C API, and stability of the C API. Pick two.
Yes but these aren't black and white IMO. These are need in tension, sure,
but all API have these kind of problem not specifically the C API.

> The goals are mutually incompatible and we have to trade off one for the
> other. Most of the LLVM core developers value goal #1, the ability to
> change the IR. Look at the pointee type changes that David Blaikie is
> working on, and the new EH representation. If we promise both stability and
> completeness, these things are impossible.
Yes I was actually thinking about that. This is the kind of change that
justify a change in the C API IMO. We should try our best to keep the C API
stable, but if somethign fundamental changes in LLVM, and that there is no
nice way to map it to the old API, then

> One way forward is to guarantee stability, but limit completeness. This
> would mean limiting the C API to constructs that will always and forever be
> easily represented in LLVM.
That would be a problem for me. It seems like other in this thread
mentioned the incompleteness of the C API as a problem for them and
mentioned the use of various hacks to work around it. On my side I tried to
propose diff to increase completeness of the C API in the past, but the
review process was frankly too painful and I mostly give up. I'd be up for
being a maintainer of the C API if that is needed.

> The other choice is to forget stability and wrap the C++ API completely,
> potentially with something auto-generated. We could make a more limited
> stability promise along the lines of "these APIs will be updated to reflect
> changes to the IR, and are otherwise stable." I think everyone would be
> fine with that.

I do not think this is a good idea. The C API is used a lot to use LLVM
from other languages than C++ . When used directly from C, you get function
signature, but when used from other languages, changing method randomly
cause undefined behavior. For instance, the landing pad instruction was
changed recently and the C API to create a landing pad was updated. As a
result, 2 thing happened :
 - It was not possible to set the personality function from C, which is a
problem for many frontends.
 - In other languages, as mangling remained the same, the thing compiles
and fail randomly at runtime.

This need to be avoided as much as possible. I'd propose the following
policy :
1/ Do change the IR as per need of LLVM development. The C API must not
prevent LLVM to move forward.
2/ If the change can be mapped nicely without changing the C API, then do
3/ If there is no way to map it nicely, then update the C API.

For instance, the pointer update work would probably be a valid reason to
go with 3/ .

Right now, as far as I'm concerned, the main limitation of the C API are
the capability to set attributes and the capability to use atomic

In any ways, I do think the patch adding tests for existing API should be
merged. The need for test for the C API was mentioned various times in this
thread and I do think that whatever the road taken, having test is a good
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150817/b99a433d/attachment.html>

More information about the llvm-dev mailing list