... {anchor:top}
h1. {anchor:CHP-VERS} Versioning
In [Chapter 39, Stability|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|Scripting]) or use in layered tools.
[Top|#top]
h2. {anchor:CHP-VERS-1} 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)|http://docs.sun.com/doc/819-2252/attributes-5?a=view]. 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.
h6. {anchor:TBL-VERS} 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 [Chapter 39, Stability|Stability]). 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 [Chapter 39, Stability|Stability]).|
|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 will provide a superset of the capabilities offered by the previous version, with the exception of any Obsolete interfaces that have been removed.
[Top|#top]
h2. {anchor:CHP-VERS-2} 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:
{noformat}
$ dtrace -V
dtrace: Sun D 1.0
$
{noformat}
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|Options and Tunables]), you can set the version option either on the command-line using {{dtrace}} \-x:
{noformat}
# dtrace -x version=1.0 -n 'BEGIN{trace("hello");}'
{noformat}
or you can use the {{#pragma D option}} syntax to set the option in your D program source file:
{noformat}
#pragma D option version=1.0
BEGIN
{
trace("hello");
}
{noformat}
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|Types, Operators and Expressions#CHP-TYPEOPEXPR-1] for tips on how to pick identifier names that are unlikely to conflict with interfaces offered by future versions of DTrace.
|