> On Jul 20, 2015, at 1:45 PM, Eric Christopher <echristo at gmail.com> wrote: > > > > On Mon, Jul 20, 2015 at 1:37 PM Juergen Ributzka <juergen at apple.com <mailto:juergen at apple.com>> wrote: > Wow, this went of topic very quickly ;-) > > > It did. I am sorry about that :) > > 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. > > > 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" :) > > That said, here's how I see this happening if we were to go the direction I'm proposing: > > 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.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.> > I totally believe that existing clients could break through this and I want to minimize that as much as possible as it's our responsibility here. I think, in general, we've been stable enough in the existing C API to keep it going until we can define something that's actually stable that we can migrate clients to though. > > Thoughts? > > -eric > > > —Juergen > >> On Jul 20, 2015, at 1:08 PM, Eric Christopher <echristo at gmail.com <mailto:echristo at gmail.com>> wrote: >> > >>> >>> Part (most?) of the point of having a stable API is as a way of decoupling the development processes of two separate projects (modulo well-documented release-to-release updating). Requiring our users to add tests in our tree doesn't really achieve much decoupling. >> >> I’m not sure there is much “coupling” here. The point is that we expose a C API that is supposed to be stable but is not well tested. And some part of the C API is just a wrapper around the C++ and hasn’t really been designed to be “stable” in time. >> It seems also that we don’t really know what part of the C API really needs to be stable and is important for the users, so I read Pete’s proposal as “let’s collect the current use-cases and make them tests in LLVM, so that we define what is part of the stable C API and so that we won’t (inadvertently) break valid use cases". >> >> >> Yeah, this is just terrible though for all of the reasons I raised in my email and as you even say here "And some part of the C API is just a wrapper around the C++ and hasn’t really been designed to be “stable” in time." >> >> >> As of having this in-tree or out-of-tree, I’m not sure about that and there is a trade-off. >> >> >> I'm regretting ever saying "out of tree" here as I don't think it's the main issue, rather the splitting of the "bindings" style of api that we see a lot of in the C API directory and the more solid ones that we see from libclang and liblto. >> >> -eric > >> _______________________________________________ >> LLVM Developers mailing list >> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu> http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/> >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev> > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150720/f1782432/attachment.html>
> On Jul 20, 2015, at 2:24 PM, Jim Grosbach <grosbach at apple.com> wrote: > > >> On Jul 20, 2015, at 1:45 PM, Eric Christopher <echristo at gmail.com <mailto:echristo at gmail.com>> wrote: >> >> >> >> On Mon, Jul 20, 2015 at 1:37 PM Juergen Ributzka <juergen at apple.com <mailto:juergen at apple.com>> wrote: >> Wow, this went of topic very quickly ;-) >> >> >> It did. I am sorry about that :) >> >> 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. >> >> >> 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" :) >> >> That said, here's how I see this happening if we were to go the direction I'm proposing: >> >> 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. > > 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.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.> >> >> I totally believe that existing clients could break through this and I want to minimize that as much as possible as it's our responsibility here. I think, in general, we've been stable enough in the existing C API to keep it going until we can define something that's actually stable that we can migrate clients to though. >> >> Thoughts? >> >> -eric >> >> >> —Juergen >> >>> On Jul 20, 2015, at 1:08 PM, Eric Christopher <echristo at gmail.com <mailto:echristo at gmail.com>> wrote: >>> >> >>>> >>>> Part (most?) of the point of having a stable API is as a way of decoupling the development processes of two separate projects (modulo well-documented release-to-release updating). Requiring our users to add tests in our tree doesn't really achieve much decoupling. >>> >>> I’m not sure there is much “coupling” here. The point is that we expose a C API that is supposed to be stable but is not well tested. And some part of the C API is just a wrapper around the C++ and hasn’t really been designed to be “stable” in time. >>> It seems also that we don’t really know what part of the C API really needs to be stable and is important for the users, so I read Pete’s proposal as “let’s collect the current use-cases and make them tests in LLVM, so that we define what is part of the stable C API and so that we won’t (inadvertently) break valid use cases". >>> >>> >>> Yeah, this is just terrible though for all of the reasons I raised in my email and as you even say here "And some part of the C API is just a wrapper around the C++ and hasn’t really been designed to be “stable” in time." >>> >>> >>> As of having this in-tree or out-of-tree, I’m not sure about that and there is a trade-off. >>> >>> >>> I'm regretting ever saying "out of tree" here as I don't think it's the main issue, rather the splitting of the "bindings" style of api that we see a lot of in the C API directory and the more solid ones that we see from libclang and liblto. >>> >>> -eric >> >>> _______________________________________________ >>> LLVM Developers mailing list >>> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu> http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/> >>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev> >> _______________________________________________ >> LLVM Developers mailing list >> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu> http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/> >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev> >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150720/656d533d/attachment.html>
On Mon, Jul 20, 2015 at 3:20 PM Jim Grosbach <grosbach at apple.com> wrote:> On Jul 20, 2015, at 2:24 PM, Jim Grosbach <grosbach at apple.com> wrote: > > > On Jul 20, 2015, at 1:45 PM, Eric Christopher <echristo at gmail.com> wrote: > > > > On Mon, Jul 20, 2015 at 1:37 PM Juergen Ributzka <juergen at apple.com> > wrote: > >> Wow, this went of topic very quickly ;-) >> >> > It did. I am sorry about that :) > > >> 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. >> >> > 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" :) > > That said, here's how I see this happening if we were to go the direction > I'm proposing: > > 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. > > > 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. > > > 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. > >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 :) 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". -eric> > I totally believe that existing clients could break through this and I > want to minimize that as much as possible as it's our responsibility here. > I think, in general, we've been stable enough in the existing C API to keep > it going until we can define something that's actually stable that we can > migrate clients to though. > > Thoughts? > > -eric > > > >> —Juergen >> >> On Jul 20, 2015, at 1:08 PM, Eric Christopher <echristo at gmail.com> wrote: >> >> >>> Part (most?) of the point of having a stable API is as a way of >>> decoupling the development processes of two separate projects (modulo >>> well-documented release-to-release updating). Requiring our users to add >>> tests in our tree doesn't really achieve much decoupling. >>> >>> >>> I’m not sure there is much “coupling” here. The point is that we expose >>> a C API that is supposed to be stable but is not well tested. And some part >>> of the C API is just a wrapper around the C++ and hasn’t really been >>> designed to be “stable” in time. >>> It seems also that we don’t really know what part of the C API really >>> needs to be stable and is important for the users, so I read Pete’s >>> proposal as “let’s collect the current use-cases and make them tests in >>> LLVM, so that we define what is part of the stable C API and so that we >>> won’t (inadvertently) break valid use cases". >>> >>> >> Yeah, this is just terrible though for all of the reasons I raised in my >> email and as you even say here "And some part of the C API is just a >> wrapper around the C++ and hasn’t really been designed to be “stable” in >> time." >> >> >>> >>> As of having this in-tree or out-of-tree, I’m not sure about that and >>> there is a trade-off. >>> >>> >> I'm regretting ever saying "out of tree" here as I don't think it's the >> main issue, rather the splitting of the "bindings" style of api that we see >> a lot of in the C API directory and the more solid ones that we see from >> libclang and liblto. >> >> -eric >> >> _______________________________________________ >> LLVM Developers mailing list >> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >> >> _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev > > >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150720/f63ecf0b/attachment.html>