Chapter 41 Versioning

In Chapter 39, Stability, we learned about the DTrace features for determining the stability attributes of D programs that you create. Once you have created a D program with the appropriate stability attributes, you may also wish to bind this program to a particular version of the D programming interface. The D interface version is a label applied to a particular set of types, variables, functions, constants, and translators made available to you by the D compiler. If you specify a binding to a specific version of the D programming interface, you ensure that you can recompile your program on future versions of DTrace without encountering conflicts between program identifiers that you define and identifiers defined in future versions of the D programming interface. You should establish version bindings for any D programs that you wish to install as persistent scripts (see Chapter 15, Scripting) or use in layered tools.

Versions and Releases

The D compiler labels sets of types, variables, functions, constants, and translators corresponding to a particular software release using a version string. A version string is a period-delimited sequence of decimal integers of the form “x” (a Major release), “x.y” (a Minor release), or “x.y.z” (a Micro release). Versions are compared by comparing the integers from left to right. If the leftmost integers are not equal, the string with the greater integer is the greater (and therefore more recent) version. If the leftmost integers are equal, the comparison proceeds to the next integer in order from left to right to determine the result. All unspecified integers in a version string are interpreted as having the value zero during a version comparison.

The DTrace version strings correspond to Sun's standard nomenclature for interface versions, as described in attributes(5). A change in the D programming interface is accompanied by a new version string. The following table summarizes the version strings used by DTrace and the likely significance of the corresponding DTrace software release.

In general, each new version of the D programming interface will provide a superset of the capabilities offered by the previous version, with the exception of any Obsolete interfaces that have been removed.

Versioning Options

By default, any D programs you compile using dtrace -s or specify using the dtrace -P, -m, -f, -n, or -i command-line options are bound to the most recent D programming interface version offered by the D compiler. You can determine the current D programming interface version using the dtrace -V option:

$ dtrace -V
dtrace: Sun D 1.0
$

If you wish to establish a binding to a specific version of the D programming interface, you can set the version option to an appropriate version string. Similar to other DTrace options (see Chapter 16, Options and Tunables), you can set the version option either on the command-line using dtrace -x:

# dtrace -x version=1.0 -n 'BEGIN{trace("hello");}'

or you can use the #pragma D option syntax to set the option in your D program source file:

#pragma D option version=1.0

BEGIN
{
	trace("hello");
}

If you use the #pragma D option syntax to request a version binding, you must place this directive at the top of your D program file prior to any other declarations and probe clauses. If the version binding argument is not a valid version string or refers to a version not offered by the D compiler, an appropriate error message will be produced and compilation will fail. You can therefore also use the version binding facility to cause execution of a D script on an older version of DTrace to fail with an obvious error message.

Prior to compiling your program declarations and clauses, the D compiler loads the set of D types, functions, constants, and translators for the appropriate interface version into the compiler namespaces. Therefore, any version binding options you specify simply control the set of identifiers, types, and translators that are visible to your program in addition to the variables, types, and translators that your program defines. Version binding prevents the D compiler from loading newer interfaces that may define identifiers or translators that conflict with declarations in your program source code and would therefore cause a compilation error. See Identifier Names and Keywords for tips on how to pick identifier names that are unlikely to conflict with interfaces offered by future versions of DTrace.

Provider Versioning

Unlike interfaces offered by the D compiler, interfaces offered by DTrace providers (that is, probes and probe arguments) are not affected by or associated with the D programming interface or the previously described version binding options. The available provider interfaces are established as part of loading your compiled instrumentation into the DTrace software in the operating system kernel and vary depending on your instruction set architecture, operating platform, processor, the software installed on your Solaris system, and your current security privileges. The D compiler and DTrace runtime examine the probes described in your D program clauses and report appropriate error messages when probes requested by your D program are not available. These features are orthogonal to the D programming interface version because DTrace providers do not export interfaces that can conflict with definitions in your D programs; that is, you can only enable probes in D, you cannot define them, and probe names are kept in a separate namespace from other D program identifiers.

DTrace providers are delivered with a particular release of Solaris and are described in the corresponding version of the Solaris Dynamic Tracing Guide. The chapter of this guide corresponding to each provider will also describe any relevant changes to or new features offered by a given provider. You can use the dtrace -l option to explore the set of providers and probes available on your Solaris system. Providers label their interfaces using the DTrace stability attributes, and you can use the DTrace stability reporting features (see Chapter 39, Stability) to determine whether the provider interfaces used by your D program are likely to change or be offered in future Solaris releases.