Re: [DTrace-devel] [PATCH 2/2] Refactor the versioning handling system (consolidate data)

[Kris Van Hees <kris.van.hees@oracle.com>]

On Mon, Aug 18, 2025 at 04:45:31PM -0400, Eugene Loh wrote:
> With this patch, I get test regressions:
> 
>    test/unittest/options/tst.version.sh
>         Diff against expected:
>         -version is 2.0
>         +version is 2.0.3
> 
>     test/unittest/dtrace-util/tst.APIVersion.d
>         Diff against expected:
>         -dtrace: Oracle D 2.0
>         +dtrace: Oracle D 2.0.3

Test with v2.

> I did not run the test suite, so I do not know if other tests also fail.
> 
> Should something be done in libdtrace/Build with
>     libdtrace_VERSION := 2.0.0

No, see Nick's email on this a while back.  Library version is a different
thing.

> Should something be done in dtrace.spec with
>     Version:      2.0.3

No, that should be done separately because it is a distro-specific release
thing.  That should remain separate because (1) it is hard to automate its
value, and (2) we have to change the spec file for each release anyway.

> On 8/15/25 23:46, Kris Van Hees via DTrace-devel wrote:
> > Rather than having multiple data items that need to be updated whenever
> > a new version is released, a single entry in versions.list will now be
> > all that is needed.  The mkvers script generated the necessary defines,
> 
> s/generated/generates/
> 
> > and is also used to return the most recent release version to be used
> > in GNUmakefile.
> > 
> > Signed-off-by: Kris Van Hees <kris.van.hees@oracle.com>
> > ---
> >   GNUmakefile             |  2 +-
> >   libdtrace/.gitignore    |  1 +
> >   libdtrace/Build         |  7 +++-
> >   libdtrace/dt_version.h  | 83 ++---------------------------------------
> >   libdtrace/mkvers        | 68 +++++++++++++++++++++++++++++++++
> >   libdtrace/versions.list | 67 +++++++++++++++++++++++++++++++++
> >   6 files changed, 147 insertions(+), 81 deletions(-)
> >   create mode 100755 libdtrace/mkvers
> >   create mode 100644 libdtrace/versions.list
> > 
> > diff --git a/GNUmakefile b/GNUmakefile
> > index 7ad857f88..03687bf3f 100644
> > --- a/GNUmakefile
> > +++ b/GNUmakefile
> > @@ -14,7 +14,7 @@
> >   SHELL = /bin/bash
> >   PROJECT := dtrace
> > -VERSION := 2.0.3
> > +VERSION := $(shell ./libdtrace/mkvers -vrelease=1 libdtrace/versions.list)
> 
> I think to most readers "release=1" means, well, release 1.  How about
> renaming the variable.  Alternatively, just say "-vrelease=t".
> 
> >   # Verify supported hardware.
> > diff --git a/libdtrace/.gitignore b/libdtrace/.gitignore
> > index cf124ba1d..ebf6ac9b2 100644
> > --- a/libdtrace/.gitignore
> > +++ b/libdtrace/.gitignore
> > @@ -3,6 +3,7 @@ dt_errtags.c
> >   dt_grammar.[ch]
> >   dt_lex.c
> >   dt_names.c
> > +dt_versions_defs.h
> 
> Great.  But dt_versions_defs.h should also not survive "make clean".  So
> that also should be added (in the appropriate place).
> 
> >   errno.d
> >   regs.d
> >   signal.d
> > diff --git a/libdtrace/Build b/libdtrace/Build
> > index 164023bbc..a3c3a2e1a 100644
> > --- a/libdtrace/Build
> > +++ b/libdtrace/Build
> > @@ -73,7 +73,8 @@ libdtrace-build_SOURCES = dt_aggregate.c \
> >   			  dt_work.c \
> >   			  dt_xlator.c
> > -libdtrace-build_SRCDEPS := dt_grammar.h $(objdir)/dt_git_version.h
> > +libdtrace-build_SRCDEPS := dt_grammar.h dt_versions_defs.h \
> > +			   $(objdir)/dt_git_version.h
> >   SHLIBS += libdtrace
> > @@ -129,6 +130,10 @@ SHORTKERNELS := $(foreach kernel,$(KERNELS),$(shell printf %s $(kernel) | sed -e
> >   $(libdtrace-build_DIR)dt_errtags.c: $(libdtrace-build_DIR)dt_errtags.h $(libdtrace-build_DIR)/mkerrtags.sh
> >   	sh $(libdtrace-build_DIR)mkerrtags.sh < $(libdtrace-build_DIR)dt_errtags.h | sed -e 's/\\n/\n/g' > $@
> > +$(libdtrace-build_DIR)dt_versions_defs.h: $(libdtrace-build_DIR)versions.list
> > +	$(call describe-target,MKVERS,$@)
> > +	$(libdtrace-build_DIR)mkvers $< > $@
> > +
> >   $(libdtrace-build_DIR)%.h $(libdtrace-build_DIR)%.c: $(libdtrace-build_DIR)%.y
> >   	$(call describe-target,YACC,$(libdtrace-build_DIR)$*.c)
> >   	bison -o $(libdtrace-build_DIR)$*.c -d $(libdtrace-build_DIR)$*.y
> > diff --git a/libdtrace/dt_version.h b/libdtrace/dt_version.h
> > index 8dd252b08..5c1528266 100644
> > --- a/libdtrace/dt_version.h
> > +++ b/libdtrace/dt_version.h
> > @@ -13,83 +13,7 @@ extern "C" {
> >   #endif
> >   #include <dt_ident.h>
> > -
> > -/*
> > - * Versioning definitions
> > - *
> > - * These #defines are used in identifier tables to fill in the version fields
> > - * associated with each identifier.  The DT_VERS_* macros declare the encoded
> > - * integer values of all versions used so far.  DT_VERS_LATEST must correspond
> > - * to the latest version value among all versions exported by the D compiler.
> > - * DT_VERS_STRING must be an ASCII string that contains DT_VERS_LATEST within
> > - * it along with any suffixes (e.g. Beta).
> > - *
> 
> The comment about "any suffixes (e.g. Beta)" disappears here.  More
> significantly, the ability to have such suffixes seems to disappear.  Is
> that a notable loss?  The loss of capability should at least be noted.
> 
> > - * Refer to the Solaris Dynamic Tracing Guide Versioning chapter for an
> > - * explanation of these DTrace features and their values.
> > - *
> > - * When adding a new version:
> > - *  - Add a new DT_VERS_* macro
> > - *  - Add the new DT_VERS_* macro at the end of the DTRACE_VERSIONS macro
> > - *  - Set DT_VERS_LATEST to the new DT_VERS_*
> > - *  - Update DT_VERS_STRING to reflect the new version
> > - *
> > - * NOTE: Although the DTrace versioning scheme supports the labeling and
> > - *       introduction of incompatible changes (e.g. dropping an interface in a
> > - *       major release), the libdtrace code does not currently support this.
> > - *       All versions are assumed to strictly inherit from one another.  If
> > - *       we ever need to provide divergent interfaces, this will need work.
> > - *
> > - * The version number should be increased for every customer visible release
> > - * of DTrace.
> > - *  - The major number should be incremented when a fundamental change has been
> > - *    made that would affect all consumers, and would reflect sweeping changes
> > - *    to DTrace or the D language.
> > - *  - The minor number should be incremented when a change is introduced that
> > - *    could break scripts that had previously worked; for example, adding a new
> > - *    built-in variable could break a script which was already using that
> > - *    identifier.
> > - *  - The micro number should be changed when introducing functionality changes
> > - *    or major bug fixes that do not affect backward compatibility -- this is
> > - *    merely to make capabilities easily determined from the version number.
> > - *    Minor bugs do not require any modification to the version number.
> > - */
> > -#define	DT_VERS_1_0	DT_VERSION_NUMBER(1, 0, 0)
> > -#define	DT_VERS_1_1	DT_VERSION_NUMBER(1, 1, 0)
> > -#define	DT_VERS_1_2	DT_VERSION_NUMBER(1, 2, 0)
> > -#define	DT_VERS_1_2_1	DT_VERSION_NUMBER(1, 2, 1)
> > -#define	DT_VERS_1_2_2	DT_VERSION_NUMBER(1, 2, 2)
> > -#define	DT_VERS_1_3	DT_VERSION_NUMBER(1, 3, 0)
> > -#define	DT_VERS_1_4	DT_VERSION_NUMBER(1, 4, 0)
> > -#define	DT_VERS_1_4_1	DT_VERSION_NUMBER(1, 4, 1)
> > -#define	DT_VERS_1_5	DT_VERSION_NUMBER(1, 5, 0)
> > -#define	DT_VERS_1_6	DT_VERSION_NUMBER(1, 6, 0)
> > -#define	DT_VERS_1_6_1	DT_VERSION_NUMBER(1, 6, 1)
> > -#define	DT_VERS_1_6_2	DT_VERSION_NUMBER(1, 6, 2)
> > -#define	DT_VERS_1_6_3	DT_VERSION_NUMBER(1, 6, 3)
> > -#define	DT_VERS_1_6_4	DT_VERSION_NUMBER(1, 6, 4)
> > -#define	DT_VERS_2_0	DT_VERSION_NUMBER(2, 0, 0)
> > -#define	DT_VERS_2_0_1	DT_VERSION_NUMBER(2, 0, 1)
> > -
> > -#define DTRACE_VERSIONS	{ \
> > -	DT_VERS_1_0,	/* D API 1.0.0 (PSARC 2001/466) Solaris 10 FCS */ \
> > -	DT_VERS_1_1,	/* D API 1.1.0 Solaris Express 6/05 */ \
> > -	DT_VERS_1_2,	/* D API 1.2.0 Solaris 10 Update 1 */ \
> > -	DT_VERS_1_2_1,	/* D API 1.2.1 Solaris Express 4/06 */ \
> > -	DT_VERS_1_2_2,	/* D API 1.2.2 Solaris Express 6/06 */ \
> > -	DT_VERS_1_3,	/* D API 1.3 Solaris Express 10/06 */ \
> > -	DT_VERS_1_4,	/* D API 1.4 Solaris Express 2/07 */ \
> > -	DT_VERS_1_4_1,	/* D API 1.4.1 Solaris Express 4/07 */ \
> > -	DT_VERS_1_5,	/* D API 1.5 Solaris Express 7/07 */ \
> > -	DT_VERS_1_6,	/* D API 1.6 */ \
> > -	DT_VERS_1_6_1,	/* D API 1.6.1 */ \
> > -	DT_VERS_1_6_2,	/* D API 1.6.2 */ \
> > -	DT_VERS_1_6_3,	/* D API 1.6.3 */ \
> > -	DT_VERS_1_6_4,	/* D API 1.6.4 */ \
> > -	DT_VERS_2_0,	/* D API 2.0 */ \
> > -}
> > -
> > -#define	DT_VERS_LATEST	DT_VERS_2_0_1
> > -#define	DT_VERS_STRING	"Oracle D 2.0"
> > +#include "dt_versions_defs.h"
> >   /*
> >    * Interfaces for parsing and handling DTrace version strings.  Version binding
> > @@ -112,8 +36,9 @@ extern "C" {
> >   typedef uint32_t dt_version_t;
> > -extern const dt_version_t _dtrace_versions[];
> > -extern const char *const _dtrace_version;
> > +extern const dt_version_t	_dtrace_versions[];
> > +extern const char *const	_dtrace_version;
> > +extern const dt_version_t	_dtrace_vers_latest;
> 
> What is _dtrace_vers_latest for?
> 
> >   extern char *dt_version_num2str(dt_version_t, char *, size_t);
> >   extern int dt_version_str2num(const char *, dt_version_t *);
> > diff --git a/libdtrace/mkvers b/libdtrace/mkvers
> > new file mode 100755
> > index 000000000..c45617773
> > --- /dev/null
> > +++ b/libdtrace/mkvers
> > @@ -0,0 +1,68 @@
> > +#!/usr/bin/gawk -f
> > +#
> > +# Oracle Linux DTrace.
> > +# Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
> > +# Licensed under the Universal Permissive License v 1.0 as shown at
> > +# http://oss.oracle.com/licenses/upl.
> > +#
> > +
> > +/^\s*#/ { next; }
> > +NF == 0 { next; }
> > +
> > +# 1.2.1	D API 1.2.1 Solaris Express 4/06
> 
> Solaris Express?  Is this a vestigial comment?
> 
> > +{
> > +	if (match($1, /^[1-9][0-9]*(\.[0-9]*){1,2}$/) == 0) {
> > +		print "E: Invalid version string: " $1 >"/dev/stderr";
> > +		exit 1
> > +	}
> > +
> > +	n = split($1, arr, /\./);
> > +	if (n == 2)
> > +		arr[3] = 0;
> > +
> > +	code = arr[1] * 0x1000000 + arr[2] * 0x1000 + arr[3];
> > +	versions[code] = arr[1] " " arr[2] " " arr[3];
> > +	next;
> > +}
> > +
> > +END {
> > +	n = asorti(versions, idx);
> > +
> > +	if (release) {
> > +		$0 = versions[idx[n]];
> > +		if ($3 == 0)
> > +			printf "%s.%s", $1, $2;
> > +		else
> > +			printf "%s.%s.%s", $1, $2, $3;
> > +
> > +		exit(0);
> > +	}
> > +
> > +	for (i = 1; i <= n; i++) {
> > +		$0 = versions[idx[i]];
> > +		if ($3 == 0)
> > +			printf "#define DT_VERS_%d_%d\tDT_VERSION_NUMBER(%d, %d, 0)\n",\
> > +			       $1, $2, $1, $2;
> > +		else
> > +			printf "#define DT_VERS_%d_%d_%d\tDT_VERSION_NUMBER(%d, %d, %d)\n",\
> > +			       $1, $2, $3, $1, $2, $3;
> > +	}
> > +
> > +	print "\n#define DTRACE_VERSIONS { \\";
> > +	for (i = 1; i <= n; i++) {
> > +		$0 = versions[idx[i]];
> > +		if ($3 == 0)
> > +			printf "\t\tDT_VERS_%d_%d, \\\n", $1, $2, $1, $2;
> > +		else
> > +			printf "\t\tDT_VERS_%d_%d_%d, \\\n", $1, $2, $3, $1, $2, $3;
> > +	}
> > +	print "}";
> > +
> > +	if ($3 == 0) {
> > +		printf "\n#define DT_VERS_LATEST\tDT_VERS_%d_%d\n", $1, $2;
> > +		printf "#define DT_VERS_STRING\t\"Oracle D %d.%d\"\n", $1, $2;
> > +	} else {
> > +		printf "\n#define DT_VERS_LATEST\tDT_VERS_%d_%d_%d\n", $1, $2, $3;
> > +		printf "#define DT_VERS_STRING\t\"Oracle D %d.%d.%d\"\n", $1, $2, $3;
> > +	}
> > +}
> > diff --git a/libdtrace/versions.list b/libdtrace/versions.list
> > new file mode 100644
> > index 000000000..8986d2007
> > --- /dev/null
> > +++ b/libdtrace/versions.list
> > @@ -0,0 +1,67 @@
> > +#
> > +# Oracle Linux DTrace.
> > +# Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
> > +# Licensed under the Universal Permissive License v 1.0 as shown at
> > +# http://oss.oracle.com/licenses/upl.
> > +#
> > +
> > +#
> > +# Version definitions
> > +#
> > +# These definitions are used to generate dt_versions_defs.h.
> > +#
> > +# The generated file contains:
> > +#  - DT_VERS_* defines that are used in identifier tables to fill in the
> > +#    version fields associated with each identifier.
> > +#
> > +#  - DTRACE_VERSIONS which is used in dt_versions.c to populate the array of
> > +#    valid DTrace versions
> > +#
> > +#  - DT_VERS_LATEST which has the value of the most recent DT_VERS_* define
> > +#
> > +#  - DT_VERS_STRING which provides a string representation of the most recent
> > +#    DTrace version
> > +#
> > +# Refer to the Solaris Dynamic Tracing Guide Versioning chapter for an
> > +# explanation of these DTrace features and their values.
> > +#
> > +# NOTE: Although the DTrace versioning scheme supports the labeling and
> > +#       introduction of incompatible changes (e.g. dropping an interface in a
> > +#       major release), the libdtrace code does not currently support this.
> > +#       All versions are assumed to strictly inherit from one another.  If
> > +#       we ever need to provide divergent interfaces, this will need work.
> > +#
> > +# The version number should be increased for every customer visible release
> > +# of DTrace.
> > +#  - The major number should be incremented when a fundamental change has been
> > +#    made that would affect all consumers, and would reflect sweeping changes
> > +#    to DTrace or the D language.
> > +#  - The minor number should be incremented when a change is introduced that
> > +#    could break scripts that had previously worked; for example, adding a new
> > +#    built-in variable could break a script which was already using that
> > +#    identifier.
> > +#  - The micro number should be changed when introducing functionality changes
> > +#    or major bug fixes that do not affect backward compatibility -- this is
> > +#    merely to make capabilities easily determined from the version number.
> > +#    Minor bugs do not require any modification to the version number.
> > +#
> > +
> > +# Ver	Description
> > +1.0	D API 1.0.0 (PSARC 2001/466) Solaris 10 FCS
> > +1.1	D API 1.1.0 Solaris Express 6/05
> > +1.2	D API 1.2.0 Solaris 10 Update 1
> > +1.2.1	D API 1.2.1 Solaris Express 4/06
> > +1.2.2	D API 1.2.2 Solaris Express 6/06
> > +1.3	D API 1.3 Solaris Express 10/06
> > +1.4	D API 1.4 Solaris Express 2/07
> > +1.4.1	D API 1.4.1 Solaris Express 4/07
> > +1.5	D API 1.5 Solaris Express 7/07
> > +1.6	D API 1.6
> > +1.6.1	D API 1.6.1
> > +1.6.2	D API 1.6.2
> > +1.6.3	D API 1.6.3
> > +1.6.4	D API 1.6.4
> > +2.0	D API 2.0 Linux (BPF)
> > +2.0.1	D API 2.0.1 Linux (BPF)
> > +2.0.2	D API 2.0.2 Linux (BPF)
> > +2.0.3	D API 2.0.3 Linux (BPF)