[RFC|oneMKL]Enable programmatic versioning

[vmalia]

Motivation

• Customers of oneMKL have requested a way to query the spec-compliance version of the implementation.
• The specification defines versioning but not in a programmatic way.
• Addresses Incomplete documentation about spec versioning #551

Inspiration

• SYCL versioning does not add the revision number:

---

• OpenMP specification itself keeps only MAJOR.MINOR version, with ongoing progress marked as Technical Report <number>. The _OPENMP macro provides a release date which maps onto a specification version, like this:

#define _OPENMP 202111    //202111: OpenMP 5.2

Proposal

• <MAJOR><MINOR><REVISION> such that MINOR and REVISION have two digits.
• Propose a macro for oneAPI and suggest a naming scheme for component macro names.

[rscohn2]

@uxlfoundation/oneapi-spec-maintainers: Please review this versioning proposal

[andrewtbarker]

I do not understand what is being proposed here.

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

[vmalia]

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

Yes. The goal of this RFC is to ensure that every implementation of the spec provides a numerically comparable value for its compliance with the spec version, through the proposed macros.

The implementation can additionally provide more ways to query that information, like APIs, but we do not mandate that in this proposal.

[vmalia]

@akukanov @mkrainiuk @rscohn2 @spencerpatty if everything looks okay, then please provide your approval. Thank you!

[spencerpatty]

Acceptable from my perspective. Approved

[vmalia]

@aelizaro @paveldyakov @lhuot @zettai-reido @sknepper can you please provide your reviews? Thank you!

[akukanov]

For your information, below is what I propose for defining a spec version macro for oneDPL. Use as you like; in case of feedback please comment in the PR #591.

A oneDPL implementation must define a preprocessor macro representing the version
of the oneDPL specification that the implementation is compliant with.

.. code:: cpp
  // Defined in <oneapi/dpl/version>
  #define ONEDPL_SPEC_VERSION /*implementation-defined*/

The ``ONEDPL_SPEC_VERSION`` macro must be defined to the decimal literal which value equals to
*major-spec-version* * 100 + *minor-spec-version*, where *major-spec-version* and *minor-spec-version*
are the major and the minor versions of the latest fully supported specification.
[*Example*: ``#define ONEDPL_SPEC_VERSION 104`` for the oneDPL specification 1.4.  -- *end example*]