Sam Elliott via llvm-dev
2020-Jul-23 11:57 UTC
[llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?
Something that would be good to get clarity on: The RISC-V backend recently had a bugfix patch that got backported to the 10.0.1 branch. The original patch introduced a new virtual method in TargetLowering.h, and the backported patch [1] was rewritten to avoid changing the ABI of libLLVM.so. This feels like some kind of policy decision about the C++ ABI beyond "it's entirely unstable" - though I understand we may not want to commit to doing this for every backported bug fix. It would be good to understand where this line is, if we're going to clarify the documentation. Sam [1]: https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f> On 23 Jul 2020, at 4:52 am, Chris Lattner via llvm-dev <llvm-dev at lists.llvm.org> wrote: > > This sounds reasonable to me, I am generally +1 on documenting things that are well known but not written down. > > Thanks Varun! > > -Chris > >> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >> >> The Developer Policy document (https://llvm.org/docs/DeveloperPolicy.html <https://llvm.org/docs/DeveloperPolicy.html>) contains a Section "C API Changes". There is no corresponding section for C++ API Changes. LLVM is somewhat different from most libraries in that the main language is C++ but the C++ API is not guaranteed to be stable in any shape or form from what I understand. >> >> I think it would be useful to have a "C++ API Changes" section to Developer Policy spelling this out. Copying the style of the C API Changes section, it could look something like: >> >> --- >> C++ API Changes >> >> * Stability Guarantees: The C++ API is does not guarantee any stability. Changes may be made without any notice about deprecation and alternate APIs for the same functionality may not be included. Downstream projects using the C++ API are expected to keep up with changes. >> * Release stability: The C++ API does not make any stability guarantees for the release branch. >> * Testing: Patches to the C++ API are expected to come with tests just like any other patch. >> * Including new things into the API: [TODO: I'm not sure what should go here]. >> * Documentation: Changes to the C++ API are not expected to be documented in the release notes. >> --- >> >> Clang does have a page with information about its own C++ API (https://clang.llvm.org/docs/Tooling.html <https://clang.llvm.org/docs/Tooling.html>) which is more informative, but I think it would useful to have this information on the Developer Policy page for the whole of LLVM. >> >> Does this addition sound reasonable? >> >> Varun >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev > > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev-- Sam Elliott Software Team Lead Senior Software Developer - LLVM and OpenTitan lowRISC CIC -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200723/7f2b7e9c/attachment.html>
David Chisnall via llvm-dev
2020-Jul-23 14:13 UTC
[llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?
I believe the policy is to provide ABI stability across the patch releases so that any downstream distribution that ships LLVM X can also ship LLVM X.0.Y and pick up bug fixes. There is no stability guarantee even at the source level between LLVM X and LLVM X+1, though where possible it's considered polite to deprecate things and provide a migration path. In practice, quite a lot of LLVM now has backwards API (source) compatibility across versions but still retains the option of breaking this in any release. David On 23/07/2020 12:57, Sam Elliott via llvm-dev wrote:> Something that would be good to get clarity on: > > The RISC-V backend recently had a bugfix patch that got backported to > the 10.0.1 branch. The original patch introduced a new virtual method in > TargetLowering.h, and the backported patch [1] was rewritten to avoid > changing the ABI of libLLVM.so. > > This feels like some kind of policy decision about the C++ ABI beyond > "it's entirely unstable" - though I understand we may not want to commit > to doing this for every backported bug fix. > > It would be good to understand where this line is, if we're going to > clarify the documentation. > > Sam > > [1]: > https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f > <https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f> > >> On 23 Jul 2020, at 4:52 am, Chris Lattner via llvm-dev >> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >> >> This sounds reasonable to me, I am generally +1 on documenting things >> that are well known but not written down. >> >> Thanks Varun! >> >> -Chris >> >>> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev >>> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >>> >>> The Developer Policy document >>> (https://llvm.org/docs/DeveloperPolicy.html >>> <https://llvm.org/docs/DeveloperPolicy.html>) contains a Section "C >>> API Changes". There is no corresponding section for C++ API Changes. >>> LLVM is somewhat different from most libraries in that the main >>> language is C++ but the C++ API is not guaranteed to be stable in any >>> shape or form from what I understand. >>> >>> I think it would be useful to have a "C++ API Changes" section to >>> Developer Policy spelling this out. Copying the style of the C API >>> Changes section, it could look something like: >>> >>> --- >>> C++ API Changes >>> >>> * Stability Guarantees: The C++ API is does not guarantee any >>> stability. Changes may be made without any notice about deprecation >>> and alternate APIs for the same functionality may not be included. >>> Downstream projects using the C++ API are expected to keep up with >>> changes. >>> * Release stability: The C++ API does not make any stability >>> guarantees for the release branch. >>> * Testing: Patches to the C++ API are expected to come with tests >>> justlike any other patch. >>> * Including new things into the API: [TODO: I'm not sure what should >>> go here]. >>> * Documentation: Changes to the C++ API are not expected to be >>> documented in the release notes. >>> --- >>> >>> Clang does have a page with information about its own C++ API >>> (https://clang.llvm.org/docs/Tooling.html >>> <https://clang.llvm.org/docs/Tooling.html>) which is more >>> informative, but I think it would useful to have this information on >>> the Developer Policy page for the whole of LLVM. >>> >>> Does this addition sound reasonable? >>> >>> Varun >>> _______________________________________________ >>> LLVM Developers mailing list >>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> >>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >>> <https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev> >> >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev > > -- > Sam Elliott > Software Team Lead > Senior Software Developer - LLVM and OpenTitan > lowRISC CIC > > > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >
Hal Finkel via llvm-dev
2020-Jul-23 15:23 UTC
[llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?
On 7/23/20 9:13 AM, David Chisnall via llvm-dev wrote:> I believe the policy is to provide ABI stability across the patch > releases so that any downstream distribution that ships LLVM X can > also ship LLVM X.0.Y and pick up bug fixes. There is no stability > guarantee even at the source level between LLVM X and LLVM X+1, though > where possible it's considered polite to deprecate things and provide > a migration path. In practice, quite a lot of LLVM now has backwards > API (source) compatibility across versions but still retains the > option of breaking this in any release. > > DavidThis is also my understanding. We maintain ABI stability across patch releases. -Hal> > On 23/07/2020 12:57, Sam Elliott via llvm-dev wrote: >> Something that would be good to get clarity on: >> >> The RISC-V backend recently had a bugfix patch that got backported to >> the 10.0.1 branch. The original patch introduced a new virtual method >> in TargetLowering.h, and the backported patch [1] was rewritten to >> avoid changing the ABI of libLLVM.so. >> >> This feels like some kind of policy decision about the C++ ABI beyond >> "it's entirely unstable" - though I understand we may not want to >> commit to doing this for every backported bug fix. >> >> It would be good to understand where this line is, if we're going to >> clarify the documentation. >> >> Sam >> >> [1]: >> https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f >> <https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f> >> >> >>> On 23 Jul 2020, at 4:52 am, Chris Lattner via llvm-dev >>> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >>> >>> This sounds reasonable to me, I am generally +1 on documenting >>> things that are well known but not written down. >>> >>> Thanks Varun! >>> >>> -Chris >>> >>>> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev >>>> <llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote: >>>> >>>> The Developer Policy document >>>> (https://llvm.org/docs/DeveloperPolicy.html >>>> <https://llvm.org/docs/DeveloperPolicy.html>) contains a Section "C >>>> API Changes". There is no corresponding section for C++ API >>>> Changes. LLVM is somewhat different from most libraries in that the >>>> main language is C++ but the C++ API is not guaranteed to be stable >>>> in any shape or form from what I understand. >>>> >>>> I think it would be useful to have a "C++ API Changes" section to >>>> Developer Policy spelling this out. Copying the style of the C API >>>> Changes section, it could look something like: >>>> >>>> --- >>>> C++ API Changes >>>> >>>> * Stability Guarantees: The C++ API is does not guarantee any >>>> stability. Changes may be made without any notice about deprecation >>>> and alternate APIs for the same functionality may not be included. >>>> Downstream projects using the C++ API are expected to keep up with >>>> changes. >>>> * Release stability: The C++ API does not make any stability >>>> guarantees for the release branch. >>>> * Testing: Patches to the C++ API are expected to come with tests >>>> justlike any other patch. >>>> * Including new things into the API: [TODO: I'm not sure what >>>> should go here]. >>>> * Documentation: Changes to the C++ API are not expected to be >>>> documented in the release notes. >>>> --- >>>> >>>> Clang does have a page with information about its own C++ API >>>> (https://clang.llvm.org/docs/Tooling.html >>>> <https://clang.llvm.org/docs/Tooling.html>) which is more >>>> informative, but I think it would useful to have this information >>>> on the Developer Policy page for the whole of LLVM. >>>> >>>> Does this addition sound reasonable? >>>> >>>> Varun >>>> _______________________________________________ >>>> LLVM Developers mailing list >>>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> >>>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >>>> <https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev> >>> >>> _______________________________________________ >>> LLVM Developers mailing list >>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org> >>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >> >> -- >> Sam Elliott >> Software Team Lead >> Senior Software Developer - LLVM and OpenTitan >> lowRISC CIC >> >> >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >> > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev-- Hal Finkel Lead, Compiler Technology and Programming Languages Leadership Computing Facility Argonne National Laboratory