.. default-domain:: chpl .. module:: Version :synopsis: Support for reasoning about version numbers. Version ======= **Usage** .. code-block:: chapel use Version; or .. code-block:: chapel import Version; Support for reasoning about version numbers. .. highlight:: chapel This module contains features that support reasoning about version numbers. The :type:`versionValue` type supports compile-time reasoning about version numbers in general, and Chapel version numbers specifically, while the :type:`version` type supports run-time reasoning about version numbers. In more detail, the module features: * :var:`chplVersion`: the version number of the copy of ``chpl`` used to compile the program. * :type:`versionValue`: a type that can be used to represent a semantic version number plus an optional commit value. This type supports `compile-time` reasoning about version numbers. * :type:`version`: a type that can be used to represent a semantic version number plus an optional commit value. This type supports `run-time` reasoning about version numbers. Version numbers in :type:`versionValue` are represented using ``param`` values to permit code specialization by being able to reason about versions at `compile-time`. The :type:`versionValue` type supports: * being printed out or cast to a ``param`` string * `compile-time` comparisons via ``==``, ``!=``, ``<``, ``<=``, ``>``, and ``>``. Generally speaking, "less than" corresponds to "is an earlier version than." For example:: if chplVersion < new versionValue(1,23) then compilerWarning("This package doesn't support 'chpl' prior to 1.23.0"); Version numbers in :type:`version` are represented using ``var`` values to permit constructing and assigning version number values at `run-time`. The :type:`version` type supports: * being printed out or cast to a string * `run-time` comparisons via ``==``, ``!=``, ``<``, ``<=``, ``>``, and ``>``. Generally speaking, "less than" corresponds to "is an earlier version than." The type :type:`versionValue` is useful for modifying compilation behavior, such as requiring a minimum version of the Chapel compiler. The type :type:`version` is useful for reasoning about version numbers that are not known at compile-time, such as values read from a text file. Comparisons between two :type:`versionValue`, two :type:`version`, or a :type:`versionValue` and a :type:`version` are supported. Equality/inequality operations check whether or not the two values have identical major, minor, update, and commit values. Ordered comparisons are based on the ordering of the semantic versions of the two values, as defined by their ``major``, ``minor``, and ``update`` components. Note that if the two values have identical semantic versions, any cases that rely on an ordering of the commits will generate an error if the values have differing, non-empty ``commit`` values due to the challenge of ordering commits. An empty ``commit`` value is considered to come after (be greater than) a non-empty value, as the former is considered an official release and the latter a pre-release. For example:: // any of the following variable declarations can be replaced with // `const vN = new versionValue(...)` instead of using the version type // and the comparison results would remain the same var v1 = new version(1, 2, 3); var v2 = new version(1, 2, 4); var v3 = new version(1, 2, 4, "abc"); var v4 = new version(1, 2, 4, "def"); writeln(v1 < v2); // prints "true" writeln(v2 < v3); // prints "false" as v3 and v4 are considered pre-releases of v2 writeln(v3 < v4); // error: cannot compare commits of different versions var v5 = new version(1, 2, 4, "abc"); writeln(v3 == v5); // prints "true" writeln(v3 != v5); // prints "false" .. data:: const chplVersion The version of ``chpl`` used to compile this program. For an official Chapel release, this will have an empty ``commit`` value, while for a pre-release, it will indicate the Git SHA. Note that, for historical reasons, Chapel ``1.x.y``/``2.x.y`` corresponds to version ``0.x.y``/``1.x.y`` in traditional semantic versioning. .. type:: type sourceVersion = versionValue .. warning:: sourceVersion is deprecated, please use versionValue instead. This record represents a software version that is modeled after a semantic version. It uses ``param`` values to represent its components in order to support compile-time comparison of version numbers which in turn permits code to specialize to specific versions of Chapel. When printed or converted to a string, it is represented as ``major.minor.update (commit)``. Note that ordered comparisons between two :type:`sourceVersion` values that only differ in their ``commit`` values are not supported due to the challenges involved in ordering commit values. However, when a value with an empty ``update`` value is compared to one whose ``update`` is non-empty, the latter is considered to be earlier than (less than) the former, due to the interpretation that it represents a pre-release of the official release. .. function:: proc createVersion(param major: int, param minor: int, param update: int = 0, param commit: string = ""): sourceVersion(?) .. warning:: createVersion is deprecated, please use 'new versionValue()' instead. A helper function that creates a new sourceVersion from its arguments. :arg major: The major version number :type major: `int` :arg minor: The minor version number :type minor: `int` :arg update: The optional update version number (defaults to 0) :type update: `int` :arg commit: The optional commit ID (defaults to "") :type commit: `string` :returns: A new version value of type :type:`sourceVersion`. .. record:: versionValue : writeSerializable This record represents a software version that is modeled after a semantic version, though not 100% true to the semver spec. The main deviation from the spec is that ``versionValue`` doesn't support pre-release identifiers and the version and optional build/commit value are separated with a space rather than with ``+``. See semver.org for details on the spec. The ``versionValue`` uses ``param`` values to represent its components in order to support `compile-time` comparison of version numbers which in turn permits code to specialize to specific versions of Chapel. When printed or converted to a string, it is represented as ``major.minor.update (commit)``. .. attribute:: param major: int The major version number. For version ``2.0.1``, this would be ``2``. .. attribute:: param minor: int The minor version number. For version ``2.0.1``, this would be ``0``. .. attribute:: param update: int The update version number. For version ``2.0.1``, this would be ``1``. .. attribute:: param commit: string = "" The commit ID of the version (e.g., a Git SHA) .. record:: version : writeSerializable This record represents a software version similar to the :type:`versionValue`. It uses ``var`` values to represent its components in order to support `run-time` building and comparison of version numbers. When printed or converted to a string, it is represented as ``major.minor.update (commit)``. Unlike :type:`versionValue`, a ``version`` can be created and modified at runtime. .. attribute:: var major: int The major version number. For version ``2.0.1``, this would be ``2``. Defaults to ``-1`` .. attribute:: var minor: int The minor version number. For version ``2.0.1``, this would be ``0``. Defaults to ``-1`` .. attribute:: var update: int The update version number. For version ``2.0.1``, this would be ``1``. Defaults to ``0`` .. attribute:: var commit: string = "" The commit ID of the version (e.g., a Git SHA) Defaults to ``""`` .. class:: VersionComparisonError : Error Error class thrown when two versions are compared that cannot be compared. For example, two versions differing only in commit IDs cannot be compared.