<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Wed, Jul 29, 2015 at 3:45 PM David Blaikie <<a href="mailto:dblaikie@gmail.com">dblaikie@gmail.com</a>> wrote:<br></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">On Wed, Jul 29, 2015 at 3:28 PM, Eric Christopher <span dir="ltr"><<a href="mailto:echristo@gmail.com" target="_blank">echristo@gmail.com</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><br><div class="gmail_quote"><span><div dir="ltr">On Mon, Jul 20, 2015 at 4:12 PM Juergen Ributzka <<a href="mailto:juergen@apple.com" target="_blank">juergen@apple.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word">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.<div><br></div></div></blockquote><div><br></div></span><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Does this make sense? Are there any problems with this?</div></div></div></blockquote><div><br></div></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div>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).<br><br></div></div></div></div></blockquote><div> </div><div>I don't think that this is going to work for what Jim's been suggesting as far as leaving the C API in place since some of what we'd remove are things like thin wrappers around C++ API functions that I'm sure are being used for things like IR creation. In general, these things have been pretty stable and I don't actually expect that to change, but if we want to open up things like debug info and most of the rest of the APIs then we'll want to do so. Having all of our internal enums and APIs exposed via the existing C API is going to make it fairly hard to work with as the surface area expands. Ultimately I think it's hard to draw the line with the existing API.</div><div> <br></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>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?<br><br></div></div></div></div></blockquote><div><br></div><div>Given that just about the entire API is simply a wrapper around C++ the entire thing fits under the "proper unstable API" aspect. But in general we could probably define anything that looks like unwrap(thing)->call() as an "unstable" API perhaps? This might be overly broad, but it's a starting point for discussion?</div><div><br></div><div>-eric</div><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>just my 0.5c,<br><br>- Dave</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"></blockquote></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><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"><span><div> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div></div><div>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?</div></div><div style="word-wrap:break-word"><div><br></div></div></blockquote><div><br></div></span><div>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"</div><div><br></div><div>-eric</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div></div><div>—Juergen</div><div><br></div><div></div></div><span><div style="word-wrap:break-word"><div> </div><div><br></div><div><div><blockquote type="cite"><div>On Jul 20, 2015, at 3:26 PM, Eric Christopher <<a href="mailto:echristo@gmail.com" target="_blank">echristo@gmail.com</a>> wrote:</div><br><div><div dir="ltr" style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">On Mon, Jul 20, 2015 at 3:20 PM Jim Grosbach <<a href="mailto:grosbach@apple.com" target="_blank">grosbach@apple.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div><blockquote type="cite"><div>On Jul 20, 2015, at 2:24 PM, Jim Grosbach <<a href="mailto:grosbach@apple.com" target="_blank">grosbach@apple.com</a>> wrote:</div><br><div><div style="word-wrap:break-word"><br><div><blockquote type="cite"><div>On Jul 20, 2015, at 1:45 PM, Eric Christopher <<a href="mailto:echristo@gmail.com" target="_blank">echristo@gmail.com</a>> wrote:</div><br><div><div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Mon, Jul 20, 2015 at 1:37 PM Juergen Ributzka <<a href="mailto:juergen@apple.com" target="_blank">juergen@apple.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word">Wow, this went of topic very quickly ;-)<div><br></div></div></blockquote><div><br></div><div>It did. I am sorry about that :)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div></div><div>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.</div></div><div style="word-wrap:break-word"><div><br></div></div></blockquote><div><br></div><div>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" :)</div><div><br></div><div>That said, here's how I see this happening if we were to go the direction I'm proposing:</div><div><br></div><div>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.<br></div></div></div></div></blockquote><div><br></div><div>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.</div></div></div></div></blockquote><div><br></div></div></div><div style="word-wrap:break-word"><div><div>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.</div></div></div><div style="word-wrap:break-word"><div><br></div></div></blockquote><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><br></div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">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 :)</div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"><br></div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">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".</div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px"> </div><div style="font-family:Helvetica;font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px">-eric</div></div></blockquote></div><br></div></div></span></blockquote></div></div>
<br></blockquote></div></div></div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">_______________________________________________<br>
LLVM Developers mailing list<br>
<a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" rel="noreferrer" target="_blank">http://llvm.cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" rel="noreferrer" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
<br></blockquote></div></div></div></blockquote></div></div>