| Message ID | 1490882336-13721-1-git-send-email-petri.savolainen@linaro.org |
|---|---|
| Headers | show |
| Series | Deprecated macros | expand |
Ping. > -----Original Message----- > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of Petri > Savolainen > Sent: Thursday, March 30, 2017 4:59 PM > To: lng-odp@lists.linaro.org > Subject: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) with > compiler independent mechanism to control if deprecated API definitions > are > visible to the application. ODP_DEPRECATED_API can be used both in > application > and implementation to check if deprecated APIs are enabled. By default > those are > disabled. Implementation may optimize the normal (new API) code path. > > ODP_DEPRECATE() macro is used to rename definitions, so that data > structure > sizes are equal on both options. This enables implementation to serve both > options with a single library (if it wishes to do so). > > > Petri Savolainen (4): > api: hints: remove ODP_DEPRECATED from API > api: deprecated: add configure option and macros > test: crypto: remove references to deprecated crypto apis > api: crypto: enforce deprecated API status > > configure.ac | 19 +++++++- > doc/application-api-guide/api_guide_lines.dox | 6 +-- > doc/platform-api-guide/Doxyfile | 1 + > doc/process-guide/release-guide.adoc | 6 +-- > example/ipsec/odp_ipsec_misc.h | 4 +- > example/ipsec/odp_ipsec_sa_db.c | 4 +- > example/ipsec/odp_ipsec_stream.c | 6 +-- > include/odp/api/spec/.gitignore | 1 + > include/odp/api/spec/crypto.h | 29 +++++++------ > include/odp/api/spec/deprecated.h.in | 50 > ++++++++++++++++++++++ > include/odp/api/spec/hints.h | 6 --- > include/odp_api.h | 1 + > platform/Makefile.inc | 1 + > platform/linux-generic/Makefile.am | 1 + > .../linux-generic/include/odp/api/deprecated.h | 26 +++++++++++ > platform/linux-generic/odp_crypto.c | 45 +++++++++++++---- > -- > test/common_plat/performance/odp_crypto.c | 4 +- > 17 files changed, 161 insertions(+), 49 deletions(-) > create mode 100644 include/odp/api/spec/deprecated.h.in > create mode 100644 platform/linux-generic/include/odp/api/deprecated.h > > -- > 2.8.1
On 30.03.2017 16:58, Petri Savolainen wrote: > Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) with > compiler independent mechanism to control if deprecated API definitions are > visible to the application. ODP_DEPRECATED_API can be used both in application > and implementation to check if deprecated APIs are enabled. By default those are > disabled. Implementation may optimize the normal (new API) code path. > > ODP_DEPRECATE() macro is used to rename definitions, so that data structure > sizes are equal on both options. This enables implementation to serve both > options with a single library (if it wishes to do so). My main question remains as it was before: is it possible for the distribution to supply (unoptimized) ODP binary and headers and then for the application to select if it builds with or without deprecated API using that binary/headers? Do we want to support such cases? -- With best wishes Dmitry
> -----Original Message----- > From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] > Sent: Wednesday, April 12, 2017 2:32 PM > To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > On 30.03.2017 16:58, Petri Savolainen wrote: > > Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) > with > > compiler independent mechanism to control if deprecated API definitions > are > > visible to the application. ODP_DEPRECATED_API can be used both in > application > > and implementation to check if deprecated APIs are enabled. By default > those are > > disabled. Implementation may optimize the normal (new API) code path. > > > > ODP_DEPRECATE() macro is used to rename definitions, so that data > structure > > sizes are equal on both options. This enables implementation to serve > both > > options with a single library (if it wishes to do so). > > My main question remains as it was before: is it possible for the > distribution to supply (unoptimized) ODP binary and headers and then for > the application to select if it builds with or without deprecated API > using that binary/headers? Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). -Petri > > Do we want to support such cases? > > -- > With best wishes > Dmitry
On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >> -----Original Message----- >> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >> Sent: Wednesday, April 12, 2017 2:32 PM >> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >> odp@lists.linaro.org >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> On 30.03.2017 16:58, Petri Savolainen wrote: >>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >> with >>> compiler independent mechanism to control if deprecated API definitions >> are >>> visible to the application. ODP_DEPRECATED_API can be used both in >> application >>> and implementation to check if deprecated APIs are enabled. By default >> those are >>> disabled. Implementation may optimize the normal (new API) code path. >>> >>> ODP_DEPRECATE() macro is used to rename definitions, so that data >> structure >>> sizes are equal on both options. This enables implementation to serve >> both >>> options with a single library (if it wishes to do so). >> >> My main question remains as it was before: is it possible for the >> distribution to supply (unoptimized) ODP binary and headers and then for >> the application to select if it builds with or without deprecated API >> using that binary/headers? > > > Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). If so. Consider I have built and installed ODP headers & binary built with --enable-deprecated-api. How do I build: - application that uses deprecated API? [I assume that the answer to this question is trivial: just build as is]. - application that wants to be sure that it does not use deprecated API? -- With best wishes Dmitry
On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org> wrote: > On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >> >> >>> -----Original Message----- >>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>> Sent: Wednesday, April 12, 2017 2:32 PM >>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>> odp@lists.linaro.org >>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>> >>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>> with >>>> compiler independent mechanism to control if deprecated API definitions >>> are >>>> visible to the application. ODP_DEPRECATED_API can be used both in >>> application >>>> and implementation to check if deprecated APIs are enabled. By default >>> those are >>>> disabled. Implementation may optimize the normal (new API) code path. >>>> >>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>> structure >>>> sizes are equal on both options. This enables implementation to serve >>> both >>>> options with a single library (if it wishes to do so). >>> >>> My main question remains as it was before: is it possible for the >>> distribution to supply (unoptimized) ODP binary and headers and then for >>> the application to select if it builds with or without deprecated API >>> using that binary/headers? >> >> >> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). > > If so. Consider I have built and installed ODP headers & binary built > with --enable-deprecated-api. > > How do I build: > > - application that uses deprecated API? > [I assume that the answer to this question is trivial: just build as is]. > > - application that wants to be sure that it does not use deprecated API? As a practical matter, the support of deprecated APIs is similar to the current provision for debug builds (--enable-debug and --enable-debug-print in the current ./configure script). These really are only of significance in the embedded space. In the cloud profile, applications use whatever ODP release(s) are installed on the system and the normal library-matchings are used to ensure that applications built for Release X are paired with library .so files compatible with that release. In this case, there are no deprecated APIs since applications only move to newer ODP release levels when they are ready. A cloud host system may specify the minimum ODP release level available on it, and that determines when laggards need to upgrade. So ODP will never ship a distribution that was configured with --enable-deprecated-api. The only users of this feature will be embedded applications that are customizing ODP to their own needs. > > > -- > With best wishes > Dmitry
On 12.04.2017 15:21, Bill Fischofer wrote: > On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov > <dmitry.ereminsolenikov@linaro.org> wrote: >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>> >>> >>>> -----Original Message----- >>>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>> odp@lists.linaro.org >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>>> with >>>>> compiler independent mechanism to control if deprecated API definitions >>>> are >>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>>> application >>>>> and implementation to check if deprecated APIs are enabled. By default >>>> those are >>>>> disabled. Implementation may optimize the normal (new API) code path. >>>>> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>>> structure >>>>> sizes are equal on both options. This enables implementation to serve >>>> both >>>>> options with a single library (if it wishes to do so). >>>> >>>> My main question remains as it was before: is it possible for the >>>> distribution to supply (unoptimized) ODP binary and headers and then for >>>> the application to select if it builds with or without deprecated API >>>> using that binary/headers? >>> >>> >>> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). >> >> If so. Consider I have built and installed ODP headers & binary built >> with --enable-deprecated-api. >> >> How do I build: >> >> - application that uses deprecated API? >> [I assume that the answer to this question is trivial: just build as is]. >> >> - application that wants to be sure that it does not use deprecated API? > > As a practical matter, the support of deprecated APIs is similar to > the current provision for debug builds (--enable-debug and > --enable-debug-print in the current ./configure script). These really > are only of significance in the embedded space. Or for application developers. > In the cloud profile, > applications use whatever ODP release(s) are installed on the system > and the normal library-matchings are used to ensure that applications > built for Release X are paired with library .so files compatible with > that release. In this case, there are no deprecated APIs since > applications only move to newer ODP release levels when they are > ready. A cloud host system may specify the minimum ODP release level > available on it, and that determines when laggards need to upgrade. Yep. That is the deployed ODP release. It is optimized for speed, it is optimized for that exact platform, etc. I'm more thinking about app developers. > > So ODP will never ship a distribution that was configured with > --enable-deprecated-api. The only users of this feature will be > embedded applications that are customizing ODP to their own needs. I'm thinking about SuSe, Canonical, RedHat or anybody else shipping ODP to enable application development on that platform. They would surely want to enable deprecated API (because otherwise old applications developed on that platform can stop building). But I'd expect that it is possible for the application developer to build an application checking that he does not use deprecated API anymore. -- With best wishes Dmitry
On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org> wrote: > On 12.04.2017 15:21, Bill Fischofer wrote: >> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov >> <dmitry.ereminsolenikov@linaro.org> wrote: >>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>>> >>>> >>>>> -----Original Message----- >>>>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>>> odp@lists.linaro.org >>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>>> >>>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>>>> with >>>>>> compiler independent mechanism to control if deprecated API definitions >>>>> are >>>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>>>> application >>>>>> and implementation to check if deprecated APIs are enabled. By default >>>>> those are >>>>>> disabled. Implementation may optimize the normal (new API) code path. >>>>>> >>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>>>> structure >>>>>> sizes are equal on both options. This enables implementation to serve >>>>> both >>>>>> options with a single library (if it wishes to do so). >>>>> >>>>> My main question remains as it was before: is it possible for the >>>>> distribution to supply (unoptimized) ODP binary and headers and then for >>>>> the application to select if it builds with or without deprecated API >>>>> using that binary/headers? >>>> >>>> >>>> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). >>> >>> If so. Consider I have built and installed ODP headers & binary built >>> with --enable-deprecated-api. >>> >>> How do I build: >>> >>> - application that uses deprecated API? >>> [I assume that the answer to this question is trivial: just build as is]. >>> >>> - application that wants to be sure that it does not use deprecated API? >> >> As a practical matter, the support of deprecated APIs is similar to >> the current provision for debug builds (--enable-debug and >> --enable-debug-print in the current ./configure script). These really >> are only of significance in the embedded space. > > Or for application developers. > >> In the cloud profile, >> applications use whatever ODP release(s) are installed on the system >> and the normal library-matchings are used to ensure that applications >> built for Release X are paired with library .so files compatible with >> that release. In this case, there are no deprecated APIs since >> applications only move to newer ODP release levels when they are >> ready. A cloud host system may specify the minimum ODP release level >> available on it, and that determines when laggards need to upgrade. > > Yep. That is the deployed ODP release. It is optimized for speed, it is > optimized for that exact platform, etc. I'm more thinking about app > developers. > >> >> So ODP will never ship a distribution that was configured with >> --enable-deprecated-api. The only users of this feature will be >> embedded applications that are customizing ODP to their own needs. > > I'm thinking about SuSe, Canonical, RedHat or anybody else shipping ODP > to enable application development on that platform. They would surely > want to enable deprecated API (because otherwise old applications > developed on that platform can stop building). But I'd expect that it is > possible for the application developer to build an application checking > that he does not use deprecated API anymore. This is really no different than supporting multiple levels of, say, the GCC compiler. Or any other package. At some point the old releases are no longer supported, but for some time you can have multiple levels available at the same time and you just use the one that you need. > > > > -- > With best wishes > Dmitry
On 12.04.2017 17:24, Bill Fischofer wrote: > On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov > <dmitry.ereminsolenikov@linaro.org> wrote: >> On 12.04.2017 15:21, Bill Fischofer wrote: >>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov >>> <dmitry.ereminsolenikov@linaro.org> wrote: >>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>>>> >>>>> >>>>>> -----Original Message----- >>>>>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>>>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>>>> odp@lists.linaro.org >>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>>>> >>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>>>>> with >>>>>>> compiler independent mechanism to control if deprecated API definitions >>>>>> are >>>>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>>>>> application >>>>>>> and implementation to check if deprecated APIs are enabled. By default >>>>>> those are >>>>>>> disabled. Implementation may optimize the normal (new API) code path. >>>>>>> >>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>>>>> structure >>>>>>> sizes are equal on both options. This enables implementation to serve >>>>>> both >>>>>>> options with a single library (if it wishes to do so). >>>>>> >>>>>> My main question remains as it was before: is it possible for the >>>>>> distribution to supply (unoptimized) ODP binary and headers and then for >>>>>> the application to select if it builds with or without deprecated API >>>>>> using that binary/headers? >>>>> >>>>> >>>>> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). >>>> >>>> If so. Consider I have built and installed ODP headers & binary built >>>> with --enable-deprecated-api. >>>> >>>> How do I build: >>>> >>>> - application that uses deprecated API? >>>> [I assume that the answer to this question is trivial: just build as is]. >>>> >>>> - application that wants to be sure that it does not use deprecated API? >>> >>> As a practical matter, the support of deprecated APIs is similar to >>> the current provision for debug builds (--enable-debug and >>> --enable-debug-print in the current ./configure script). These really >>> are only of significance in the embedded space. >> >> Or for application developers. >> >>> In the cloud profile, >>> applications use whatever ODP release(s) are installed on the system >>> and the normal library-matchings are used to ensure that applications >>> built for Release X are paired with library .so files compatible with >>> that release. In this case, there are no deprecated APIs since >>> applications only move to newer ODP release levels when they are >>> ready. A cloud host system may specify the minimum ODP release level >>> available on it, and that determines when laggards need to upgrade. >> >> Yep. That is the deployed ODP release. It is optimized for speed, it is >> optimized for that exact platform, etc. I'm more thinking about app >> developers. >> >>> >>> So ODP will never ship a distribution that was configured with >>> --enable-deprecated-api. The only users of this feature will be >>> embedded applications that are customizing ODP to their own needs. >> >> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping ODP >> to enable application development on that platform. They would surely >> want to enable deprecated API (because otherwise old applications >> developed on that platform can stop building). But I'd expect that it is >> possible for the application developer to build an application checking >> that he does not use deprecated API anymore. > > This is really no different than supporting multiple levels of, say, > the GCC compiler. Or any other package. At some point the old releases > are no longer supported, but for some time you can have multiple > levels available at the same time and you just use the one that you > need. We might want to consult maintainers. But from my previous experience, supporting several 'levels' is a significant headache, that most of maintainers would like to stand away from. Moreover, even if several versions are provided by distro, app developers still would like to have 'migration' path. Consider the way deprecated API are implemented e.g. in Gtk, Qt or other app frameworks. -- With best wishes Dmitry
On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org> wrote: > On 12.04.2017 17:24, Bill Fischofer wrote: >> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov >> <dmitry.ereminsolenikov@linaro.org> wrote: >>> On 12.04.2017 15:21, Bill Fischofer wrote: >>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov >>>> <dmitry.ereminsolenikov@linaro.org> wrote: >>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>>>>> >>>>>> >>>>>>> -----Original Message----- >>>>>>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>>>>> odp@lists.linaro.org >>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>>>>> >>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>>>>>> with >>>>>>>> compiler independent mechanism to control if deprecated API definitions >>>>>>> are >>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>>>>>> application >>>>>>>> and implementation to check if deprecated APIs are enabled. By default >>>>>>> those are >>>>>>>> disabled. Implementation may optimize the normal (new API) code path. >>>>>>>> >>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>>>>>> structure >>>>>>>> sizes are equal on both options. This enables implementation to serve >>>>>>> both >>>>>>>> options with a single library (if it wishes to do so). >>>>>>> >>>>>>> My main question remains as it was before: is it possible for the >>>>>>> distribution to supply (unoptimized) ODP binary and headers and then for >>>>>>> the application to select if it builds with or without deprecated API >>>>>>> using that binary/headers? >>>>>> >>>>>> >>>>>> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). >>>>> >>>>> If so. Consider I have built and installed ODP headers & binary built >>>>> with --enable-deprecated-api. >>>>> >>>>> How do I build: >>>>> >>>>> - application that uses deprecated API? >>>>> [I assume that the answer to this question is trivial: just build as is]. >>>>> >>>>> - application that wants to be sure that it does not use deprecated API? >>>> >>>> As a practical matter, the support of deprecated APIs is similar to >>>> the current provision for debug builds (--enable-debug and >>>> --enable-debug-print in the current ./configure script). These really >>>> are only of significance in the embedded space. >>> >>> Or for application developers. >>> >>>> In the cloud profile, >>>> applications use whatever ODP release(s) are installed on the system >>>> and the normal library-matchings are used to ensure that applications >>>> built for Release X are paired with library .so files compatible with >>>> that release. In this case, there are no deprecated APIs since >>>> applications only move to newer ODP release levels when they are >>>> ready. A cloud host system may specify the minimum ODP release level >>>> available on it, and that determines when laggards need to upgrade. >>> >>> Yep. That is the deployed ODP release. It is optimized for speed, it is >>> optimized for that exact platform, etc. I'm more thinking about app >>> developers. >>> >>>> >>>> So ODP will never ship a distribution that was configured with >>>> --enable-deprecated-api. The only users of this feature will be >>>> embedded applications that are customizing ODP to their own needs. >>> >>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping ODP >>> to enable application development on that platform. They would surely >>> want to enable deprecated API (because otherwise old applications >>> developed on that platform can stop building). But I'd expect that it is >>> possible for the application developer to build an application checking >>> that he does not use deprecated API anymore. >> >> This is really no different than supporting multiple levels of, say, >> the GCC compiler. Or any other package. At some point the old releases >> are no longer supported, but for some time you can have multiple >> levels available at the same time and you just use the one that you >> need. > > We might want to consult maintainers. But from my previous experience, > supporting several 'levels' is a significant headache, that most of > maintainers would like to stand away from. Moreover, even if several > versions are provided by distro, app developers still would like to have > 'migration' path. Consider the way deprecated API are implemented e.g. > in Gtk, Qt or other app frameworks. The migration path is very straightforward: Don't move until you're ready to move. When you are ready to move you change your application to use the new preferred APIs. Will some wait until they are forced to move because the older releases are no longer distributed? Sure. But that's just business as usual. The point is that distributions can choose to distribute whatever level(s) of ODP they wish. Our biggest problem is more likely to be not that they won't distribute older releases but the lag in getting them to distribute newer releases. It also points out that we really shouldn't be deprecating APIs in the first place. These should be very rare instances, not something so commonplace that we need a general framework to make it convenient to deprecate a bunch of stuff each release. An API is "forever" and we need to be mindful of that when we pour the concrete. As a practical matter, the main reason for deprecating an API is because it is superseded by a better way to do something. But keeping the older API around just means that applications don't get the advantage of using the newer way until such time as we get tired of carrying around the old baggage and the old forms get removed. So deprecation is more a documentation than a code issue, which is all that the original ODP_DEPRECATED() macros were intended to do. A likely more controversial issue is that we've stated that ODP makes no ABI compatibility claims from one release to the next. It's assumed that applications will recompile to move from ODP Release N to ODP Release N+1. In ODP, ABI compatibility is a statement of compatibility across different ODP implementations of a given API release, not across multiple API releases. > > -- > With best wishes > Dmitry
> -----Original Message----- > From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] > Sent: Wednesday, April 12, 2017 3:11 PM > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > labs.com>; lng-odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > > > >> -----Original Message----- > >> From: Dmitry Eremin-Solenikov > [mailto:dmitry.ereminsolenikov@linaro.org] > >> Sent: Wednesday, April 12, 2017 2:32 PM > >> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >> odp@lists.linaro.org > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> > >> On 30.03.2017 16:58, Petri Savolainen wrote: > >>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) > >> with > >>> compiler independent mechanism to control if deprecated API > definitions > >> are > >>> visible to the application. ODP_DEPRECATED_API can be used both in > >> application > >>> and implementation to check if deprecated APIs are enabled. By default > >> those are > >>> disabled. Implementation may optimize the normal (new API) code path. > >>> > >>> ODP_DEPRECATE() macro is used to rename definitions, so that data > >> structure > >>> sizes are equal on both options. This enables implementation to serve > >> both > >>> options with a single library (if it wishes to do so). > >> > >> My main question remains as it was before: is it possible for the > >> distribution to supply (unoptimized) ODP binary and headers and then > for > >> the application to select if it builds with or without deprecated API > >> using that binary/headers? > > > > > > Yes. This patch set keeps the same struct fields/etc for both modes - > only the names are scrambled (with __deprecated_ prefix) when deprecated > APIs are not supported (the default). > > If so. Consider I have built and installed ODP headers & binary built > with --enable-deprecated-api. So, you have built and installed the implementation with --enable-deprecated-api. This means that applications using this install, see deprecated APIs. A distribution decides which way it supports ODP, with or without deprecated stuff. The default in our (odp-linux) configure is without, to minimize confusion and promote the new API definitions which should be always better for application than the old ones. > > How do I build: > > - application that uses deprecated API? > [I assume that the answer to this question is trivial: just build as > is]. If you build with our make system: use --enable-deprecated-api. If you do not, then first build and install the implementation with --enable-deprecated-api, and then build against that (== installed ODP API headers contain old stuff). > > - application that wants to be sure that it does not use deprecated API? If you build with our make system: use --disable-deprecated-api. If you do not, then first build and install the implementation with --disable-deprecated-api, and then build against that (== installed ODP API headers have renamed old stuff, so that application build fails if it still uses those) -Petri
On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >> -----Original Message----- >> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >> Sent: Wednesday, April 12, 2017 3:11 PM >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >> labs.com>; lng-odp@lists.linaro.org >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>> >>> >>>> -----Original Message----- >>>> From: Dmitry Eremin-Solenikov >> [mailto:dmitry.ereminsolenikov@linaro.org] >>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>> odp@lists.linaro.org >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>>> with >>>>> compiler independent mechanism to control if deprecated API >> definitions >>>> are >>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>>> application >>>>> and implementation to check if deprecated APIs are enabled. By default >>>> those are >>>>> disabled. Implementation may optimize the normal (new API) code path. >>>>> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>>> structure >>>>> sizes are equal on both options. This enables implementation to serve >>>> both >>>>> options with a single library (if it wishes to do so). >>>> >>>> My main question remains as it was before: is it possible for the >>>> distribution to supply (unoptimized) ODP binary and headers and then >> for >>>> the application to select if it builds with or without deprecated API >>>> using that binary/headers? >>> >>> >>> Yes. This patch set keeps the same struct fields/etc for both modes - >> only the names are scrambled (with __deprecated_ prefix) when deprecated >> APIs are not supported (the default). >> >> If so. Consider I have built and installed ODP headers & binary built >> with --enable-deprecated-api. > > So, you have built and installed the implementation with --enable-deprecated-api. This means that applications using this install, see deprecated APIs. A distribution decides which way it supports ODP, with or without deprecated stuff. The default in our (odp-linux) configure is without, to minimize confusion and promote the new API definitions which should be always better for application than the old ones. > I was advocating for binary distributions and developers using packages from those distributions. And for those distributions providing _single_ binary version of ODP. -- With best wishes Dmitry
I vote for default build will not build with deprecating support. Yes all general propose distributives will need to enable --enable-deprecated-api to support some old software. But developers who work with git should not work with deprecated api. Maxim. On 13 April 2017 at 13:57, Dmitry Eremin-Solenikov < dmitry.ereminsolenikov@linaro.org> wrote: > On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > > > >> -----Original Message----- > >> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org > ] > >> Sent: Wednesday, April 12, 2017 3:11 PM > >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > >> labs.com>; lng-odp@lists.linaro.org > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> > >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >>> > >>> > >>>> -----Original Message----- > >>>> From: Dmitry Eremin-Solenikov > >> [mailto:dmitry.ereminsolenikov@linaro.org] > >>>> Sent: Wednesday, April 12, 2017 2:32 PM > >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >>>> odp@lists.linaro.org > >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >>>> > >>>> On 30.03.2017 16:58, Petri Savolainen wrote: > >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) > >>>> with > >>>>> compiler independent mechanism to control if deprecated API > >> definitions > >>>> are > >>>>> visible to the application. ODP_DEPRECATED_API can be used both in > >>>> application > >>>>> and implementation to check if deprecated APIs are enabled. By > default > >>>> those are > >>>>> disabled. Implementation may optimize the normal (new API) code path. > >>>>> > >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data > >>>> structure > >>>>> sizes are equal on both options. This enables implementation to serve > >>>> both > >>>>> options with a single library (if it wishes to do so). > >>>> > >>>> My main question remains as it was before: is it possible for the > >>>> distribution to supply (unoptimized) ODP binary and headers and then > >> for > >>>> the application to select if it builds with or without deprecated API > >>>> using that binary/headers? > >>> > >>> > >>> Yes. This patch set keeps the same struct fields/etc for both modes - > >> only the names are scrambled (with __deprecated_ prefix) when deprecated > >> APIs are not supported (the default). > >> > >> If so. Consider I have built and installed ODP headers & binary built > >> with --enable-deprecated-api. > > > > So, you have built and installed the implementation with > --enable-deprecated-api. This means that applications using this install, > see deprecated APIs. A distribution decides which way it supports ODP, with > or without deprecated stuff. The default in our (odp-linux) configure is > without, to minimize confusion and promote the new API definitions which > should be always better for application than the old ones. > > > > I was advocating for binary distributions and developers using packages > from those distributions. And for those distributions providing _single_ > binary version of ODP. > > > -- > With best wishes > Dmitry >
On Thu, Apr 13, 2017 at 6:46 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > I vote for default build will not build with deprecating support. Yes all > general propose distributives will need to enable --enable-deprecated-api > to support some old software. But developers who work with git should not > work with deprecated api. The opposite is more likely. Distros can distribute different levels of ODP and if you want the older version you just keep using the older version. So --enable-deprecated-api is really for embedded users who want (some) newer features but haven't (yet) converted older code. The key is that it is the embedded space that customizes and hyper tunes things, not the cloud, because the embedded space knows precisely the platform and configuration it's running on. By definition the cloud is more concerned with portability because the application does not control the environment--that's controlled by the operator. But no matter how you sugar-coat it, deprecation is always painful, which is why we should not do this at all, or at most only very rarely. So rarely that there is no need for a general framework for dealing with it as each deprecation will be considered on its own merits. Better to focus on structures that permit APIs to evolve over time without needing deprecation. As a practical matter, the question of deprecation is only relevant going forward from Tiger Moth / odp-cloud. There is no need to consider Monarch as "deprecatable" as it's never been part of any distro. > > Maxim. > > On 13 April 2017 at 13:57, Dmitry Eremin-Solenikov < > dmitry.ereminsolenikov@linaro.org> wrote: > >> On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: >> > >> > >> >> -----Original Message----- >> >> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org >> ] >> >> Sent: Wednesday, April 12, 2017 3:11 PM >> >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >> >> labs.com>; lng-odp@lists.linaro.org >> >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> >> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >> >>> >> >>> >> >>>> -----Original Message----- >> >>>> From: Dmitry Eremin-Solenikov >> >> [mailto:dmitry.ereminsolenikov@linaro.org] >> >>>> Sent: Wednesday, April 12, 2017 2:32 PM >> >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >> >>>> odp@lists.linaro.org >> >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >>>> >> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: >> >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >> >>>> with >> >>>>> compiler independent mechanism to control if deprecated API >> >> definitions >> >>>> are >> >>>>> visible to the application. ODP_DEPRECATED_API can be used both in >> >>>> application >> >>>>> and implementation to check if deprecated APIs are enabled. By >> default >> >>>> those are >> >>>>> disabled. Implementation may optimize the normal (new API) code path. >> >>>>> >> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >> >>>> structure >> >>>>> sizes are equal on both options. This enables implementation to serve >> >>>> both >> >>>>> options with a single library (if it wishes to do so). >> >>>> >> >>>> My main question remains as it was before: is it possible for the >> >>>> distribution to supply (unoptimized) ODP binary and headers and then >> >> for >> >>>> the application to select if it builds with or without deprecated API >> >>>> using that binary/headers? >> >>> >> >>> >> >>> Yes. This patch set keeps the same struct fields/etc for both modes - >> >> only the names are scrambled (with __deprecated_ prefix) when deprecated >> >> APIs are not supported (the default). >> >> >> >> If so. Consider I have built and installed ODP headers & binary built >> >> with --enable-deprecated-api. >> > >> > So, you have built and installed the implementation with >> --enable-deprecated-api. This means that applications using this install, >> see deprecated APIs. A distribution decides which way it supports ODP, with >> or without deprecated stuff. The default in our (odp-linux) configure is >> without, to minimize confusion and promote the new API definitions which >> should be always better for application than the old ones. >> > >> >> I was advocating for binary distributions and developers using packages >> from those distributions. And for those distributions providing _single_ >> binary version of ODP. >> >> >> -- >> With best wishes >> Dmitry >>
On 13.04.2017 15:26, Bill Fischofer wrote: > On Thu, Apr 13, 2017 at 6:46 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: >> I vote for default build will not build with deprecating support. Yes all >> general propose distributives will need to enable --enable-deprecated-api >> to support some old software. But developers who work with git should not >> work with deprecated api. > > The opposite is more likely. Distros can distribute different levels > of ODP and if you want the older version you just keep using the older > version. So --enable-deprecated-api is really for embedded users who > want (some) newer features but haven't (yet) converted older code. Fine, if you say so. It would be nice to hear a word from distro maintainers though. IIRC SuSe has ODP packaged. Canonical were working on that, weren't they? -- With best wishes Dmitry
13.04.2017 15:31, Dmitry Eremin-Solenikov wrote: > On 13.04.2017 15:26, Bill Fischofer wrote: >> On Thu, Apr 13, 2017 at 6:46 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: >>> I vote for default build will not build with deprecating support. Yes all >>> general propose distributives will need to enable --enable-deprecated-api >>> to support some old software. But developers who work with git should not >>> work with deprecated api. >> >> The opposite is more likely. Distros can distribute different levels >> of ODP and if you want the older version you just keep using the older >> version. So --enable-deprecated-api is really for embedded users who >> want (some) newer features but haven't (yet) converted older code. > > Fine, if you say so. It would be nice to hear a word from distro > maintainers though. IIRC SuSe has ODP packaged. Canonical were working > on that, weren't they? > From my experience enterprise distros have to support some deprecated syscalls inside linux kernel to support some application which were sold as binaries only. I.e. they use old api. I think it does not matter if it's embedded or not. It does matter if customer bought only binaries and he wants to use new version of library for some reason. Maxim.
> -----Original Message----- > From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] > Sent: Thursday, April 13, 2017 1:57 PM > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > labs.com>; lng-odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > > > >> -----Original Message----- > >> From: Dmitry Eremin-Solenikov > [mailto:dmitry.ereminsolenikov@linaro.org] > >> Sent: Wednesday, April 12, 2017 3:11 PM > >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > >> labs.com>; lng-odp@lists.linaro.org > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> > >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >>> > >>> > >>>> -----Original Message----- > >>>> From: Dmitry Eremin-Solenikov > >> [mailto:dmitry.ereminsolenikov@linaro.org] > >>>> Sent: Wednesday, April 12, 2017 2:32 PM > >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >>>> odp@lists.linaro.org > >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >>>> > >>>> On 30.03.2017 16:58, Petri Savolainen wrote: > >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) > >>>> with > >>>>> compiler independent mechanism to control if deprecated API > >> definitions > >>>> are > >>>>> visible to the application. ODP_DEPRECATED_API can be used both in > >>>> application > >>>>> and implementation to check if deprecated APIs are enabled. By > default > >>>> those are > >>>>> disabled. Implementation may optimize the normal (new API) code > path. > >>>>> > >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data > >>>> structure > >>>>> sizes are equal on both options. This enables implementation to > serve > >>>> both > >>>>> options with a single library (if it wishes to do so). > >>>> > >>>> My main question remains as it was before: is it possible for the > >>>> distribution to supply (unoptimized) ODP binary and headers and then > >> for > >>>> the application to select if it builds with or without deprecated API > >>>> using that binary/headers? > >>> > >>> > >>> Yes. This patch set keeps the same struct fields/etc for both modes - > >> only the names are scrambled (with __deprecated_ prefix) when > deprecated > >> APIs are not supported (the default). > >> > >> If so. Consider I have built and installed ODP headers & binary built > >> with --enable-deprecated-api. > > > > So, you have built and installed the implementation with --enable- > deprecated-api. This means that applications using this install, see > deprecated APIs. A distribution decides which way it supports ODP, with or > without deprecated stuff. The default in our (odp-linux) configure is > without, to minimize confusion and promote the new API definitions which > should be always better for application than the old ones. > > > > I was advocating for binary distributions and developers using packages > from those distributions. And for those distributions providing _single_ > binary version of ODP. Obviously, a distribution would select which ODP API versions are supported, and if those versions include deprecated APIs or not. Deprecation is feature of API spec and thus header files. A header file cannot be in both modes at the same time. E.g. a struct either has a field e.g. int foo or int _deprecated_foo, but not both at the same time. A single library can support both modes since struct sizes are the same (_deprecated_foo is left with default values since application does not read/write it). Now, if a distribution dictates that deprecated APIs are supported, an implementation delivers headers with deprecated stuff and a library that supports those. The same happens in the opposite case (headers without deprecated stuff and an library that supports those). Depending on implementation the library binary may be same or different. Distribution does not care, since it needs to store headers and pairing libs for those in any case. We do not guarantee binary compatibility over different API versions. Application, API headers and implementation lib need to be on the same API version - with or without deprecated stuff. -Petri
On Thu, Apr 13, 2017 at 9:07 AM, Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell-labs.com> wrote: > > >> -----Original Message----- >> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >> Sent: Thursday, April 13, 2017 1:57 PM >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >> labs.com>; lng-odp@lists.linaro.org >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: >> > >> > >> >> -----Original Message----- >> >> From: Dmitry Eremin-Solenikov >> [mailto:dmitry.ereminsolenikov@linaro.org] >> >> Sent: Wednesday, April 12, 2017 3:11 PM >> >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >> >> labs.com>; lng-odp@lists.linaro.org >> >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> >> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >> >>> >> >>> >> >>>> -----Original Message----- >> >>>> From: Dmitry Eremin-Solenikov >> >> [mailto:dmitry.ereminsolenikov@linaro.org] >> >>>> Sent: Wednesday, April 12, 2017 2:32 PM >> >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >> >>>> odp@lists.linaro.org >> >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >>>> >> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: >> >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >> >>>> with >> >>>>> compiler independent mechanism to control if deprecated API >> >> definitions >> >>>> are >> >>>>> visible to the application. ODP_DEPRECATED_API can be used both in >> >>>> application >> >>>>> and implementation to check if deprecated APIs are enabled. By >> default >> >>>> those are >> >>>>> disabled. Implementation may optimize the normal (new API) code >> path. >> >>>>> >> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >> >>>> structure >> >>>>> sizes are equal on both options. This enables implementation to >> serve >> >>>> both >> >>>>> options with a single library (if it wishes to do so). >> >>>> >> >>>> My main question remains as it was before: is it possible for the >> >>>> distribution to supply (unoptimized) ODP binary and headers and then >> >> for >> >>>> the application to select if it builds with or without deprecated API >> >>>> using that binary/headers? >> >>> >> >>> >> >>> Yes. This patch set keeps the same struct fields/etc for both modes - >> >> only the names are scrambled (with __deprecated_ prefix) when >> deprecated >> >> APIs are not supported (the default). >> >> >> >> If so. Consider I have built and installed ODP headers & binary built >> >> with --enable-deprecated-api. >> > >> > So, you have built and installed the implementation with --enable- >> deprecated-api. This means that applications using this install, see >> deprecated APIs. A distribution decides which way it supports ODP, with or >> without deprecated stuff. The default in our (odp-linux) configure is >> without, to minimize confusion and promote the new API definitions which >> should be always better for application than the old ones. >> > >> >> I was advocating for binary distributions and developers using packages >> from those distributions. And for those distributions providing _single_ >> binary version of ODP. > > Obviously, a distribution would select which ODP API versions are supported, and if those versions include deprecated APIs or not. Deprecation is feature of API spec and thus header files. A header file cannot be in both modes at the same time. E.g. a struct either has a field e.g. int foo or int _deprecated_foo, but not both at the same time. > > A single library can support both modes since struct sizes are the same (_deprecated_foo is left with default values since application does not read/write it). > > Now, if a distribution dictates that deprecated APIs are supported, an implementation delivers headers with deprecated stuff and a library that supports those. The same happens in the opposite case (headers without deprecated stuff and an library that supports those). Depending on implementation the library binary may be same or different. Distribution does not care, since it needs to store headers and pairing libs for those in any case. > > We do not guarantee binary compatibility over different API versions. Application, API headers and implementation lib need to be on the same API version - with or without deprecated stuff. Good summary. Having ODP part of a distro simply means that someone has installed it in the library catalog associated with that distro and configured it however they wished. At that point it's either part of the default install or can be installed with apt-get, yum, etc. What gets installed are the include files that allow applications to compile/link against that ODP installation, and the associated .so files that provide the runtime support for these apps. If I look on my Ubuntu 16.10 system I see /usr/include/clang and under that are several different release options (3.6, 3.6.3, 3.8, and 3.8.1 in my case). Similarly there is a /usr/lib/clang/ with the individual releases under it. ODP is no different. I'd expect there to be /usr/include/odp/<release> and /usr/lib/odp/<release> directories present. At that point it becomes a business decision, as to which releases / configurations a given distro offers. So if an application is built to run on ODP release X then it needs the libraries associated with release X to be available to it. If the distro also offers release Y and Z that's fine, but the app still will continue to run just fine as long as release X is still available. How long that is is an LTS consideration because at some point release X will no longer be supported and the application will have to move to a currently supported release. When it does that it needs to do two things: 1. Ensure that it's not using any APIs that are no longer present in the new release 2. Recompile against the new release Given that it's had years to prepare for step 1, I don't think it's unreasonable to assume that we have no need to support deprecated APIs, so distros aren't going to bother with having deprecated APIs being part of newer releases. If we wanted to continue their support it would be simpler to just continue the LTS for release X. Again, deprecation is a rare event and is mainly a documentation / communication / planning matter, not something that needs a lot of infrastructure support. > > -Petri > >
Ping. Review needed. Are we ready to merge? This should work fine with distros as explained two weeks ago. -Petri > -----Original Message----- > From: Bill Fischofer [mailto:bill.fischofer@linaro.org] > Sent: Thursday, April 13, 2017 6:02 PM > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > labs.com> > Cc: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>; lng- > odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > On Thu, Apr 13, 2017 at 9:07 AM, Savolainen, Petri (Nokia - FI/Espoo) > <petri.savolainen@nokia-bell-labs.com> wrote: > > > > > >> -----Original Message----- > >> From: Dmitry Eremin-Solenikov > [mailto:dmitry.ereminsolenikov@linaro.org] > >> Sent: Thursday, April 13, 2017 1:57 PM > >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > >> labs.com>; lng-odp@lists.linaro.org > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> > >> On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >> > > >> > > >> >> -----Original Message----- > >> >> From: Dmitry Eremin-Solenikov > >> [mailto:dmitry.ereminsolenikov@linaro.org] > >> >> Sent: Wednesday, April 12, 2017 3:11 PM > >> >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia- > bell- > >> >> labs.com>; lng-odp@lists.linaro.org > >> >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> >> > >> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >> >>> > >> >>> > >> >>>> -----Original Message----- > >> >>>> From: Dmitry Eremin-Solenikov > >> >> [mailto:dmitry.ereminsolenikov@linaro.org] > >> >>>> Sent: Wednesday, April 12, 2017 2:32 PM > >> >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >> >>>> odp@lists.linaro.org > >> >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> >>>> > >> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: > >> >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC > __attribute__) > >> >>>> with > >> >>>>> compiler independent mechanism to control if deprecated API > >> >> definitions > >> >>>> are > >> >>>>> visible to the application. ODP_DEPRECATED_API can be used both > in > >> >>>> application > >> >>>>> and implementation to check if deprecated APIs are enabled. By > >> default > >> >>>> those are > >> >>>>> disabled. Implementation may optimize the normal (new API) code > >> path. > >> >>>>> > >> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data > >> >>>> structure > >> >>>>> sizes are equal on both options. This enables implementation to > >> serve > >> >>>> both > >> >>>>> options with a single library (if it wishes to do so). > >> >>>> > >> >>>> My main question remains as it was before: is it possible for the > >> >>>> distribution to supply (unoptimized) ODP binary and headers and > then > >> >> for > >> >>>> the application to select if it builds with or without deprecated > API > >> >>>> using that binary/headers? > >> >>> > >> >>> > >> >>> Yes. This patch set keeps the same struct fields/etc for both modes > - > >> >> only the names are scrambled (with __deprecated_ prefix) when > >> deprecated > >> >> APIs are not supported (the default). > >> >> > >> >> If so. Consider I have built and installed ODP headers & binary > built > >> >> with --enable-deprecated-api. > >> > > >> > So, you have built and installed the implementation with --enable- > >> deprecated-api. This means that applications using this install, see > >> deprecated APIs. A distribution decides which way it supports ODP, with > or > >> without deprecated stuff. The default in our (odp-linux) configure is > >> without, to minimize confusion and promote the new API definitions > which > >> should be always better for application than the old ones. > >> > > >> > >> I was advocating for binary distributions and developers using packages > >> from those distributions. And for those distributions providing > _single_ > >> binary version of ODP. > > > > Obviously, a distribution would select which ODP API versions are > supported, and if those versions include deprecated APIs or not. > Deprecation is feature of API spec and thus header files. A header file > cannot be in both modes at the same time. E.g. a struct either has a field > e.g. int foo or int _deprecated_foo, but not both at the same time. > > > > A single library can support both modes since struct sizes are the same > (_deprecated_foo is left with default values since application does not > read/write it). > > > > Now, if a distribution dictates that deprecated APIs are supported, an > implementation delivers headers with deprecated stuff and a library that > supports those. The same happens in the opposite case (headers without > deprecated stuff and an library that supports those). Depending on > implementation the library binary may be same or different. Distribution > does not care, since it needs to store headers and pairing libs for those > in any case. > > > > We do not guarantee binary compatibility over different API versions. > Application, API headers and implementation lib need to be on the same API > version - with or without deprecated stuff. > > Good summary. Having ODP part of a distro simply means that someone > has installed it in the library catalog associated with that distro > and configured it however they wished. At that point it's either part > of the default install or can be installed with apt-get, yum, etc. > > What gets installed are the include files that allow applications to > compile/link against that ODP installation, and the associated .so > files that provide the runtime support for these apps. If I look on my > Ubuntu 16.10 system I see /usr/include/clang and under that are > several different release options (3.6, 3.6.3, 3.8, and 3.8.1 in my > case). Similarly there is a /usr/lib/clang/ with the individual > releases under it. ODP is no different. I'd expect there to be > /usr/include/odp/<release> and /usr/lib/odp/<release> directories > present. At that point it becomes a business decision, as to which > releases / configurations a given distro offers. > > So if an application is built to run on ODP release X then it needs > the libraries associated with release X to be available to it. If the > distro also offers release Y and Z that's fine, but the app still will > continue to run just fine as long as release X is still available. How > long that is is an LTS consideration because at some point release X > will no longer be supported and the application will have to move to a > currently supported release. When it does that it needs to do two > things: > > 1. Ensure that it's not using any APIs that are no longer present in > the new release > 2. Recompile against the new release > > Given that it's had years to prepare for step 1, I don't think it's > unreasonable to assume that we have no need to support deprecated > APIs, so distros aren't going to bother with having deprecated APIs > being part of newer releases. If we wanted to continue their support > it would be simpler to just continue the LTS for release X. > > Again, deprecation is a rare event and is mainly a documentation / > communication / planning matter, not something that needs a lot of > infrastructure support. > > > > > -Petri > > > >
On 13 April 2017 at 10:02, Bill Fischofer <bill.fischofer@linaro.org> wrote: > On Thu, Apr 13, 2017 at 9:07 AM, Savolainen, Petri (Nokia - FI/Espoo) > <petri.savolainen@nokia-bell-labs.com> wrote: >> >> >>> -----Original Message----- >>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] >>> Sent: Thursday, April 13, 2017 1:57 PM >>> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >>> labs.com>; lng-odp@lists.linaro.org >>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>> >>> On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>> > >>> > >>> >> -----Original Message----- >>> >> From: Dmitry Eremin-Solenikov >>> [mailto:dmitry.ereminsolenikov@linaro.org] >>> >> Sent: Wednesday, April 12, 2017 3:11 PM >>> >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- >>> >> labs.com>; lng-odp@lists.linaro.org >>> >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>> >> >>> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>> >>> >>> >>> >>> >>>> -----Original Message----- >>> >>>> From: Dmitry Eremin-Solenikov >>> >> [mailto:dmitry.ereminsolenikov@linaro.org] >>> >>>> Sent: Wednesday, April 12, 2017 2:32 PM >>> >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>> >>>> odp@lists.linaro.org >>> >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>> >>>> >>> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>> >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) >>> >>>> with >>> >>>>> compiler independent mechanism to control if deprecated API >>> >> definitions >>> >>>> are >>> >>>>> visible to the application. ODP_DEPRECATED_API can be used both in >>> >>>> application >>> >>>>> and implementation to check if deprecated APIs are enabled. By >>> default >>> >>>> those are >>> >>>>> disabled. Implementation may optimize the normal (new API) code >>> path. >>> >>>>> >>> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data >>> >>>> structure >>> >>>>> sizes are equal on both options. This enables implementation to >>> serve >>> >>>> both >>> >>>>> options with a single library (if it wishes to do so). >>> >>>> >>> >>>> My main question remains as it was before: is it possible for the >>> >>>> distribution to supply (unoptimized) ODP binary and headers and then >>> >> for >>> >>>> the application to select if it builds with or without deprecated API >>> >>>> using that binary/headers? >>> >>> >>> >>> >>> >>> Yes. This patch set keeps the same struct fields/etc for both modes - >>> >> only the names are scrambled (with __deprecated_ prefix) when >>> deprecated >>> >> APIs are not supported (the default). >>> >> >>> >> If so. Consider I have built and installed ODP headers & binary built >>> >> with --enable-deprecated-api. >>> > >>> > So, you have built and installed the implementation with --enable- >>> deprecated-api. This means that applications using this install, see >>> deprecated APIs. A distribution decides which way it supports ODP, with or >>> without deprecated stuff. The default in our (odp-linux) configure is >>> without, to minimize confusion and promote the new API definitions which >>> should be always better for application than the old ones. >>> > >>> >>> I was advocating for binary distributions and developers using packages >>> from those distributions. And for those distributions providing _single_ >>> binary version of ODP. >> >> Obviously, a distribution would select which ODP API versions are supported, and if those versions include deprecated APIs or not. Deprecation is feature of API spec and thus header files. A header file cannot be in both modes at the same time. E.g. a struct either has a field e.g. int foo or int _deprecated_foo, but not both at the same time. >> >> A single library can support both modes since struct sizes are the same (_deprecated_foo is left with default values since application does not read/write it). >> >> Now, if a distribution dictates that deprecated APIs are supported, an implementation delivers headers with deprecated stuff and a library that supports those. The same happens in the opposite case (headers without deprecated stuff and an library that supports those). Depending on implementation the library binary may be same or different. Distribution does not care, since it needs to store headers and pairing libs for those in any case. >> >> We do not guarantee binary compatibility over different API versions. Application, API headers and implementation lib need to be on the same API version - with or without deprecated stuff. > > Good summary. Having ODP part of a distro simply means that someone > has installed it in the library catalog associated with that distro > and configured it however they wished. At that point it's either part > of the default install or can be installed with apt-get, yum, etc. > > What gets installed are the include files that allow applications to > compile/link against that ODP installation, and the associated .so > files that provide the runtime support for these apps. If I look on my > Ubuntu 16.10 system I see /usr/include/clang and under that are > several different release options (3.6, 3.6.3, 3.8, and 3.8.1 in my > case). Similarly there is a /usr/lib/clang/ with the individual > releases under it. ODP is no different. I'd expect there to be > /usr/include/odp/<release> and /usr/lib/odp/<release> directories > present. At that point it becomes a business decision, as to which > releases / configurations a given distro offers. > > So if an application is built to run on ODP release X then it needs > the libraries associated with release X to be available to it. If the > distro also offers release Y and Z that's fine, but the app still will > continue to run just fine as long as release X is still available. How > long that is is an LTS consideration because at some point release X > will no longer be supported and the application will have to move to a > currently supported release. When it does that it needs to do two > things: > > 1. Ensure that it's not using any APIs that are no longer present in > the new release > 2. Recompile against the new release > > Given that it's had years to prepare for step 1, I don't think it's > unreasonable to assume that we have no need to support deprecated > APIs, so distros aren't going to bother with having deprecated APIs > being part of newer releases. If we wanted to continue their support > it would be simpler to just continue the LTS for release X. > > Again, deprecation is a rare event and is mainly a documentation / > communication / planning matter, not something that needs a lot of > infrastructure support. > Read through the discussion chain. This summary reflects my understanding as well. Every release will have release notes that document the change in API definitions (including deprecations). Application developers should look at them to find out the changes and decide whether they want to move to the next release or not. If they decide to move, they have to change their code to not use the deprecated things. If required, we could have a separate section for deprecated things. I also do not think that one would like to write code with deprecated APIs/structure fields and deploy the application. >> >> -Petri >> >>
Ping. Review needed. Packet range patch needs this. We have deprecation in place already. This patch set makes deprecation more explicit than it's today. With this deprecation is off by default, and user can turn it on. Today, deprecation is on by default and there's no way to turn it off. It's another discussion, if deprecation should be removed all together. We don't decide that on this patch set. This set makes it possible to control it. I think majority of the people think that it's good to offer the flexibility. -Petri > -----Original Message----- > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of > Savolainen, Petri (Nokia - FI/Espoo) > Sent: Monday, April 24, 2017 2:06 PM > To: Maxim Uvarov <maxim.uvarov@linaro.org> > Cc: lng-odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > Ping. Review needed. Are we ready to merge? This should work fine with > distros as explained two weeks ago. > > > -Petri > > > > -----Original Message----- > > From: Bill Fischofer [mailto:bill.fischofer@linaro.org] > > Sent: Thursday, April 13, 2017 6:02 PM > > To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia-bell- > > labs.com> > > Cc: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>; lng- > > odp@lists.linaro.org > > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > > > On Thu, Apr 13, 2017 at 9:07 AM, Savolainen, Petri (Nokia - FI/Espoo) > > <petri.savolainen@nokia-bell-labs.com> wrote: > > > > > > > > >> -----Original Message----- > > >> From: Dmitry Eremin-Solenikov > > [mailto:dmitry.ereminsolenikov@linaro.org] > > >> Sent: Thursday, April 13, 2017 1:57 PM > > >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia- > bell- > > >> labs.com>; lng-odp@lists.linaro.org > > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > >> > > >> On 13.04.2017 10:33, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >> > > > >> > > > >> >> -----Original Message----- > > >> >> From: Dmitry Eremin-Solenikov > > >> [mailto:dmitry.ereminsolenikov@linaro.org] > > >> >> Sent: Wednesday, April 12, 2017 3:11 PM > > >> >> To: Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia- > > bell- > > >> >> labs.com>; lng-odp@lists.linaro.org > > >> >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > >> >> > > >> >> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >> >>> > > >> >>> > > >> >>>> -----Original Message----- > > >> >>>> From: Dmitry Eremin-Solenikov > > >> >> [mailto:dmitry.ereminsolenikov@linaro.org] > > >> >>>> Sent: Wednesday, April 12, 2017 2:32 PM > > >> >>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > > >> >>>> odp@lists.linaro.org > > >> >>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > >> >>>> > > >> >>>> On 30.03.2017 16:58, Petri Savolainen wrote: > > >> >>>>> Replaced ODP_DEPRECATED macro (which was based on GCC > > __attribute__) > > >> >>>> with > > >> >>>>> compiler independent mechanism to control if deprecated API > > >> >> definitions > > >> >>>> are > > >> >>>>> visible to the application. ODP_DEPRECATED_API can be used both > > in > > >> >>>> application > > >> >>>>> and implementation to check if deprecated APIs are enabled. By > > >> default > > >> >>>> those are > > >> >>>>> disabled. Implementation may optimize the normal (new API) code > > >> path. > > >> >>>>> > > >> >>>>> ODP_DEPRECATE() macro is used to rename definitions, so that > data > > >> >>>> structure > > >> >>>>> sizes are equal on both options. This enables implementation to > > >> serve > > >> >>>> both > > >> >>>>> options with a single library (if it wishes to do so). > > >> >>>> > > >> >>>> My main question remains as it was before: is it possible for > the > > >> >>>> distribution to supply (unoptimized) ODP binary and headers and > > then > > >> >> for > > >> >>>> the application to select if it builds with or without > deprecated > > API > > >> >>>> using that binary/headers? > > >> >>> > > >> >>> > > >> >>> Yes. This patch set keeps the same struct fields/etc for both > modes > > - > > >> >> only the names are scrambled (with __deprecated_ prefix) when > > >> deprecated > > >> >> APIs are not supported (the default). > > >> >> > > >> >> If so. Consider I have built and installed ODP headers & binary > > built > > >> >> with --enable-deprecated-api. > > >> > > > >> > So, you have built and installed the implementation with --enable- > > >> deprecated-api. This means that applications using this install, see > > >> deprecated APIs. A distribution decides which way it supports ODP, > with > > or > > >> without deprecated stuff. The default in our (odp-linux) configure is > > >> without, to minimize confusion and promote the new API definitions > > which > > >> should be always better for application than the old ones. > > >> > > > >> > > >> I was advocating for binary distributions and developers using > packages > > >> from those distributions. And for those distributions providing > > _single_ > > >> binary version of ODP. > > > > > > Obviously, a distribution would select which ODP API versions are > > supported, and if those versions include deprecated APIs or not. > > Deprecation is feature of API spec and thus header files. A header file > > cannot be in both modes at the same time. E.g. a struct either has a > field > > e.g. int foo or int _deprecated_foo, but not both at the same time. > > > > > > A single library can support both modes since struct sizes are the > same > > (_deprecated_foo is left with default values since application does not > > read/write it). > > > > > > Now, if a distribution dictates that deprecated APIs are supported, an > > implementation delivers headers with deprecated stuff and a library that > > supports those. The same happens in the opposite case (headers without > > deprecated stuff and an library that supports those). Depending on > > implementation the library binary may be same or different. Distribution > > does not care, since it needs to store headers and pairing libs for > those > > in any case. > > > > > > We do not guarantee binary compatibility over different API versions. > > Application, API headers and implementation lib need to be on the same > API > > version - with or without deprecated stuff. > > > > Good summary. Having ODP part of a distro simply means that someone > > has installed it in the library catalog associated with that distro > > and configured it however they wished. At that point it's either part > > of the default install or can be installed with apt-get, yum, etc. > > > > What gets installed are the include files that allow applications to > > compile/link against that ODP installation, and the associated .so > > files that provide the runtime support for these apps. If I look on my > > Ubuntu 16.10 system I see /usr/include/clang and under that are > > several different release options (3.6, 3.6.3, 3.8, and 3.8.1 in my > > case). Similarly there is a /usr/lib/clang/ with the individual > > releases under it. ODP is no different. I'd expect there to be > > /usr/include/odp/<release> and /usr/lib/odp/<release> directories > > present. At that point it becomes a business decision, as to which > > releases / configurations a given distro offers. > > > > So if an application is built to run on ODP release X then it needs > > the libraries associated with release X to be available to it. If the > > distro also offers release Y and Z that's fine, but the app still will > > continue to run just fine as long as release X is still available. How > > long that is is an LTS consideration because at some point release X > > will no longer be supported and the application will have to move to a > > currently supported release. When it does that it needs to do two > > things: > > > > 1. Ensure that it's not using any APIs that are no longer present in > > the new release > > 2. Recompile against the new release > > > > Given that it's had years to prepare for step 1, I don't think it's > > unreasonable to assume that we have no need to support deprecated > > APIs, so distros aren't going to bother with having deprecated APIs > > being part of newer releases. If we wanted to continue their support > > it would be simpler to just continue the LTS for release X. > > > > Again, deprecation is a rare event and is mainly a documentation / > > communication / planning matter, not something that needs a lot of > > infrastructure support. > > > > > > > > -Petri > > > > > >
On ????., ??????. 12, 2017 at 10:33:24 -0500, Bill Fischofer wrote: > On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov > <dmitry.ereminsolenikov@linaro.org> wrote: > > On 12.04.2017 17:24, Bill Fischofer wrote: > >> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov > >> <dmitry.ereminsolenikov@linaro.org> wrote: > >>> On 12.04.2017 15:21, Bill Fischofer wrote: > >>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov > >>>> <dmitry.ereminsolenikov@linaro.org> wrote: > >>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >>>>>> > >>>>>> > >>>>>>> -----Original Message----- > >>>>>>> From: Dmitry Eremin-Solenikov [mailto:dmitry.ereminsolenikov@linaro.org] > >>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM > >>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >>>>>>> odp@lists.linaro.org > >>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >>>>>>> > >>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: > >>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) > >>>>>>> with > >>>>>>>> compiler independent mechanism to control if deprecated API definitions > >>>>>>> are > >>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both in > >>>>>>> application > >>>>>>>> and implementation to check if deprecated APIs are enabled. By default > >>>>>>> those are > >>>>>>>> disabled. Implementation may optimize the normal (new API) code path. > >>>>>>>> > >>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that data > >>>>>>> structure > >>>>>>>> sizes are equal on both options. This enables implementation to serve > >>>>>>> both > >>>>>>>> options with a single library (if it wishes to do so). > >>>>>>> > >>>>>>> My main question remains as it was before: is it possible for the > >>>>>>> distribution to supply (unoptimized) ODP binary and headers and then for > >>>>>>> the application to select if it builds with or without deprecated API > >>>>>>> using that binary/headers? > >>>>>> > >>>>>> > >>>>>> Yes. This patch set keeps the same struct fields/etc for both modes - only the names are scrambled (with __deprecated_ prefix) when deprecated APIs are not supported (the default). > >>>>> > >>>>> If so. Consider I have built and installed ODP headers & binary built > >>>>> with --enable-deprecated-api. > >>>>> > >>>>> How do I build: > >>>>> > >>>>> - application that uses deprecated API? > >>>>> [I assume that the answer to this question is trivial: just build as is]. > >>>>> > >>>>> - application that wants to be sure that it does not use deprecated API? > >>>> > >>>> As a practical matter, the support of deprecated APIs is similar to > >>>> the current provision for debug builds (--enable-debug and > >>>> --enable-debug-print in the current ./configure script). These really > >>>> are only of significance in the embedded space. > >>> > >>> Or for application developers. > >>> > >>>> In the cloud profile, > >>>> applications use whatever ODP release(s) are installed on the system > >>>> and the normal library-matchings are used to ensure that applications > >>>> built for Release X are paired with library .so files compatible with > >>>> that release. In this case, there are no deprecated APIs since > >>>> applications only move to newer ODP release levels when they are > >>>> ready. A cloud host system may specify the minimum ODP release level > >>>> available on it, and that determines when laggards need to upgrade. > >>> > >>> Yep. That is the deployed ODP release. It is optimized for speed, it is > >>> optimized for that exact platform, etc. I'm more thinking about app > >>> developers. > >>> > >>>> > >>>> So ODP will never ship a distribution that was configured with > >>>> --enable-deprecated-api. The only users of this feature will be > >>>> embedded applications that are customizing ODP to their own needs. > >>> > >>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping ODP > >>> to enable application development on that platform. They would surely > >>> want to enable deprecated API (because otherwise old applications > >>> developed on that platform can stop building). But I'd expect that it is > >>> possible for the application developer to build an application checking > >>> that he does not use deprecated API anymore. > >> > >> This is really no different than supporting multiple levels of, say, > >> the GCC compiler. Or any other package. At some point the old releases > >> are no longer supported, but for some time you can have multiple > >> levels available at the same time and you just use the one that you > >> need. > > > > We might want to consult maintainers. But from my previous experience, > > supporting several 'levels' is a significant headache, that most of > > maintainers would like to stand away from. Moreover, even if several > > versions are provided by distro, app developers still would like to have > > 'migration' path. Consider the way deprecated API are implemented e.g. > > in Gtk, Qt or other app frameworks. > > The migration path is very straightforward: Don't move until you're > ready to move. When you are ready to move you change your application > to use the new preferred APIs. > > Will some wait until they are forced to move because the older > releases are no longer distributed? Sure. But that's just business as > usual. The point is that distributions can choose to distribute > whatever level(s) of ODP they wish. Our biggest problem is more likely > to be not that they won't distribute older releases but the lag in > getting them to distribute newer releases. > > It also points out that we really shouldn't be deprecating APIs in the > first place. These should be very rare instances, not something so > commonplace that we need a general framework to make it convenient to > deprecate a bunch of stuff each release. An API is "forever" and we > need to be mindful of that when we pour the concrete. > > As a practical matter, the main reason for deprecating an API is > because it is superseded by a better way to do something. But keeping > the older API around just means that applications don't get the > advantage of using the newer way until such time as we get tired of > carrying around the old baggage and the old forms get removed. So > deprecation is more a documentation than a code issue, which is all > that the original ODP_DEPRECATED() macros were intended to do. > > A likely more controversial issue is that we've stated that ODP makes > no ABI compatibility claims from one release to the next. It's assumed > that applications will recompile to move from ODP Release N to ODP > Release N+1. In ODP, ABI compatibility is a statement of compatibility > across different ODP implementations of a given API release, not > across multiple API releases. > I have some more thoughts on deprecating api / documentation. First lets clearly define what deprecation as: Feature of making api functions of struct element for limited support by ODP implementer in future. In that case: - Upstream (Linaro/odp) has to provide common best practice way to do that. - All api headers have to remain the same as main repo has, only some function can be marked as deprecated. - Each ODP implementer can choose which functions he marks as deprecated and for how long. The same for data structures. What is delivery? How odp is shipped? - library + headers (more common for enterprise software). - git sources (more common for embedded). In my understanding current approach with #idefs in api does not work due to it's impossible to quickly compare headers with main line code if everybody will start to mark unmark fields as deprecated (implementers and main line at the same time.) I see a way how we can get more clear definition here: - ODP mainline provides documentation and ways how to mark deprecated function or types. - ./configure has to have --enable-deprecated symbol - ./include/api headers have to be generated on ./configure stage regarding if deprecated symbols are supported or not. That include headers have to be shipped with library binary to package. - all deprecated api have to be in separate folder to be easy to remove something like ./include/api-deprecated/ - Doxygen note has to have all deprecated symbols documented. Now when we talk about real delivery we talk only about Long Term Support releases. When we do this release we can discuss which api people still want to support as deprecated. In that case we enable this apis in the build. But apps developers will know that these apis will no be valid on next release. In my understanding it has to solve patch original api headers with deprecated macro and makes maintains more easy. Best regards, Maxim.
> -----Original Message----- > From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of maxim > Sent: Tuesday, May 02, 2017 1:06 PM > To: lng-odp@lists.linaro.org > Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > On ????., ??????. 12, 2017 at 10:33:24 -0500, Bill Fischofer wrote: > > On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov > > <dmitry.ereminsolenikov@linaro.org> wrote: > > > On 12.04.2017 17:24, Bill Fischofer wrote: > > >> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov > > >> <dmitry.ereminsolenikov@linaro.org> wrote: > > >>> On 12.04.2017 15:21, Bill Fischofer wrote: > > >>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov > > >>>> <dmitry.ereminsolenikov@linaro.org> wrote: > > >>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >>>>>> > > >>>>>> > > >>>>>>> -----Original Message----- > > >>>>>>> From: Dmitry Eremin-Solenikov > [mailto:dmitry.ereminsolenikov@linaro.org] > > >>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM > > >>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > > >>>>>>> odp@lists.linaro.org > > >>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > > >>>>>>> > > >>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: > > >>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC > __attribute__) > > >>>>>>> with > > >>>>>>>> compiler independent mechanism to control if deprecated API > definitions > > >>>>>>> are > > >>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both > in > > >>>>>>> application > > >>>>>>>> and implementation to check if deprecated APIs are enabled. By > default > > >>>>>>> those are > > >>>>>>>> disabled. Implementation may optimize the normal (new API) code > path. > > >>>>>>>> > > >>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that > data > > >>>>>>> structure > > >>>>>>>> sizes are equal on both options. This enables implementation to > serve > > >>>>>>> both > > >>>>>>>> options with a single library (if it wishes to do so). > > >>>>>>> > > >>>>>>> My main question remains as it was before: is it possible for > the > > >>>>>>> distribution to supply (unoptimized) ODP binary and headers and > then for > > >>>>>>> the application to select if it builds with or without > deprecated API > > >>>>>>> using that binary/headers? > > >>>>>> > > >>>>>> > > >>>>>> Yes. This patch set keeps the same struct fields/etc for both > modes - only the names are scrambled (with __deprecated_ prefix) when > deprecated APIs are not supported (the default). > > >>>>> > > >>>>> If so. Consider I have built and installed ODP headers & binary > built > > >>>>> with --enable-deprecated-api. > > >>>>> > > >>>>> How do I build: > > >>>>> > > >>>>> - application that uses deprecated API? > > >>>>> [I assume that the answer to this question is trivial: just > build as is]. > > >>>>> > > >>>>> - application that wants to be sure that it does not use > deprecated API? > > >>>> > > >>>> As a practical matter, the support of deprecated APIs is similar to > > >>>> the current provision for debug builds (--enable-debug and > > >>>> --enable-debug-print in the current ./configure script). These > really > > >>>> are only of significance in the embedded space. > > >>> > > >>> Or for application developers. > > >>> > > >>>> In the cloud profile, > > >>>> applications use whatever ODP release(s) are installed on the > system > > >>>> and the normal library-matchings are used to ensure that > applications > > >>>> built for Release X are paired with library .so files compatible > with > > >>>> that release. In this case, there are no deprecated APIs since > > >>>> applications only move to newer ODP release levels when they are > > >>>> ready. A cloud host system may specify the minimum ODP release > level > > >>>> available on it, and that determines when laggards need to upgrade. > > >>> > > >>> Yep. That is the deployed ODP release. It is optimized for speed, it > is > > >>> optimized for that exact platform, etc. I'm more thinking about app > > >>> developers. > > >>> > > >>>> > > >>>> So ODP will never ship a distribution that was configured with > > >>>> --enable-deprecated-api. The only users of this feature will be > > >>>> embedded applications that are customizing ODP to their own needs. > > >>> > > >>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping > ODP > > >>> to enable application development on that platform. They would > surely > > >>> want to enable deprecated API (because otherwise old applications > > >>> developed on that platform can stop building). But I'd expect that > it is > > >>> possible for the application developer to build an application > checking > > >>> that he does not use deprecated API anymore. > > >> > > >> This is really no different than supporting multiple levels of, say, > > >> the GCC compiler. Or any other package. At some point the old > releases > > >> are no longer supported, but for some time you can have multiple > > >> levels available at the same time and you just use the one that you > > >> need. > > > > > > We might want to consult maintainers. But from my previous experience, > > > supporting several 'levels' is a significant headache, that most of > > > maintainers would like to stand away from. Moreover, even if several > > > versions are provided by distro, app developers still would like to > have > > > 'migration' path. Consider the way deprecated API are implemented e.g. > > > in Gtk, Qt or other app frameworks. > > > > The migration path is very straightforward: Don't move until you're > > ready to move. When you are ready to move you change your application > > to use the new preferred APIs. > > > > Will some wait until they are forced to move because the older > > releases are no longer distributed? Sure. But that's just business as > > usual. The point is that distributions can choose to distribute > > whatever level(s) of ODP they wish. Our biggest problem is more likely > > to be not that they won't distribute older releases but the lag in > > getting them to distribute newer releases. > > > > It also points out that we really shouldn't be deprecating APIs in the > > first place. These should be very rare instances, not something so > > commonplace that we need a general framework to make it convenient to > > deprecate a bunch of stuff each release. An API is "forever" and we > > need to be mindful of that when we pour the concrete. > > > > As a practical matter, the main reason for deprecating an API is > > because it is superseded by a better way to do something. But keeping > > the older API around just means that applications don't get the > > advantage of using the newer way until such time as we get tired of > > carrying around the old baggage and the old forms get removed. So > > deprecation is more a documentation than a code issue, which is all > > that the original ODP_DEPRECATED() macros were intended to do. > > > > A likely more controversial issue is that we've stated that ODP makes > > no ABI compatibility claims from one release to the next. It's assumed > > that applications will recompile to move from ODP Release N to ODP > > Release N+1. In ODP, ABI compatibility is a statement of compatibility > > across different ODP implementations of a given API release, not > > across multiple API releases. > > > > I have some more thoughts on deprecating api / documentation. > > First lets clearly define what deprecation as: > Feature of making api functions of struct element for limited support > by ODP implementer in future. No. Deprecation is part of API specification. For example, API spec v1.20 could define: typedef struct odp_foo_bar_t { /** This is foo*/ uint8_t foo; } odp_foo_bar_t; API spec v1.30 could define: typedef struct odp_foo_bar_t { /** @deprecated Foo is deprecated, use bar instead. */ uint8_t ODP_DEPRECATE(foo); /** This is bar */ uint8_t bar; } odp_foo_bar_t; By default, ODP_DEPRECATE() macro makes 'foo' unusable for the application. Each implementation may choose to support only the default (foo unusable), or also support all deprecated stuff (foo usable). API spec has only two modes: with or without deprecated stuff. If you compile with deprecated, the above example looks like this to the application: typedef struct odp_foo_bar_t { /** @deprecated Foo is deprecated, use bar instead. */ uint8_t foo; /** This is bar */ uint8_t bar; } odp_foo_bar_t; ... and without deprecation (the default) it looks like this typedef struct odp_foo_bar_t { /** @deprecated Foo is deprecated, use bar instead. */ uint8_t ____dont_use_this_since_its_deprecated_foo; /** This is bar */ uint8_t bar; } odp_foo_bar_t; Note: struct size does not change between the two modes. > > In that case: > - Upstream (Linaro/odp) has to provide common best practice way to do > that. > - All api headers have to remain the same as main repo has, only some > function can be marked as deprecated. > - Each ODP implementer can choose which functions he marks as deprecated > and for how long. The same for data structures. Deprecated APIs are part of API spec. So, implementation cannot add or remove the number of deprecated APIs. It can just choose to support all of those, or none. > > What is delivery? How odp is shipped? > - library + headers (more common for enterprise software). > - git sources (more common for embedded). API spec is the primary deliverable of ODP project. Deprecation spec does not include how SW is delivered, it just defines those things in API that are invisible/visible to the application, when deprecation support is off/on. It's a business choice for an implementation / class of implementations to support deprecated APIs. > > In my understanding current approach with #idefs in api does not work > due to it's impossible to quickly compare headers with main line code > if everybody will start to mark unmark fields as deprecated > (implementers and main line at the same time.) The spec does not contain #ifdef. It marks deprecated stuff with ODP_DEPRECATE(). An implementation must not add / remove those. The spec files are the same for everybody. > > I see a way how we can get more clear definition here: > - ODP mainline provides documentation and ways how to mark deprecated > function or types. This is the ODP_DEPRECATE() macro. > - ./configure has to have --enable-deprecated symbol It depends on implementation which build system is used, but obviously it needs a way to enable deprecated APIs if it supports those. > - ./include/api headers have to be generated on ./configure stage > regarding if deprecated symbols are supported or not. That include > headers have to be shipped with library binary to package. This is no different from selecting if ABI compat is used. Both need to be selected at build time (at latest). Obviously, for distros we always build with ABI compat, we need to decide our position on deprecated APIs. Maybe those are always off (as the default mode suggests). > - all deprecated api have to be in separate folder to be easy to remove > something like ./include/api-deprecated/ > - Doxygen note has to have all deprecated symbols documented. Separate folders are not needed. API spec files mark deprecated definitions with both ODP_DEPRECATE() and @deprecated tag. Implementations re-use the spec files as-is, or otherwise make sure that the same definitions are visible/not-visible to the application through ODP API. -Petri > > > Now when we talk about real delivery we talk only about Long Term > Support releases. When we do this release we can discuss which api > people still want to support as deprecated. In that case we enable > this apis in the build. But apps developers will know that these apis > will no be valid on next release. > > In my understanding it has to solve patch original api headers with > deprecated macro and makes maintains more easy. > > Best regards, > Maxim. > > > > > > > > > > > > > > > > > > > >
On 05/02/17 14:43, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > >> -----Original Message----- >> From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of maxim >> Sent: Tuesday, May 02, 2017 1:06 PM >> To: lng-odp@lists.linaro.org >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >> >> On ????., ??????. 12, 2017 at 10:33:24 -0500, Bill Fischofer wrote: >>> On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov >>> <dmitry.ereminsolenikov@linaro.org> wrote: >>>> On 12.04.2017 17:24, Bill Fischofer wrote: >>>>> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov >>>>> <dmitry.ereminsolenikov@linaro.org> wrote: >>>>>> On 12.04.2017 15:21, Bill Fischofer wrote: >>>>>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov >>>>>>> <dmitry.ereminsolenikov@linaro.org> wrote: >>>>>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: >>>>>>>>> >>>>>>>>> >>>>>>>>>> -----Original Message----- >>>>>>>>>> From: Dmitry Eremin-Solenikov >> [mailto:dmitry.ereminsolenikov@linaro.org] >>>>>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM >>>>>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- >>>>>>>>>> odp@lists.linaro.org >>>>>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros >>>>>>>>>> >>>>>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: >>>>>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC >> __attribute__) >>>>>>>>>> with >>>>>>>>>>> compiler independent mechanism to control if deprecated API >> definitions >>>>>>>>>> are >>>>>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both >> in >>>>>>>>>> application >>>>>>>>>>> and implementation to check if deprecated APIs are enabled. By >> default >>>>>>>>>> those are >>>>>>>>>>> disabled. Implementation may optimize the normal (new API) code >> path. >>>>>>>>>>> >>>>>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that >> data >>>>>>>>>> structure >>>>>>>>>>> sizes are equal on both options. This enables implementation to >> serve >>>>>>>>>> both >>>>>>>>>>> options with a single library (if it wishes to do so). >>>>>>>>>> >>>>>>>>>> My main question remains as it was before: is it possible for >> the >>>>>>>>>> distribution to supply (unoptimized) ODP binary and headers and >> then for >>>>>>>>>> the application to select if it builds with or without >> deprecated API >>>>>>>>>> using that binary/headers? >>>>>>>>> >>>>>>>>> >>>>>>>>> Yes. This patch set keeps the same struct fields/etc for both >> modes - only the names are scrambled (with __deprecated_ prefix) when >> deprecated APIs are not supported (the default). >>>>>>>> >>>>>>>> If so. Consider I have built and installed ODP headers & binary >> built >>>>>>>> with --enable-deprecated-api. >>>>>>>> >>>>>>>> How do I build: >>>>>>>> >>>>>>>> - application that uses deprecated API? >>>>>>>> [I assume that the answer to this question is trivial: just >> build as is]. >>>>>>>> >>>>>>>> - application that wants to be sure that it does not use >> deprecated API? >>>>>>> >>>>>>> As a practical matter, the support of deprecated APIs is similar to >>>>>>> the current provision for debug builds (--enable-debug and >>>>>>> --enable-debug-print in the current ./configure script). These >> really >>>>>>> are only of significance in the embedded space. >>>>>> >>>>>> Or for application developers. >>>>>> >>>>>>> In the cloud profile, >>>>>>> applications use whatever ODP release(s) are installed on the >> system >>>>>>> and the normal library-matchings are used to ensure that >> applications >>>>>>> built for Release X are paired with library .so files compatible >> with >>>>>>> that release. In this case, there are no deprecated APIs since >>>>>>> applications only move to newer ODP release levels when they are >>>>>>> ready. A cloud host system may specify the minimum ODP release >> level >>>>>>> available on it, and that determines when laggards need to upgrade. >>>>>> >>>>>> Yep. That is the deployed ODP release. It is optimized for speed, it >> is >>>>>> optimized for that exact platform, etc. I'm more thinking about app >>>>>> developers. >>>>>> >>>>>>> >>>>>>> So ODP will never ship a distribution that was configured with >>>>>>> --enable-deprecated-api. The only users of this feature will be >>>>>>> embedded applications that are customizing ODP to their own needs. >>>>>> >>>>>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping >> ODP >>>>>> to enable application development on that platform. They would >> surely >>>>>> want to enable deprecated API (because otherwise old applications >>>>>> developed on that platform can stop building). But I'd expect that >> it is >>>>>> possible for the application developer to build an application >> checking >>>>>> that he does not use deprecated API anymore. >>>>> >>>>> This is really no different than supporting multiple levels of, say, >>>>> the GCC compiler. Or any other package. At some point the old >> releases >>>>> are no longer supported, but for some time you can have multiple >>>>> levels available at the same time and you just use the one that you >>>>> need. >>>> >>>> We might want to consult maintainers. But from my previous experience, >>>> supporting several 'levels' is a significant headache, that most of >>>> maintainers would like to stand away from. Moreover, even if several >>>> versions are provided by distro, app developers still would like to >> have >>>> 'migration' path. Consider the way deprecated API are implemented e.g. >>>> in Gtk, Qt or other app frameworks. >>> >>> The migration path is very straightforward: Don't move until you're >>> ready to move. When you are ready to move you change your application >>> to use the new preferred APIs. >>> >>> Will some wait until they are forced to move because the older >>> releases are no longer distributed? Sure. But that's just business as >>> usual. The point is that distributions can choose to distribute >>> whatever level(s) of ODP they wish. Our biggest problem is more likely >>> to be not that they won't distribute older releases but the lag in >>> getting them to distribute newer releases. >>> >>> It also points out that we really shouldn't be deprecating APIs in the >>> first place. These should be very rare instances, not something so >>> commonplace that we need a general framework to make it convenient to >>> deprecate a bunch of stuff each release. An API is "forever" and we >>> need to be mindful of that when we pour the concrete. >>> >>> As a practical matter, the main reason for deprecating an API is >>> because it is superseded by a better way to do something. But keeping >>> the older API around just means that applications don't get the >>> advantage of using the newer way until such time as we get tired of >>> carrying around the old baggage and the old forms get removed. So >>> deprecation is more a documentation than a code issue, which is all >>> that the original ODP_DEPRECATED() macros were intended to do. >>> >>> A likely more controversial issue is that we've stated that ODP makes >>> no ABI compatibility claims from one release to the next. It's assumed >>> that applications will recompile to move from ODP Release N to ODP >>> Release N+1. In ODP, ABI compatibility is a statement of compatibility >>> across different ODP implementations of a given API release, not >>> across multiple API releases. >>> >> >> I have some more thoughts on deprecating api / documentation. >> >> First lets clearly define what deprecation as: >> Feature of making api functions of struct element for limited support >> by ODP implementer in future. > > > No. Deprecation is part of API specification. For example, > > API spec v1.20 could define: > > typedef struct odp_foo_bar_t { > /** This is foo*/ > uint8_t foo; > } odp_foo_bar_t; > > > API spec v1.30 could define: > > typedef struct odp_foo_bar_t { > /** @deprecated Foo is deprecated, use bar instead. */ > uint8_t ODP_DEPRECATE(foo); > > /** This is bar */ > uint8_t bar; > } odp_foo_bar_t; > > > By default, ODP_DEPRECATE() macro makes 'foo' unusable for the application. Each implementation may choose to support only the default (foo unusable), or also support all deprecated stuff (foo usable). API spec has only two modes: with or without deprecated stuff. If you compile with deprecated, the above example looks like this to the application: > > typedef struct odp_foo_bar_t { > /** @deprecated Foo is deprecated, use bar instead. */ > uint8_t foo; > > /** This is bar */ > uint8_t bar; > } odp_foo_bar_t; > > > ... and without deprecation (the default) it looks like this > > typedef struct odp_foo_bar_t { > /** @deprecated Foo is deprecated, use bar instead. */ > uint8_t ____dont_use_this_since_its_deprecated_foo; > > /** This is bar */ > uint8_t bar; > } odp_foo_bar_t; > > > Note: struct size does not change between the two modes. > > > >> >> In that case: >> - Upstream (Linaro/odp) has to provide common best practice way to do >> that. >> - All api headers have to remain the same as main repo has, only some >> function can be marked as deprecated. >> - Each ODP implementer can choose which functions he marks as deprecated >> and for how long. The same for data structures. > > > Deprecated APIs are part of API spec. So, implementation cannot add or remove the number of deprecated APIs. It can just choose to support all of those, or none. > > >> >> What is delivery? How odp is shipped? >> - library + headers (more common for enterprise software). >> - git sources (more common for embedded). > > API spec is the primary deliverable of ODP project. Deprecation spec does not include how SW is delivered, it just defines those things in API that are invisible/visible to the application, when deprecation support is off/on. It's a business choice for an implementation / class of implementations to support deprecated APIs. > > >> >> In my understanding current approach with #idefs in api does not work >> due to it's impossible to quickly compare headers with main line code >> if everybody will start to mark unmark fields as deprecated >> (implementers and main line at the same time.) > > The spec does not contain #ifdef. It marks deprecated stuff with ODP_DEPRECATE(). An implementation must not add / remove those. The spec files are the same for everybody. > > >> >> I see a way how we can get more clear definition here: >> - ODP mainline provides documentation and ways how to mark deprecated >> function or types. > > This is the ODP_DEPRECATE() macro. > > >> - ./configure has to have --enable-deprecated symbol > > It depends on implementation which build system is used, but obviously it needs a way to enable deprecated APIs if it supports those. > > >> - ./include/api headers have to be generated on ./configure stage >> regarding if deprecated symbols are supported or not. That include >> headers have to be shipped with library binary to package. > > This is no different from selecting if ABI compat is used. Both need to be selected at build time (at latest). Obviously, for distros we always build with ABI compat, we need to decide our position on deprecated APIs. Maybe those are always off (as the default mode suggests). > > >> - all deprecated api have to be in separate folder to be easy to remove >> something like ./include/api-deprecated/ >> - Doxygen note has to have all deprecated symbols documented. > > > Separate folders are not needed. API spec files mark deprecated definitions with both ODP_DEPRECATE() and @deprecated tag. Implementations re-use the spec files as-is, or otherwise make sure that the same definitions are visible/not-visible to the application through ODP API. > > > -Petri > So use case is only one - if you have source code for application based on api X and you want to jump to api level X+Y and if old api is supported as deprecated then app should compile and run without modifications. Right? In that case ABI compatibility more like will be broken but old API has to be supported. Maxim. >> >> >> Now when we talk about real delivery we talk only about Long Term >> Support releases. When we do this release we can discuss which api >> people still want to support as deprecated. In that case we enable >> this apis in the build. But apps developers will know that these apis >> will no be valid on next release. >> >> In my understanding it has to solve patch original api headers with >> deprecated macro and makes maintains more easy. >> >> Best regards, >> Maxim. >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >>
On Tue, May 2, 2017 at 9:20 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 05/02/17 14:43, Savolainen, Petri (Nokia - FI/Espoo) wrote: > > > > > >> -----Original Message----- > >> From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of > maxim > >> Sent: Tuesday, May 02, 2017 1:06 PM > >> To: lng-odp@lists.linaro.org > >> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >> > >> On ????., ??????. 12, 2017 at 10:33:24 -0500, Bill Fischofer wrote: > >>> On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov > >>> <dmitry.ereminsolenikov@linaro.org> wrote: > >>>> On 12.04.2017 17:24, Bill Fischofer wrote: > >>>>> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov > >>>>> <dmitry.ereminsolenikov@linaro.org> wrote: > >>>>>> On 12.04.2017 15:21, Bill Fischofer wrote: > >>>>>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov > >>>>>>> <dmitry.ereminsolenikov@linaro.org> wrote: > >>>>>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote: > >>>>>>>>> > >>>>>>>>> > >>>>>>>>>> -----Original Message----- > >>>>>>>>>> From: Dmitry Eremin-Solenikov > >> [mailto:dmitry.ereminsolenikov@linaro.org] > >>>>>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM > >>>>>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng- > >>>>>>>>>> odp@lists.linaro.org > >>>>>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros > >>>>>>>>>> > >>>>>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote: > >>>>>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC > >> __attribute__) > >>>>>>>>>> with > >>>>>>>>>>> compiler independent mechanism to control if deprecated API > >> definitions > >>>>>>>>>> are > >>>>>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both > >> in > >>>>>>>>>> application > >>>>>>>>>>> and implementation to check if deprecated APIs are enabled. By > >> default > >>>>>>>>>> those are > >>>>>>>>>>> disabled. Implementation may optimize the normal (new API) code > >> path. > >>>>>>>>>>> > >>>>>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that > >> data > >>>>>>>>>> structure > >>>>>>>>>>> sizes are equal on both options. This enables implementation to > >> serve > >>>>>>>>>> both > >>>>>>>>>>> options with a single library (if it wishes to do so). > >>>>>>>>>> > >>>>>>>>>> My main question remains as it was before: is it possible for > >> the > >>>>>>>>>> distribution to supply (unoptimized) ODP binary and headers and > >> then for > >>>>>>>>>> the application to select if it builds with or without > >> deprecated API > >>>>>>>>>> using that binary/headers? > >>>>>>>>> > >>>>>>>>> > >>>>>>>>> Yes. This patch set keeps the same struct fields/etc for both > >> modes - only the names are scrambled (with __deprecated_ prefix) when > >> deprecated APIs are not supported (the default). > >>>>>>>> > >>>>>>>> If so. Consider I have built and installed ODP headers & binary > >> built > >>>>>>>> with --enable-deprecated-api. > >>>>>>>> > >>>>>>>> How do I build: > >>>>>>>> > >>>>>>>> - application that uses deprecated API? > >>>>>>>> [I assume that the answer to this question is trivial: just > >> build as is]. > >>>>>>>> > >>>>>>>> - application that wants to be sure that it does not use > >> deprecated API? > >>>>>>> > >>>>>>> As a practical matter, the support of deprecated APIs is similar to > >>>>>>> the current provision for debug builds (--enable-debug and > >>>>>>> --enable-debug-print in the current ./configure script). These > >> really > >>>>>>> are only of significance in the embedded space. > >>>>>> > >>>>>> Or for application developers. > >>>>>> > >>>>>>> In the cloud profile, > >>>>>>> applications use whatever ODP release(s) are installed on the > >> system > >>>>>>> and the normal library-matchings are used to ensure that > >> applications > >>>>>>> built for Release X are paired with library .so files compatible > >> with > >>>>>>> that release. In this case, there are no deprecated APIs since > >>>>>>> applications only move to newer ODP release levels when they are > >>>>>>> ready. A cloud host system may specify the minimum ODP release > >> level > >>>>>>> available on it, and that determines when laggards need to upgrade. > >>>>>> > >>>>>> Yep. That is the deployed ODP release. It is optimized for speed, it > >> is > >>>>>> optimized for that exact platform, etc. I'm more thinking about app > >>>>>> developers. > >>>>>> > >>>>>>> > >>>>>>> So ODP will never ship a distribution that was configured with > >>>>>>> --enable-deprecated-api. The only users of this feature will be > >>>>>>> embedded applications that are customizing ODP to their own needs. > >>>>>> > >>>>>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping > >> ODP > >>>>>> to enable application development on that platform. They would > >> surely > >>>>>> want to enable deprecated API (because otherwise old applications > >>>>>> developed on that platform can stop building). But I'd expect that > >> it is > >>>>>> possible for the application developer to build an application > >> checking > >>>>>> that he does not use deprecated API anymore. > >>>>> > >>>>> This is really no different than supporting multiple levels of, say, > >>>>> the GCC compiler. Or any other package. At some point the old > >> releases > >>>>> are no longer supported, but for some time you can have multiple > >>>>> levels available at the same time and you just use the one that you > >>>>> need. > >>>> > >>>> We might want to consult maintainers. But from my previous experience, > >>>> supporting several 'levels' is a significant headache, that most of > >>>> maintainers would like to stand away from. Moreover, even if several > >>>> versions are provided by distro, app developers still would like to > >> have > >>>> 'migration' path. Consider the way deprecated API are implemented e.g. > >>>> in Gtk, Qt or other app frameworks. > >>> > >>> The migration path is very straightforward: Don't move until you're > >>> ready to move. When you are ready to move you change your application > >>> to use the new preferred APIs. > >>> > >>> Will some wait until they are forced to move because the older > >>> releases are no longer distributed? Sure. But that's just business as > >>> usual. The point is that distributions can choose to distribute > >>> whatever level(s) of ODP they wish. Our biggest problem is more likely > >>> to be not that they won't distribute older releases but the lag in > >>> getting them to distribute newer releases. > >>> > >>> It also points out that we really shouldn't be deprecating APIs in the > >>> first place. These should be very rare instances, not something so > >>> commonplace that we need a general framework to make it convenient to > >>> deprecate a bunch of stuff each release. An API is "forever" and we > >>> need to be mindful of that when we pour the concrete. > >>> > >>> As a practical matter, the main reason for deprecating an API is > >>> because it is superseded by a better way to do something. But keeping > >>> the older API around just means that applications don't get the > >>> advantage of using the newer way until such time as we get tired of > >>> carrying around the old baggage and the old forms get removed. So > >>> deprecation is more a documentation than a code issue, which is all > >>> that the original ODP_DEPRECATED() macros were intended to do. > >>> > >>> A likely more controversial issue is that we've stated that ODP makes > >>> no ABI compatibility claims from one release to the next. It's assumed > >>> that applications will recompile to move from ODP Release N to ODP > >>> Release N+1. In ODP, ABI compatibility is a statement of compatibility > >>> across different ODP implementations of a given API release, not > >>> across multiple API releases. > >>> > >> > >> I have some more thoughts on deprecating api / documentation. > >> > >> First lets clearly define what deprecation as: > >> Feature of making api functions of struct element for limited support > >> by ODP implementer in future. > > > > > > No. Deprecation is part of API specification. For example, > > > > API spec v1.20 could define: > > > > typedef struct odp_foo_bar_t { > > /** This is foo*/ > > uint8_t foo; > > } odp_foo_bar_t; > > > > > > API spec v1.30 could define: > > > > typedef struct odp_foo_bar_t { > > /** @deprecated Foo is deprecated, use bar instead. */ > > uint8_t ODP_DEPRECATE(foo); > > > > /** This is bar */ > > uint8_t bar; > > } odp_foo_bar_t; > > > > > > By default, ODP_DEPRECATE() macro makes 'foo' unusable for the > application. Each implementation may choose to support only the default > (foo unusable), or also support all deprecated stuff (foo usable). API spec > has only two modes: with or without deprecated stuff. If you compile with > deprecated, the above example looks like this to the application: > > > > typedef struct odp_foo_bar_t { > > /** @deprecated Foo is deprecated, use bar instead. */ > > uint8_t foo; > > > > /** This is bar */ > > uint8_t bar; > > } odp_foo_bar_t; > > > > > > ... and without deprecation (the default) it looks like this > > > > typedef struct odp_foo_bar_t { > > /** @deprecated Foo is deprecated, use bar instead. */ > > uint8_t ____dont_use_this_since_its_deprecated_foo; > > > > /** This is bar */ > > uint8_t bar; > > } odp_foo_bar_t; > > > > > > Note: struct size does not change between the two modes. > > > > > > > >> > >> In that case: > >> - Upstream (Linaro/odp) has to provide common best practice way to do > >> that. > >> - All api headers have to remain the same as main repo has, only some > >> function can be marked as deprecated. > >> - Each ODP implementer can choose which functions he marks as deprecated > >> and for how long. The same for data structures. > > > > > > Deprecated APIs are part of API spec. So, implementation cannot add or > remove the number of deprecated APIs. It can just choose to support all of > those, or none. > > > > > >> > >> What is delivery? How odp is shipped? > >> - library + headers (more common for enterprise software). > >> - git sources (more common for embedded). > > > > API spec is the primary deliverable of ODP project. Deprecation spec > does not include how SW is delivered, it just defines those things in API > that are invisible/visible to the application, when deprecation support is > off/on. It's a business choice for an implementation / class of > implementations to support deprecated APIs. > > > > > >> > >> In my understanding current approach with #idefs in api does not work > >> due to it's impossible to quickly compare headers with main line code > >> if everybody will start to mark unmark fields as deprecated > >> (implementers and main line at the same time.) > > > > The spec does not contain #ifdef. It marks deprecated stuff with > ODP_DEPRECATE(). An implementation must not add / remove those. The spec > files are the same for everybody. > > > > > >> > >> I see a way how we can get more clear definition here: > >> - ODP mainline provides documentation and ways how to mark deprecated > >> function or types. > > > > This is the ODP_DEPRECATE() macro. > > > > > >> - ./configure has to have --enable-deprecated symbol > > > > It depends on implementation which build system is used, but obviously > it needs a way to enable deprecated APIs if it supports those. > > > > > >> - ./include/api headers have to be generated on ./configure stage > >> regarding if deprecated symbols are supported or not. That include > >> headers have to be shipped with library binary to package. > > > > This is no different from selecting if ABI compat is used. Both need to > be selected at build time (at latest). Obviously, for distros we always > build with ABI compat, we need to decide our position on deprecated APIs. > Maybe those are always off (as the default mode suggests). > > > > > >> - all deprecated api have to be in separate folder to be easy to remove > >> something like ./include/api-deprecated/ > >> - Doxygen note has to have all deprecated symbols documented. > > > > > > Separate folders are not needed. API spec files mark deprecated > definitions with both ODP_DEPRECATE() and @deprecated tag. Implementations > re-use the spec files as-is, or otherwise make sure that the same > definitions are visible/not-visible to the application through ODP API. > > > > > > -Petri > > > > So use case is only one - if you have source code for application based > on api X and you want to jump to api level X+Y and if old api is > supported as deprecated then app should compile and run without > modifications. Right? > > In that case ABI compatibility more like will be broken but old API has > to be supported. > Inter-release ABI compatibility is something ODP has explicitly said is not a design goal. If we want to change that we need to discuss that as a separate topic. The goal of ABI compatibility in ODP is for binary application portability across different ODP implementations of the same API level. > > Maxim. > > > >> > >> > >> Now when we talk about real delivery we talk only about Long Term > >> Support releases. When we do this release we can discuss which api > >> people still want to support as deprecated. In that case we enable > >> this apis in the build. But apps developers will know that these apis > >> will no be valid on next release. > >> > >> In my understanding it has to solve patch original api headers with > >> deprecated macro and makes maintains more easy. > >> > >> Best regards, > >> Maxim. > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >> > >
For this series: Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> On Thu, Mar 30, 2017 at 8:58 AM, Petri Savolainen < petri.savolainen@linaro.org> wrote: > Replaced ODP_DEPRECATED macro (which was based on GCC __attribute__) with > compiler independent mechanism to control if deprecated API definitions are > visible to the application. ODP_DEPRECATED_API can be used both in > application > and implementation to check if deprecated APIs are enabled. By default > those are > disabled. Implementation may optimize the normal (new API) code path. > > ODP_DEPRECATE() macro is used to rename definitions, so that data structure > sizes are equal on both options. This enables implementation to serve both > options with a single library (if it wishes to do so). > > > Petri Savolainen (4): > api: hints: remove ODP_DEPRECATED from API > api: deprecated: add configure option and macros > test: crypto: remove references to deprecated crypto apis > api: crypto: enforce deprecated API status > > configure.ac | 19 +++++++- > doc/application-api-guide/api_guide_lines.dox | 6 +-- > doc/platform-api-guide/Doxyfile | 1 + > doc/process-guide/release-guide.adoc | 6 +-- > example/ipsec/odp_ipsec_misc.h | 4 +- > example/ipsec/odp_ipsec_sa_db.c | 4 +- > example/ipsec/odp_ipsec_stream.c | 6 +-- > include/odp/api/spec/.gitignore | 1 + > include/odp/api/spec/crypto.h | 29 +++++++------ > include/odp/api/spec/deprecated.h.in | 50 > ++++++++++++++++++++++ > include/odp/api/spec/hints.h | 6 --- > include/odp_api.h | 1 + > platform/Makefile.inc | 1 + > platform/linux-generic/Makefile.am | 1 + > .../linux-generic/include/odp/api/deprecated.h | 26 +++++++++++ > platform/linux-generic/odp_crypto.c | 45 > +++++++++++++------ > test/common_plat/performance/odp_crypto.c | 4 +- > 17 files changed, 161 insertions(+), 49 deletions(-) > create mode 100644 include/odp/api/spec/deprecated.h.in > create mode 100644 platform/linux-generic/include/odp/api/deprecated.h > > -- > 2.8.1 > >
Let us say:
API spec v1.20 could define:
typedef struct odp_foo_bar_t {
/** This is foo*/
uint8_t foo;
} odp_foo_bar_t;
API spec v1.30 could define:
typedef struct odp_foo_bar_t {
/** @deprecated Foo is deprecated, use bar instead. */
uint8_t foo;
/** This is bar */
uint8_t bar;
} odp_foo_bar_t;
Application (with out any changes) moves to v1.30, it still compiles and runs.
Application writer checks what is deprecated by searching for
'@deprecated' or looking at the release notes and changes his code for
v1.30.
On 2 May 2017 at 06:43, Savolainen, Petri (Nokia - FI/Espoo)
<petri.savolainen@nokia.com> wrote:
>
>
>> -----Original Message-----
>> From: lng-odp [mailto:lng-odp-bounces@lists.linaro.org] On Behalf Of maxim
>> Sent: Tuesday, May 02, 2017 1:06 PM
>> To: lng-odp@lists.linaro.org
>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros
>>
>> On ????., ??????. 12, 2017 at 10:33:24 -0500, Bill Fischofer wrote:
>> > On Wed, Apr 12, 2017 at 10:05 AM, Dmitry Eremin-Solenikov
>> > <dmitry.ereminsolenikov@linaro.org> wrote:
>> > > On 12.04.2017 17:24, Bill Fischofer wrote:
>> > >> On Wed, Apr 12, 2017 at 8:22 AM, Dmitry Eremin-Solenikov
>> > >> <dmitry.ereminsolenikov@linaro.org> wrote:
>> > >>> On 12.04.2017 15:21, Bill Fischofer wrote:
>> > >>>> On Wed, Apr 12, 2017 at 7:11 AM, Dmitry Eremin-Solenikov
>> > >>>> <dmitry.ereminsolenikov@linaro.org> wrote:
>> > >>>>> On 12.04.2017 14:50, Savolainen, Petri (Nokia - FI/Espoo) wrote:
>> > >>>>>>
>> > >>>>>>
>> > >>>>>>> -----Original Message-----
>> > >>>>>>> From: Dmitry Eremin-Solenikov
>> [mailto:dmitry.ereminsolenikov@linaro.org]
>> > >>>>>>> Sent: Wednesday, April 12, 2017 2:32 PM
>> > >>>>>>> To: Petri Savolainen <petri.savolainen@linaro.org>; lng-
>> > >>>>>>> odp@lists.linaro.org
>> > >>>>>>> Subject: Re: [lng-odp] [API-NEXT PATCH v2 0/4] Deprecated macros
>> > >>>>>>>
>> > >>>>>>> On 30.03.2017 16:58, Petri Savolainen wrote:
>> > >>>>>>>> Replaced ODP_DEPRECATED macro (which was based on GCC
>> __attribute__)
>> > >>>>>>> with
>> > >>>>>>>> compiler independent mechanism to control if deprecated API
>> definitions
>> > >>>>>>> are
>> > >>>>>>>> visible to the application. ODP_DEPRECATED_API can be used both
>> in
>> > >>>>>>> application
>> > >>>>>>>> and implementation to check if deprecated APIs are enabled. By
>> default
>> > >>>>>>> those are
>> > >>>>>>>> disabled. Implementation may optimize the normal (new API) code
>> path.
>> > >>>>>>>>
>> > >>>>>>>> ODP_DEPRECATE() macro is used to rename definitions, so that
>> data
>> > >>>>>>> structure
>> > >>>>>>>> sizes are equal on both options. This enables implementation to
>> serve
>> > >>>>>>> both
>> > >>>>>>>> options with a single library (if it wishes to do so).
>> > >>>>>>>
>> > >>>>>>> My main question remains as it was before: is it possible for
>> the
>> > >>>>>>> distribution to supply (unoptimized) ODP binary and headers and
>> then for
>> > >>>>>>> the application to select if it builds with or without
>> deprecated API
>> > >>>>>>> using that binary/headers?
>> > >>>>>>
>> > >>>>>>
>> > >>>>>> Yes. This patch set keeps the same struct fields/etc for both
>> modes - only the names are scrambled (with __deprecated_ prefix) when
>> deprecated APIs are not supported (the default).
>> > >>>>>
>> > >>>>> If so. Consider I have built and installed ODP headers & binary
>> built
>> > >>>>> with --enable-deprecated-api.
>> > >>>>>
>> > >>>>> How do I build:
>> > >>>>>
>> > >>>>> - application that uses deprecated API?
>> > >>>>> [I assume that the answer to this question is trivial: just
>> build as is].
>> > >>>>>
>> > >>>>> - application that wants to be sure that it does not use
>> deprecated API?
>> > >>>>
>> > >>>> As a practical matter, the support of deprecated APIs is similar to
>> > >>>> the current provision for debug builds (--enable-debug and
>> > >>>> --enable-debug-print in the current ./configure script). These
>> really
>> > >>>> are only of significance in the embedded space.
>> > >>>
>> > >>> Or for application developers.
>> > >>>
>> > >>>> In the cloud profile,
>> > >>>> applications use whatever ODP release(s) are installed on the
>> system
>> > >>>> and the normal library-matchings are used to ensure that
>> applications
>> > >>>> built for Release X are paired with library .so files compatible
>> with
>> > >>>> that release. In this case, there are no deprecated APIs since
>> > >>>> applications only move to newer ODP release levels when they are
>> > >>>> ready. A cloud host system may specify the minimum ODP release
>> level
>> > >>>> available on it, and that determines when laggards need to upgrade.
>> > >>>
>> > >>> Yep. That is the deployed ODP release. It is optimized for speed, it
>> is
>> > >>> optimized for that exact platform, etc. I'm more thinking about app
>> > >>> developers.
>> > >>>
>> > >>>>
>> > >>>> So ODP will never ship a distribution that was configured with
>> > >>>> --enable-deprecated-api. The only users of this feature will be
>> > >>>> embedded applications that are customizing ODP to their own needs.
>> > >>>
>> > >>> I'm thinking about SuSe, Canonical, RedHat or anybody else shipping
>> ODP
>> > >>> to enable application development on that platform. They would
>> surely
>> > >>> want to enable deprecated API (because otherwise old applications
>> > >>> developed on that platform can stop building). But I'd expect that
>> it is
>> > >>> possible for the application developer to build an application
>> checking
>> > >>> that he does not use deprecated API anymore.
>> > >>
>> > >> This is really no different than supporting multiple levels of, say,
>> > >> the GCC compiler. Or any other package. At some point the old
>> releases
>> > >> are no longer supported, but for some time you can have multiple
>> > >> levels available at the same time and you just use the one that you
>> > >> need.
>> > >
>> > > We might want to consult maintainers. But from my previous experience,
>> > > supporting several 'levels' is a significant headache, that most of
>> > > maintainers would like to stand away from. Moreover, even if several
>> > > versions are provided by distro, app developers still would like to
>> have
>> > > 'migration' path. Consider the way deprecated API are implemented e.g.
>> > > in Gtk, Qt or other app frameworks.
>> >
>> > The migration path is very straightforward: Don't move until you're
>> > ready to move. When you are ready to move you change your application
>> > to use the new preferred APIs.
>> >
>> > Will some wait until they are forced to move because the older
>> > releases are no longer distributed? Sure. But that's just business as
>> > usual. The point is that distributions can choose to distribute
>> > whatever level(s) of ODP they wish. Our biggest problem is more likely
>> > to be not that they won't distribute older releases but the lag in
>> > getting them to distribute newer releases.
>> >
>> > It also points out that we really shouldn't be deprecating APIs in the
>> > first place. These should be very rare instances, not something so
>> > commonplace that we need a general framework to make it convenient to
>> > deprecate a bunch of stuff each release. An API is "forever" and we
>> > need to be mindful of that when we pour the concrete.
>> >
>> > As a practical matter, the main reason for deprecating an API is
>> > because it is superseded by a better way to do something. But keeping
>> > the older API around just means that applications don't get the
>> > advantage of using the newer way until such time as we get tired of
>> > carrying around the old baggage and the old forms get removed. So
>> > deprecation is more a documentation than a code issue, which is all
>> > that the original ODP_DEPRECATED() macros were intended to do.
>> >
>> > A likely more controversial issue is that we've stated that ODP makes
>> > no ABI compatibility claims from one release to the next. It's assumed
>> > that applications will recompile to move from ODP Release N to ODP
>> > Release N+1. In ODP, ABI compatibility is a statement of compatibility
>> > across different ODP implementations of a given API release, not
>> > across multiple API releases.
>> >
>>
>> I have some more thoughts on deprecating api / documentation.
>>
>> First lets clearly define what deprecation as:
>> Feature of making api functions of struct element for limited support
>> by ODP implementer in future.
>
>
> No. Deprecation is part of API specification. For example,
>
> API spec v1.20 could define:
>
> typedef struct odp_foo_bar_t {
> /** This is foo*/
> uint8_t foo;
> } odp_foo_bar_t;
>
>
> API spec v1.30 could define:
>
> typedef struct odp_foo_bar_t {
> /** @deprecated Foo is deprecated, use bar instead. */
> uint8_t ODP_DEPRECATE(foo);
>
> /** This is bar */
> uint8_t bar;
> } odp_foo_bar_t;
>
>
> By default, ODP_DEPRECATE() macro makes 'foo' unusable for the application. Each implementation may choose to support only the default (foo unusable), or also support all deprecated stuff (foo usable). API spec has only two modes: with or without deprecated stuff. If you compile with deprecated, the above example looks like this to the application:
>
> typedef struct odp_foo_bar_t {
> /** @deprecated Foo is deprecated, use bar instead. */
> uint8_t foo;
>
> /** This is bar */
> uint8_t bar;
> } odp_foo_bar_t;
>
>
> ... and without deprecation (the default) it looks like this
>
> typedef struct odp_foo_bar_t {
> /** @deprecated Foo is deprecated, use bar instead. */
> uint8_t ____dont_use_this_since_its_deprecated_foo;
>
> /** This is bar */
> uint8_t bar;
> } odp_foo_bar_t;
>
>
> Note: struct size does not change between the two modes.
>
>
>
>>
>> In that case:
>> - Upstream (Linaro/odp) has to provide common best practice way to do
>> that.
>> - All api headers have to remain the same as main repo has, only some
>> function can be marked as deprecated.
>> - Each ODP implementer can choose which functions he marks as deprecated
>> and for how long. The same for data structures.
>
>
> Deprecated APIs are part of API spec. So, implementation cannot add or remove the number of deprecated APIs. It can just choose to support all of those, or none.
>
>
>>
>> What is delivery? How odp is shipped?
>> - library + headers (more common for enterprise software).
>> - git sources (more common for embedded).
>
> API spec is the primary deliverable of ODP project. Deprecation spec does not include how SW is delivered, it just defines those things in API that are invisible/visible to the application, when deprecation support is off/on. It's a business choice for an implementation / class of implementations to support deprecated APIs.
>
>
>>
>> In my understanding current approach with #idefs in api does not work
>> due to it's impossible to quickly compare headers with main line code
>> if everybody will start to mark unmark fields as deprecated
>> (implementers and main line at the same time.)
>
> The spec does not contain #ifdef. It marks deprecated stuff with ODP_DEPRECATE(). An implementation must not add / remove those. The spec files are the same for everybody.
>
>
>>
>> I see a way how we can get more clear definition here:
>> - ODP mainline provides documentation and ways how to mark deprecated
>> function or types.
>
> This is the ODP_DEPRECATE() macro.
>
>
>> - ./configure has to have --enable-deprecated symbol
>
> It depends on implementation which build system is used, but obviously it needs a way to enable deprecated APIs if it supports those.
>
>
>> - ./include/api headers have to be generated on ./configure stage
>> regarding if deprecated symbols are supported or not. That include
>> headers have to be shipped with library binary to package.
>
> This is no different from selecting if ABI compat is used. Both need to be selected at build time (at latest). Obviously, for distros we always build with ABI compat, we need to decide our position on deprecated APIs. Maybe those are always off (as the default mode suggests).
>
>
>> - all deprecated api have to be in separate folder to be easy to remove
>> something like ./include/api-deprecated/
>> - Doxygen note has to have all deprecated symbols documented.
>
>
> Separate folders are not needed. API spec files mark deprecated definitions with both ODP_DEPRECATE() and @deprecated tag. Implementations re-use the spec files as-is, or otherwise make sure that the same definitions are visible/not-visible to the application through ODP API.
>
>
> -Petri
>
>>
>>
>> Now when we talk about real delivery we talk only about Long Term
>> Support releases. When we do this release we can discuss which api
>> people still want to support as deprecated. In that case we enable
>> this apis in the build. But apps developers will know that these apis
>> will no be valid on next release.
>>
>> In my understanding it has to solve patch original api headers with
>> deprecated macro and makes maintains more easy.
>>
>> Best regards,
>> Maxim.
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
On 03.05.2017 07:43, Honnappa Nagarahalli wrote: > Let us say: > > API spec v1.20 could define: > > typedef struct odp_foo_bar_t { > /** This is foo*/ > uint8_t foo; > } odp_foo_bar_t; > > > API spec v1.30 could define: > > typedef struct odp_foo_bar_t { > /** @deprecated Foo is deprecated, use bar instead. */ > uint8_t foo; > > /** This is bar */ > uint8_t bar; > } odp_foo_bar_t; > > Application (with out any changes) moves to v1.30, it still compiles and runs. > > Application writer checks what is deprecated by searching for > '@deprecated' or looking at the release notes and changes his code for > v1.30. This does not work. Nobody reads release notes in check for deprecated API until his piece of software breaks horribly. Even we do not do that, as demonstrated by Petri's patch 3/4. -- With best wishes Dmitry
On 2 May 2017 at 23:48, Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org> wrote: > On 03.05.2017 07:43, Honnappa Nagarahalli wrote: >> Let us say: >> >> API spec v1.20 could define: >> >> typedef struct odp_foo_bar_t { >> /** This is foo*/ >> uint8_t foo; >> } odp_foo_bar_t; >> >> >> API spec v1.30 could define: >> >> typedef struct odp_foo_bar_t { >> /** @deprecated Foo is deprecated, use bar instead. */ >> uint8_t foo; >> >> /** This is bar */ >> uint8_t bar; >> } odp_foo_bar_t; >> >> Application (with out any changes) moves to v1.30, it still compiles and runs. >> >> Application writer checks what is deprecated by searching for >> '@deprecated' or looking at the release notes and changes his code for >> v1.30. > > This does not work. Nobody reads release notes in check for deprecated > API until his piece of software breaks horribly. Even we do not do that, > as demonstrated by Petri's patch 3/4. If I am the manager who takes the decision to move to next release, I would first read the release notes to see what changed in the release (did someone make a bogus release?), I would look at the performance benchmarking report to see how this release affects the performance. This will save a ton of money and effort for the company and the team. This also needs to be done to understand how much effort (not just changing the code, testing in QA, support etc) is required and how much it will cost vs the benefits of moving to this release. If somebody wants to get a feel for the benefits, the code still compiles in the approach I have described. > -- > With best wishes > Dmitry