1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
.. index::
   pair: library version mechanism; design

.. _design-version-library:


Library version mechanism
=========================

.. mps:prefix:: design.mps.version-library


Introduction
------------

:mps:tag:`intro` This describes the design of a mechanism to be used to
determine the version (that is, product, version, and release) of an
MPS library.


Readership
----------

:mps:tag:`readership` Any MPS developer.


Source
------

:mps:tag:`source` Various requirements demand such a mechanism. See
request.epcore.160021_: There is no way to tell which version and
release of the MM one is using.

.. _request.epcore.160021: https://info.ravenbrook.com/project/mps/import/2001-11-05/mmprevol/request/epcore/160021

Overview
--------

:mps:tag:`overview` See design.mps.version for discussion and design of
versions of other aspects of the software. This document concentrates
on a design for determining which version of the library one has
linked with. There are two aspects to the design, allowing humans to
determine the version of an MPS library, and allowing programs to
determine the version of an MPS library. Only the former is currently
designed (a method for humans to determine which version of an MPS
library is being used).

:mps:tag:`overview.impl` The overall design is to have a distinctive string
compiled into the library binary. Various programs and tools will be
able to extract the string and display it. The string will identify
the version of the MPS begin used.


Architecture
------------

:mps:tag:`arch.structure` The design consists of three components:

#. :mps:tag:`arch.string` A string embedded into any delivered library
   binaries (which will encode the necessary information).

#. :mps:tag:`arch.proc` A process by which the string is modified
   appropriately whenever releases are made.

#. :mps:tag:`arch.tool` A tool and its documentation (it is expected that
   standard tools can be used). The tool will be used to extract the
   version string from a delivered library or an executable linked
   with the library.

:mps:tag:`arch.not-here` Only the string component
(arch.string) is directly described here. The other
components are described elsewhere. (where?)

The string will contain information to identify the following items:

#. :mps:tag:`arch.string.platform` the platform being used.

#. :mps:tag:`arch.string.product` the name of the product.

#. :mps:tag:`arch.string.variety` the variety of the product.

#. :mps:tag:`arch.string.version` the version and release of the product.


Implementation
--------------

:mps:tag:`impl.file` The string itself is a declared C object in the file
``version.c`` (impl.c.version). It consists of a concatenation of
various strings which are defined in other modules.

:mps:tag:`impl.variety` The string containing the name of the variety is the
expansion of the macro :c:macro:`MPS_VARIETY_STRING` defined by ``config.h``
(impl.h.config).

:mps:tag:`impl.product` The string containing the name of the product is the
expansion of the macro :c:macro:`MPS_PROD_STRING` defined by ``config.h``
(impl.h.config).

:mps:tag:`impl.platform` The string containing the name of the platform is
the expansion of the macro :c:macro:`MPS_PF_STRING` defined by ``mpstd.h``
(impl.h.mpstd).

:mps:tag:`impl.date` The string contains the date and time of compilation by
using the ``__DATE__`` and ``__TIME__`` macros defined by ISO C
ยง6.8.8.

:mps:tag:`impl.version` The string contains the version and release of the
product. This is by the expansion of the macro :c:macro:`MPS_RELEASE` which
is defined in this module (``version.c``).

:mps:tag:`impl.usage` To make a release, the :c:macro:`MPS_RELEASE` macro (see
impl.c.version.release) is edited to contain the release name (for
example, ``"release.epcore.brisling"``), and then changed back
immediately after the release checkpoint is made.