Re: Version number macros

I would like to point out that the original SystemC API does not play well with compile-time issues. With TLM it is quite nice to be able to detect and deal with issues at compile-time. For example, when an incompatibility arises due to versions. #if works nicely to prevent wasted compilation cycles.

Also, this allows allows for writing code that is backward compatible, which becomes an issue as ESL is now adopted in many places.

Back in May of 2008, Charles Wilson made several very reasoned comments on this subject:
> The issue I have with the SystemC version information is that is does not provide a consistent, testable (compile time, run time) mechanism for determining and extracting the version information.
>
> I would assert that '20060505' is not the version, but rather the ISO 8601 date (YYYYMMDD) for the build. The version is '2.2.0'. SystemC version strings are incorrectly implemented.
>
> A developer implementing code that works with version of TLM should be able to conditionally compile using standard practices
>
> #if ( TLM_VERION_MAJOR < 2 ) <-- compile time
>
> or
>
> if ( tlm_version_major < 2 ) <-- run time
>
> and not by elaborating each release date string.
>
> Hence the choice of 'major.minor.patch[ (prerelease)]'.
>
> where:
>
> 2.0.0 (DR1) indicates a developer release
> 2.0.0 indicates a public of 2.0
> 2.0.1 indicates a patch to 2.0
> 2.1.0 indicates an feature update to 2.0
>
> I don't have an issue with including the build date in the string, with the note that it should not be used except for public releases.
>
> 2.0.0 (20080614) indicating a public release of 2.0 on 14 June 2008.
>
> -----------
>
> references:
>
> ISO 8601 <http://en.wikipedia.org/wiki/ISO_8601>
> version numbering <http://apr.apache.org/versioning.html>

I think he made a very strong case for this approach. Also note his reference to existing standards regarding both date formatting and versioning.

So I am strongly in favor of the TLM style versioning.

------------------------------------------------------
David C Black, XtremeEDA ESL Practice Leader
http://www.Xtreme-EDA.com
(Consulting, Services & Training for all your ESL, verification and DFT needs)
Voice: 512.850.4322 Skype:dcblack FAX: 888.467.4609

On Sep 28, 2010, at 6:16 AM, john.aynsley@doulos.com wrote:

> Jerome, All,
>
> Well, okay, but there is more to it than that. Here is the current SystemC API. Note that there are no macros, but the release string has a formal structure.
>
> namespace sc_core {
> const char* sc_copyright();
> const char* sc_version();
> const char* sc_release();
> }
>
> Function sc_release shall return an implementation-defined string of the following form:
> <major#>.<minor#>.<patch>-<originator>
> where <major#> represents the major release number, <minor#> represents the minor release
> number, <patch> represents the patch level, and <originator> represents the originator of the
> SystemC implementation. The intent is that this string should be machine-readable by any SystemC
> application that has an interest in checking the version or release number of the SystemC
> implementation.
> The character set for each of these four fields shall be as follows:
> a)The lower-case letters a-z
> b)The upper-case letters A-Z
> c)The decimal digits 0-9
> d)The underscore character _
>
> and here is the equivalent for TLM-2.0 (taken from the OSCI LRM, not just the implementation):
>
>
> namespace tlm
> {
> #define TLM_VERSION_MAJOR implementation_defined_number // For example, 2
> #define TLM_VERSION_MINOR implementation_defined_number // 0
> #define TLM_VERSION_PATCH implementation_defined_number // 1
> #define TLM_VERSION_ORIGINATOR implementation_defined_string // "OSCI"
> #define TLM_VERSION_RELEASE_DATE implementation_defined_date // "20090329"
> #define TLM_VERSION_PRERELEASE implementation_defined_string // "beta"
> #define TLM_IS_PRERELEASE implementation_defined_bool // TRUE
> #define TLM_VERSION implementation_defined_string // "2.0.1_beta-OSCI"
> #define TLM_COPYRIGHT implementation_defined_string
>
> const unsigned int tlm_version_major;
> const unsigned int tlm_version_minor;
> const unsigned int tlm_version_patch;
> const std::string tlm_version_originator;
> const std::string tlm_version_release_date;
> const std::string tlm_version_prerelease;
> const bool tlm_is_prerelease;
> const std::string tlm_version_string;
> const std::string tlm_copyright_string;
>
> inline const char* tlm_release();
> inline const char* tlm_version();
> inline const char* tlm_copyright();
> } // namespace tlm
>
>
> So the question is, do we want independent and parallel set of definitions for SystemC and TLM-2.0 releases, or do we want to merge them to give a single combined version? Having made that decision, do we want backward compatibility with the current 1666 and TLM-2.0 definitions?
>
> John A
>
>
>
> From: Jerome CORNET <jerome.cornet@st.com>
> To: "Philipp A. Hartmann" <philipp.hartmann@offis.de>
> Cc: john.aynsley@doulos.com, systemc-p1666-technical@eda.org
> Date: 16/09/2010 13:59
> Subject: Re: Version number macros
>
>
>
>
> Philipp,
>
> sorry for the delay in the answer: obviously you are right (I should
> have read the C++ norm more
> carefully).
>
> Agreed with all you said.
>
> Regards,
>
> Jerome
>
> On 9/15/2010 11:29 AM, Philipp A. Hartmann wrote:
> > Jerome,
> >
> > according to the C++ standard (17.4.3.1.2 [lib.global.names]), "certain
> > sets of names and function signatures are always reserved to the [C++]
> > implementation":
> >
> > - Each name that contains a double underscore (__) or begins with an
> > underscore followed by an upper-case letter (2.11) is reserved to
> > the implementation for any use.
> >
> > So I would prefer to have a macro name like SYSTEMC_IEEE_VERSION, or
> > SYSTEMC_IEEE_1666. SYSTEMC_VERSION should not be used, since this is
> > already used in (some) existing implementations.
> >
> > Thanks,
> > Philipp
> >
> > On 14/09/10 13:17, Jerome CORNET wrote:
> >> On 9/10/2010 4:07 PM, john.aynsley@doulos.com wrote:
> >>> Jerome,
> >>>
> >>> After process control extensions, the next priority on the list is
> >>> version number macros.
> >>>
> >>> You wrote:
> >>>
> >>> "Speaking of macros, I don't know if this has been planned, but it
> >>> would be great (and standard practice) to specify a way to retrieve
> >>> the version number of the norm that an implementation is following.
> >>> (In our case that would be either 2005 or 2010 for now).
> >>> The ISO C standard defines a macro __STDC__VERSION__ whose value is
> >>> 199901L (integer long) for C99.
> >>> ISO C++ also defines a macro, __cplusplus with value 199711L."
> >>>
> >>> Would you like to make a specific proposal?
> >>>
> >> John, All, (sorry for the slight delay)
> >>
> >> to me the best way is to follow the other standards' previous decisions
> >> unless
> >> we've got strong reasons for changing.
> >>
> >> So I would propose a macro (to allow test in #if) like this:
> >>
> >> __SYSTEMC_IEEE_VERSION with value 201001L
> >>
> >>
> >> with 2010 be for 1666-2010 and 01 being reserved for minor revisions (as
> >> it is used for c++).
> >>
> >> If someone prefer a variations in the name (__SYSTEM_VERSION or
> >> whatever), this is obviously
> >> also ok for us.
> >>
> >>
> >> Jerome
> >>
> >>
> >>
> >
>
>
>
>
> --
> This message has been scanned for viruses and
> dangerous content by MailScanner, and is
> believed to be clean.

-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.