mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-01-06 03:40:56 -08:00
189 lines
6.8 KiB
ReStructuredText
189 lines
6.8 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: http://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: http://www.ravenbrook.com/consultants/rb/
|
|
.. _GDR: http://www.ravenbrook.com/consultants/gdr/
|
|
|
|
|
|
Copyright and License
|
|
---------------------
|
|
|
|
Copyright © 2013-2016 Ravenbrook Limited <http://www.ravenbrook.com/>.
|
|
All rights reserved. This is an open source license. Contact
|
|
Ravenbrook for commercial licensing options.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are
|
|
met:
|
|
|
|
#. Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
#. 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.
|
|
|
|
#. Redistributions in any form must be accompanied by information on how
|
|
to obtain complete source code for this software and any
|
|
accompanying software that uses this software. The source code must
|
|
either be included in the distribution or be available for no more than
|
|
the cost of distribution plus a nominal fee, and must be freely
|
|
redistributable under reasonable conditions. For an executable file,
|
|
complete source code means the source code for all modules it contains.
|
|
It does not include source code for modules or files that typically
|
|
accompany the major components of the operating system on which the
|
|
executable file runs.
|
|
|
|
**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, fitness for a
|
|
particular purpose, or non-infringement, are disclaimed. In no event
|
|
shall the copyright holders and 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.**
|