mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-03-29 02:02:50 -07:00
175 lines
6 KiB
ReStructuredText
175 lines
6 KiB
ReStructuredText
.. mode: -*- rst -*-
|
||
|
||
Library version mechanism
|
||
=========================
|
||
|
||
:Tag: design.mps.version-library
|
||
:Author: David Jones
|
||
:Date: 1998-08-19
|
||
:Status: complete document
|
||
:Revision: $Id$
|
||
:Copyright: See `Copyright and License`_.
|
||
:Index terms: pair: library version mechanism; design
|
||
|
||
|
||
Introduction
|
||
------------
|
||
|
||
_`.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
|
||
----------
|
||
|
||
_`.readership`: Any MPS developer.
|
||
|
||
|
||
Source
|
||
------
|
||
|
||
_`.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
|
||
--------
|
||
|
||
_`.overview`: This is the design for determining which version of the
|
||
library one has linked against. 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).
|
||
|
||
_`.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
|
||
------------
|
||
|
||
_`.arch.structure`: The design consists of two components:
|
||
|
||
#. _`.arch.string`: A string embedded into any delivered library
|
||
binaries (which will encode the necessary information).
|
||
|
||
#. _`.arch.proc`: Procedures by which the string is modified
|
||
appropriately whenever releases are made.
|
||
|
||
#. _`.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.
|
||
|
||
The string will contain information to identify the following items:
|
||
|
||
#. _`.arch.string.platform`: the platform being used.
|
||
|
||
#. _`.arch.string.product`: the name of the product.
|
||
|
||
#. _`.arch.string.variety`: the variety of the product.
|
||
|
||
#. _`.arch.string.version`: the version and release of the product.
|
||
|
||
|
||
Implementation
|
||
--------------
|
||
|
||
_`.impl.file`: The version string itself is a declared C object
|
||
``MPSVersionString`` in the file ``version.c`` (impl.c.version). It
|
||
consists of a concatenation of various strings which are defined in
|
||
other modules.
|
||
|
||
_`.impl.variety`: The string containing the name of the variety is the
|
||
expansion of the macro ``MPS_VARIETY_STRING`` defined by ``config.h``
|
||
(impl.h.config).
|
||
|
||
_`.impl.product`: The string containing the name of the product is the
|
||
expansion of the macro ``MPS_PROD_STRING`` defined by ``config.h``
|
||
(impl.h.config). Note that there is now only one product, so this is
|
||
always ``"mps"`` (see design.mps.config.req.prod_).
|
||
|
||
.. _design.mps.config.req.prod: config#.req.prod
|
||
|
||
_`.impl.platform`: The string containing the name of the platform is
|
||
the expansion of the macro ``MPS_PF_STRING`` defined by ``mpstd.h``
|
||
(impl.h.mpstd).
|
||
|
||
_`.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.
|
||
|
||
_`.impl.version`: The string contains the version and release of the
|
||
product. This is by the expansion of the macro ``MPS_RELEASE`` which
|
||
is defined in this module (``version.c``).
|
||
|
||
_`.impl.proc`: The ``MPS_RELEASE`` macro (see impl.c.version.release)
|
||
is edited after making a release so that it contains the name of the
|
||
next release to be made from the sources on that branch. For example, after
|
||
making version 1.117, the source on the master branch is updated to say::
|
||
|
||
#define MPS_RELEASE "release/1.118.0"
|
||
|
||
and after making release 1.117.0, the source on the version/1.117 branch is updated to say::
|
||
|
||
#define MPS_RELEASE "release/1.117.1"
|
||
|
||
See the version creation and release build procedures respectively.
|
||
|
||
_`.impl.tool`: The version string starts with the characters
|
||
``"@(#)"``. This is recognized by the standard Unix utility |what|_. For example::
|
||
|
||
$ what mps.a
|
||
mps.a
|
||
Ravenbrook MPS, product.mps, release/1.117.0, platform.xci6ll, variety.asserted.logging.nonstats, compiled on Oct 18 2016 13:57:08
|
||
|
||
.. |what| replace:: ``what(1)``
|
||
.. _what: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/what.html
|
||
|
||
|
||
Document History
|
||
----------------
|
||
|
||
- 1998-08-19 David Jones. Incomplete document.
|
||
|
||
- 2002-06-07 RB_ Converted from MMInfo database design document.
|
||
|
||
- 2013-03-11 GDR_ Converted to reStructuredText.
|
||
|
||
.. _RB: https://www.ravenbrook.com/consultants/rb/
|
||
.. _GDR: https://www.ravenbrook.com/consultants/gdr/
|
||
|
||
|
||
Copyright and License
|
||
---------------------
|
||
|
||
Copyright © 2013–2020 `Ravenbrook Limited <https://www.ravenbrook.com/>`_.
|
||
|
||
Redistribution and use in source and binary forms, with or without
|
||
modification, are permitted provided that the following conditions are
|
||
met:
|
||
|
||
1. Redistributions of source code must retain the above copyright
|
||
notice, this list of conditions and the following disclaimer.
|
||
|
||
2. Redistributions in binary form must reproduce the above copyright
|
||
notice, this list of conditions and the following disclaimer in the
|
||
documentation and/or other materials provided with the distribution.
|
||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|