.. 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 compile-time reasoning about version numbers in general, and Chapel version numbers specifically. In more detail, it features: * :var:`chplVersion`: the version number of the copy of ``chpl`` used to compile the program. * :type:`sourceVersion`: a type that can be used to represent a semantic version number plus an optional commit value. * :proc:`createVersion`: a utility function for creating new version values Version numbers in this module are represented using ``param`` values to permit code specialization by being able to reason about versions at compile-time. The :type:`sourceVersion` 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 < createVersion(1,23) then compilerWarning("This package doesn't support 'chpl' prior to 1.23.0"); .. 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. .. function:: proc createVersion(param major: int, param minor: int, param update: int = 0, param commit: string = ""): sourceVersion(?) A helper function that creates a new version value 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:: sourceVersion This record represents a software version in a Git repository. 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 ``version 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. .. 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) .. method:: proc type sourceVersion.==(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool .. method:: proc type sourceVersion.!=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool Equality/inequality operators between two values of type :type:`sourceVersion` check whether or not the two values have identical major, minor, update, and commit values. .. method:: proc type sourceVersion.<(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool .. method:: proc type sourceVersion.<=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool .. method:: proc type sourceVersion.>(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool .. method:: proc type sourceVersion.>=(v1: sourceVersion(?), v2: sourceVersion(?)) param: bool Ordered comparisons between two values of type :type:`sourceVersion` are based on the ordering of the semantic versions of the two values, as defined by their ``major``, ``minor``, and ``update`` components. If the two values have identical semantic versions, any cases that rely on an ordering of the commits will generate a compile-time error if the values have differing, non-empty ``commit`` values due to the challenge of ordering commits at compile-time. 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.