18 DTrace Versioning

In the chapter, DTrace Stability Features, the DTrace features for determining the stability attributes of D programs that you create are described. When you have created a D program with the appropriate stability attributes, you might also choose to bind this program to a particular version of the D programming interface.

The D interface version is a label that is applied to a particular set of types, variables, functions, constants, and translators that are 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, as well as identifiers that are defined in future versions of the D programming interface. You should establish version bindings for any D programs that you want to install as persistent scripts or use in layered tools. See Scripting for more information about using DTrace scripts.

Note:

DTrace versioning in Oracle Linux is not currently interoperable with DTrace versioning on other operating system platforms.

Versions and Releases

The D compiler labels sets of types, variables, functions, constants, and translators that correspond to a particular software release by using a version string. A version string is a period-delimited sequence of decimal integers that takes one of the following forms:

x

Major release

x.y

Minor release

x.y.z

Micro release

Version comparisons are made 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 the standard nomenclature for interface versions. A change in the D programming interface is accompanied by a new version string. The following table summarizes the version strings that are used by DTrace and the likely significance of the corresponding DTrace software release.

Table 18-1 DTrace Release Versions

Release	Version	Significance
Major	x.0	A Major release is likely to contain major feature additions; adhere to different, possibly incompatible Standard revisions; and though unlikely, could change, drop, or replace Standard or Stable interfaces (see DTrace Stability Features). The initial version of the D programming interface is labeled as version 1.0.
Minor	x.y	Compared to an x.0 or earlier version (where y is not equal to zero), a new Minor release is likely to contain minor feature additions, compatible Standard and Stable interfaces, possibly incompatible Evolving interfaces, or likely incompatible Unstable interfaces. These changes may include new built-in D types, variables, functions, constants, and translators. In addition, a Minor release may remove support for interfaces previously labeled as Obsolete (see DTrace Stability Features).
Micro	x.y.z	Micro releases are intended to be interface compatible with the previous release (where z is not equal to zero), but are likely to include bug fixes, performance enhancements, and support for additional hardware.

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

Versioning Options

By default, any D programs that you compile by using the dtrace -s command or that you specify by using the dtrace -P, -m, -f, -n, or -i command 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 by using the -V option:

# dtrace -V
dtrace: Sun D 1.6.4

Note:

Specifying the -Vv combination displays other version information, such as the version of the user-space binaries from the dtrace-utils package.

# dtrace -Vv
dtrace: Sun D 1.6.4
This is DTrace 1.0.4.
dtrace(1) version-control ID: 364a014be59b349d6222991d651d38422f170e7e
libdtrace version-control ID: 364a014be59b349d6222991d651d38422f170e7e

If you want 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 that are described in Options and Tunables, you can set the version option as follows:

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

Alternatively, you can use the #pragma D option syntax to set the option in your D program source file, for example:

#pragma D option version=1.6

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 that is not offered by the D compiler, an appropriate error message is produced and compilation fails. You can also use the version binding facility to cause the execution of a D script on an older version of DTrace to fail with an obvious error message.

Before 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 that 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 might 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 selecting identifier names that are unlikely to conflict with interfaces offered by future versions of DTrace.

Provider Versioning

Unlike interfaces that are offered by the D compiler, interfaces that are offered by DTrace providers, that is, probes and probe arguments, are not affected by or associated with the D programming interface or the version binding options previously described. The available provider interfaces are established as part of loading your compiled instrumentation into the DTrace software in the operating system kernel. These interfaces vary, depending on the following: your instruction set architecture, operating platform, processor, the software that is installed on your Oracle Linux system, and your current security privileges. The D compiler and DTrace runtime examine the probes that are described in your D program clauses and report appropriate error messages whenever 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, which means you can only enable probes in D; you cannot define them. Also, probe names are kept in a separate namespace from other D program identifiers.

Use the dtrace -l command, optionally adding the -v option, to explore the set of providers and probes that are available on your Oracle Linux system. See DTrace Providers for more information about common providers and probes.