<div dir="ltr">As someone who used the LLVM C API for an experiment back in 2009ish (porting the SBCL lisp compiler to target LLVM as a backend -- never finished), I thought it was great that LLVM provided the C API. I was sad that it wasn't properly updated to include support for all the newly introduced IR features, though. (E.g. atomics). I tried to send patches for some of that stuff a while later, but didn't manage to get it in. (I wasn't active in llvm at that point, I was just trying to contribute a patch. I gave up.).<div><br></div><div>It doesn't make sense to me to have the C API be less than a full wrapping of the IR building functions. Having less than that, you almost might as well not have it at all. (Which would be sad.)<div><div><br></div><div>I'd like suggest that the most important thing for the C API is NOT a 100% promise of eternal compatibility, but to _strive_ for compatibility, as much as is realistically possible. If it's not possible, oh well. We're not talking about libc here, so the costs of changing it incompatibly -- with careful deliberation -- are not impossibly huge. I mean, even libstdc++ changes its ABI occassionally! LLVM's C API certainly shouldn't be considered more important to keep stable than libstdc++!</div><div><br></div><div>That said, incompatible changes ought not be made just for trivial reasons: they should be made when there's a true need, e.g. when an existing LLVM-C function cannot sensibly maintain its existing behavior anymore because the underlying functionality of LLVM was removed, or drastically changed.</div><div><br></div><div>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.</div><div><br></div><div>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.<br></div><div><br></div></div></div><div>That is:</div><div>1) Adding new functions for new LLVM functionality: great.</div><div>2) Removing old functions: if it's required -- after careful deliberation.</div><div>3) Modifying the signature of existing functions: no way.</div><div><br></div><div>A couple of concrete examples:</div><div><br></div><div>- Let's say you run out of space in an existing enum type (ahem, LLVMAttribute...).</div><div><br></div><div>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.</div><div><br></div><div>- Let's say you remove types from pointers.</div><div><br>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.</div><div><br></div><div>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.</div><div><br></div><div>Preferably, there would be a release of LLVM in between with both functions available to let people have some time to adjust, but if not, oh well.</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Aug 17, 2015 at 1:28 PM, deadal nix via llvm-dev <span dir="ltr"><<a href="mailto:llvm-dev@lists.llvm.org" target="_blank">llvm-dev@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">2015-08-17 8:34 GMT-07:00 Reid Kleckner <span dir="ltr"><<a href="mailto:rnk@google.com" target="_blank">rnk@google.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><span>On Sun, Aug 16, 2015 at 10:34 PM, deadal nix via llvm-dev <span dir="ltr"><<a href="mailto:llvm-dev@lists.llvm.org" target="_blank">llvm-dev@lists.llvm.org</a>></span> wrote:<br></span><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div class="gmail_extra"><br><div class="gmail_quote"><span>2015-08-16 21:51 GMT-07:00 Eric Christopher <span dir="ltr"><<a href="mailto:echristo@gmail.com" target="_blank">echristo@gmail.com</a>></span>:</span><span><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div>The promise of stability. We don't promise that the C++ API will stay stable.</div></div></div>
</blockquote></span></div><br><br></div></div></div><span><div class="gmail_extra">Why was that promise be made in the first place ? Has it been made in the first place ?<br></div></span></div></blockquote><div><br></div><div>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. :)</div><div><br></div><div>There are really three goals here: flexibility to change LLVM IR, completeness of the C API, and stability of the C API. Pick two.</div><div><br></div></div></div></div></blockquote><div><br></div></span><div>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.<br><br></div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></div><div>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.</div><div><br></div></div></div></div></blockquote><div><br></div></span><div>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 <br><br></div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></div><div>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.</div><div><br></div></div></div></div></blockquote><div><br></div></span><div>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.<br><br></div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></div><div>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.</div></div></div></div>
</blockquote></span></div><br></div><div class="gmail_extra">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 :<br></div><div class="gmail_extra"> - It was not possible to set the personality function from C, which is a problem for many frontends.<br></div><div class="gmail_extra"> - In other languages, as mangling remained the same, the thing compiles and fail randomly at runtime.<br><br></div><div class="gmail_extra">This need to be avoided as much as possible. I'd propose the following policy :<br></div><div class="gmail_extra">1/ Do change the IR as per need of LLVM development. The C API must not prevent LLVM to move forward.<br></div><div class="gmail_extra">2/ If the change can be mapped nicely without changing the C API, then do that.<br></div><div class="gmail_extra">3/ If there is no way to map it nicely, then update the C API.<br><br></div><div class="gmail_extra">For instance, the pointer update work would probably be a valid reason to go with 3/ .<br></div><div class="gmail_extra"><br></div><div class="gmail_extra">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 loads/stores.<br></div><div class="gmail_extra"><br></div><div class="gmail_extra">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 thing.<br></div></div>
<br>_______________________________________________<br>
LLVM Developers mailing list<br>
<a href="mailto:llvm-dev@lists.llvm.org">llvm-dev@lists.llvm.org</a>         <a href="http://llvm.cs.uiuc.edu" rel="noreferrer" target="_blank">http://llvm.cs.uiuc.edu</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev</a><br>
<br></blockquote></div><br></div>