Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-20 03:47:34 +00:00
Code Issues Projects Releases Packages Wiki Activity
emacs/mps/manual/html/design/config.html
Gareth Rees c5f77afc19 Bring html up to date for the mps manual. 
Copied from Perforce
 Change: 181433
 ServerID: perforce.ravenbrook.com
2013-04-24 12:21:37 +01:00

568 lines
No EOL
42 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>7. Configuration &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.111.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Design" href="index.html" />
<link rel="next" title="8. Finalization" href="finalize.html" />
<link rel="prev" title="6. Collection framework" href="collection.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="finalize.html" title="8. Finalization"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="collection.html" title="6. Collection framework"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Design</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="configuration">
<span id="design.mps.config"></span><h1>7. Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline"></a></h1>
<div class="section" id="introduction">
<h2>7.1. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.intro"></span><a class="mpstag reference internal" href="#design.mps.config.intro">.intro:</a> This document describes how the MPS configuration is
parameterized so that it can target different architectures, operating
systems, build environments, varieties, and products.</p>
<p><span class="target" id="design.mps.config.bg"></span><a class="mpstag reference internal" href="#design.mps.config.bg">.bg:</a> For background see [build system mail, configuration
mail, meeting.general.something]</p>
</div>
<div class="section" id="history">
<h2>7.2. History<a class="headerlink" href="#history" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.hist.0"></span><a class="mpstag reference internal" href="#design.mps.config.hist.0">.hist.0:</a> Initial draft created by Richard Brooksby on
1997-02-19 based on discussions of configuration at
meeting.general.1997-02-05.</p>
<p><span class="target" id="design.mps.config.hist.1"></span><a class="mpstag reference internal" href="#design.mps.config.hist.1">.hist.1:</a> Various improvements and clarifications to the draft
discussed between Richard and Nick Barnes at
meeting.general.1997-02-19.</p>
<p><span class="target" id="design.mps.config.hist.2"></span><a class="mpstag reference internal" href="#design.mps.config.hist.2">.hist.2:</a> Converted from MMInfo database design document.
Richard Brooksby, 2002-06-07.</p>
<p><span class="target" id="design.mps.config.hist.3"></span><a class="mpstag reference internal" href="#design.mps.config.hist.3">.hist.3:</a> Updated for variety-reform branch, to remove untrue
things, though the document could do with a rewrite. Richard Brooksby,
2012-09-03.</p>
<p><span class="target" id="design.mps.config.hist.4"></span><a class="mpstag reference internal" href="#design.mps.config.hist.4">.hist.4:</a> Converted to reStructuredText. Gareth Rees,
2013-03-19.</p>
</div>
<div class="section" id="requirements">
<h2>7.3. Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.req.arch"></span><a class="mpstag reference internal" href="#design.mps.config.req.arch">.req.arch:</a> Allow architecture specific configurations of the
MPS.</p>
<p><span class="target" id="design.mps.config.req.os"></span><a class="mpstag reference internal" href="#design.mps.config.req.os">.req.os:</a> Allow operating system specific configurations of
the MPS.</p>
<p><span class="target" id="design.mps.config.req.builder"></span><a class="mpstag reference internal" href="#design.mps.config.req.builder">.req.builder:</a> Allow build environment (compiler, etc.)
specific configurations of the MPS.</p>
<p><span class="target" id="design.mps.config.req.prod"></span><a class="mpstag reference internal" href="#design.mps.config.req.prod">.req.prod:</a> Allow product specific configurations of the MPS.
[This requirement was retired on 2012-09-03. Client-specific
customisation of the MPS will be handled by configuration management,
while the MPS source remains generic, to reduce costs and increase
reliability.]</p>
<p><span class="target" id="design.mps.config.req.var"></span><a class="mpstag reference internal" href="#design.mps.config.req.var">.req.var:</a> Allow configurations with different amounts of
instrumentation (assertions, metering, etc.).</p>
<p><span class="target" id="design.mps.config.req.impact"></span><a class="mpstag reference internal" href="#design.mps.config.req.impact">.req.impact:</a> The configuration system should have a minimal
effect on maintainability of the implementation.</p>
<p><span class="target" id="design.mps.config.req.port"></span><a class="mpstag reference internal" href="#design.mps.config.req.port">.req.port:</a> The system should be easy to port across operating
systems.</p>
<p><span class="target" id="design.mps.config.req.maint"></span><a class="mpstag reference internal" href="#design.mps.config.req.maint">.req.maint:</a> Maintenance of the configuration and build system
should not consume much developer time.</p>
</div>
<div class="section" id="definitions">
<h2>7.4. Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.def.platform"></span><a class="mpstag reference internal" href="#design.mps.config.def.platform">.def.platform:</a> A platform is a combination of an architecture
(<a class="reference internal" href="#design.mps.config.def.arch">.def.arch</a>), an operating system (<a class="reference internal" href="#design.mps.config.def.os">.def.os</a>), and
a builder (<a class="reference internal" href="#design.mps.config.def.builder">.def.builder</a>). The set of supported platforms is
platform.*.</p>
<p><span class="target" id="design.mps.config.def.arch"></span><a class="mpstag reference internal" href="#design.mps.config.def.arch">.def.arch:</a> An architecture is processor type with associated
calling conventions and other binary interface stuff.</p>
<p><span class="target" id="design.mps.config.def.os"></span><a class="mpstag reference internal" href="#design.mps.config.def.os">.def.os:</a> An operating system is the interface to external
resources.</p>
<p><span class="target" id="design.mps.config.def.builder"></span><a class="mpstag reference internal" href="#design.mps.config.def.builder">.def.builder:</a> A builder is the tools (C compiler, etc.) used
to make the target (<a class="reference internal" href="#design.mps.config.def.target">.def.target</a>).</p>
<p><span class="target" id="design.mps.config.def.var"></span><a class="mpstag reference internal" href="#design.mps.config.def.var">.def.var:</a> A variety is a combination of annotations such as
assertions, metering, etc.</p>
<p><span class="target" id="design.mps.config.def.prod"></span><a class="mpstag reference internal" href="#design.mps.config.def.prod">.def.prod:</a> A product is the intended product into which the
MPS will fit, e.g. ScriptWorks, Dylan, etc.</p>
<p><span class="target" id="design.mps.config.def.target"></span><a class="mpstag reference internal" href="#design.mps.config.def.target">.def.target:</a> The target is the result of the build.</p>
</div>
<div class="section" id="overview">
<h2>7.5. Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li>No automatically generated code. Use only C compiler and linker.</li>
<li>Simple build function (design.mps.buildsys).</li>
<li>Avoid conditional code spaghetti in implementations.</li>
<li>Dependency on a particular configuration should be minimized and
localized when developing code.</li>
</ul>
</div>
<div class="section" id="the-build-system">
<h2>7.6. The build system<a class="headerlink" href="#the-build-system" title="Permalink to this headline"></a></h2>
<div class="section" id="abstract-build-function">
<h3>7.6.1. Abstract Build Function<a class="headerlink" href="#abstract-build-function" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.build.fun"></span><a class="mpstag reference internal" href="#design.mps.config.build.fun">.build.fun:</a> The MPS implementation assumes only a simple
&#8220;build function&#8221; which takes a set of sources, possibly in several
languages, compiles them with a set of predefined preprocessor
symbols, and links the result with a set of libraries to form the
target:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">target</span> <span class="o">:=</span> <span class="n">build</span><span class="p">(</span><span class="o">&lt;</span><span class="n">defs</span><span class="o">&gt;</span><span class="p">,</span> <span class="o">&lt;</span><span class="n">srcs</span><span class="o">&gt;</span><span class="p">,</span> <span class="o">&lt;</span><span class="n">libs</span><span class="o">&gt;</span><span class="p">)</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.build.sep"></span><a class="mpstag reference internal" href="#design.mps.config.build.sep">.build.sep:</a> Separate compilation and linkage can be seen as a
memoization of this function, and is not strictly necessary for the
build.</p>
<p><span class="target" id="design.mps.config.build.cc"></span><a class="mpstag reference internal" href="#design.mps.config.build.cc">.build.cc:</a> A consequence of this approach is that it should
always be possible to build a complete target with a single UNIX
command line calling the compiler driver (usually <tt class="docutils literal"><span class="pre">cc</span></tt> or <tt class="docutils literal"><span class="pre">gcc</span></tt>),
for example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">o</span> <span class="n">main</span> <span class="o">-</span><span class="n">DCONFIG_VAR_DF</span> <span class="n">foo</span><span class="p">.</span><span class="n">c</span> <span class="n">bar</span><span class="p">.</span><span class="n">c</span> <span class="n">baz</span><span class="p">.</span><span class="n">s</span> <span class="o">-</span><span class="n">lz</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.build.defs"></span><a class="mpstag reference internal" href="#design.mps.config.build.defs">.build.defs:</a> The &#8220;defs&#8221; are the set of preprocessor macros
which are to be predefined when compiling the module sources, of the
form:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">CONFIG_VAR_</span><span class="o">&lt;</span><span class="n">variety</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>A variety-code is a code that appears after <tt class="docutils literal"><span class="pre">variety.</span></tt> in the tag of
the relevant variety document (see design.mps.variety),
converted to upper case. Currently (2012-09-03) the valid variety
codes are <tt class="docutils literal"><span class="pre">RASH</span></tt>, <tt class="docutils literal"><span class="pre">HOT</span></tt>, <tt class="docutils literal"><span class="pre">COOL</span></tt>, <tt class="docutils literal"><span class="pre">DIAG</span></tt>, and <tt class="docutils literal"><span class="pre">TI</span></tt>.</p>
<p>If no <tt class="docutils literal"><span class="pre">CONFIG_VAR_</span></tt> is present, <tt class="docutils literal"><span class="pre">HOT</span></tt> is assumed in <tt class="docutils literal"><span class="pre">config.h</span></tt>.</p>
<p><span class="target" id="design.mps.config.build.srcs"></span><a class="mpstag reference internal" href="#design.mps.config.build.srcs">.build.srcs:</a> The &#8220;srcs&#8221; are the set of sources that must be
compiled in order to build the target. The set of sources may vary
depending on the configuration. For example, different sets of sources
may be required to build on different architectures. [This is a
dependency between the makefile (or whatever) and the module
configuration in <tt class="docutils literal"><span class="pre">config.h</span></tt>.]</p>
<p><span class="target" id="design.mps.config.build.libs"></span><a class="mpstag reference internal" href="#design.mps.config.build.libs">.build.libs:</a> The &#8220;libs&#8221; are the set of libraries to which the
compiled sources must be linked in order to build the target. For
example, when building a test program, it might include the ANSI C
library and an operating system interface library.</p>
</div>
<div class="section" id="file-structure">
<h3>7.6.2. File Structure<a class="headerlink" href="#file-structure" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.file.dir"></span><a class="mpstag reference internal" href="#design.mps.config.file.dir">.file.dir:</a> Each product consists of a single directory
(corresponding to a HOPE compound) containing all the sources for the
whole family of targets.</p>
<p><span class="target" id="design.mps.config.file.base"></span><a class="mpstag reference internal" href="#design.mps.config.file.base">.file.base:</a> The names of sources must be unique in the first
eight characters in order to conform to FAT filesystem naming
restrictions.</p>
<p><span class="target" id="design.mps.config..file.ext"></span><a class="mpstag reference internal" href="#design.mps.config..file.ext">..file.ext:</a> The extension may be up to three characters and
directly indicates the source language.</p>
<p>[Where is the set of valid extensions and languages defined?]</p>
</div>
<div class="section" id="modules-and-naming">
<h3>7.6.3. Modules and Naming<a class="headerlink" href="#modules-and-naming" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.mod.unique"></span><a class="mpstag reference internal" href="#design.mps.config.mod.unique">.mod.unique:</a> Each module has an identifier which is unique
within the MPS.</p>
<p><span class="target" id="design.mps.config.mod.impls"></span><a class="mpstag reference internal" href="#design.mps.config.mod.impls">.mod.impls:</a> Each module has one or more implementations which
may be in any language supported by the relevant build environment.</p>
<p><span class="target" id="design.mps.config.mod.primary"></span><a class="mpstag reference internal" href="#design.mps.config.mod.primary">.mod.primary:</a> The primary implementation of a module is
written in target-independent ANSI C in a source file with the same
name as the module (plus the <tt class="docutils literal"><span class="pre">an</span></tt> suffix if there are secondary
implementations: see <a class="reference internal" href="#design.mps.config.mod.secondary">.mod.secondary</a>).</p>
<p><span class="target" id="design.mps.config..mod.secondary"></span><a class="mpstag reference internal" href="#design.mps.config..mod.secondary">..mod.secondary:</a> The names of other implementations should
begin with the same prefix (the module identifier, or a shortened
version of it) and be suffixed with on or more target parameter codes
(defined below). In particular, the names of assembly language sources
must include the target parameter code for the relevant architecture.</p>
</div>
<div class="section" id="build-system-rationale">
<h3>7.6.4. Build System Rationale<a class="headerlink" href="#build-system-rationale" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.build.rat"></span><a class="mpstag reference internal" href="#design.mps.config.build.rat">.build.rat:</a> This simple design makes it possible to build the
MPS using many different tools. Microsoft Visual C++, Metrowerks
Codewarrior, and other graphical development tools do not support much
in the way of generated sources, staged building, or other such stuff.
The Visual C and Metrowerks &#8220;project&#8221; files correspond closely to a
closure of the build function (<a class="reference internal" href="#design.mps.config.build.fun">.build.fun</a>). The simplicity
of the build function has also made it easy to set up builds using
NMAKE (DOS), MPW (Macintosh), and to get the MPS up and running on
other platforms such as FreeBSD and Linux in very little time. The
cost of maintaining the build systems on these various platforms is
also reduced to a minimum, allowing the MM Group to concentrate on
primary development. The source code is kept simple and
straightforward. When looking at MPS sources you can tell exactly what
is going to be generated with very little context. The sources are not
munged beyond the standard ANSI C preprocessor.</p>
<p><span class="target" id="design.mps.config.build.port"></span><a class="mpstag reference internal" href="#design.mps.config.build.port">.build.port:</a> The portability requirement
(<a class="reference internal" href="#design.mps.config.req.port">.req.port</a>) implies that the build system must use only
standard tools that will be available on all conceivable target
platforms. Experience of development environments on the Macintosh
(Metrowerks Codewarrior) and Windows NT (Visual C++) indicates that we
cannot assume much sophistication in the use of file structure by
development environments. The best that we can hope for is the ability
to combine a fixed list of source files, libraries, and predefined
preprocessor symbols into a single target.</p>
<p><span class="target" id="design.mps.config.build.maint"></span><a class="mpstag reference internal" href="#design.mps.config.build.maint">.build.maint:</a> The maintainability requirement
(<a class="reference internal" href="#design.mps.config.req.maint">.req.maint</a>) implies that we don&#8217;t spend time trying to
develop a set of tools to support anything more complicated than the
simple build function described above. The effort in constructing and
maintaining a portable system of this kind is considerable. Such
efforts have failed in EP.</p>
</div>
</div>
<div class="section" id="implementation">
<h2>7.7. Implementation<a class="headerlink" href="#implementation" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.impl"></span><a class="mpstag reference internal" href="#design.mps.config.impl">.impl:</a> The two implementation files impl.h.config
and impl.h.mpstd can be seen as preprocessor programs which
&#8220;accept&#8221; build parameters and &#8220;emit&#8221; configuration parameters
(<a class="reference internal" href="#design.mps.config.fig.impl">.fig.impl</a>). The build parameters are defined either by the
builder (in the case of target detection) or by the build function (in
the case of selecting the variety).</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="17%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Build parameter →</th>
<th class="head">Header →</th>
<th class="head">Configuration parameters</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">CONFIG_VAR_COOL</span></tt></td>
<td><tt class="docutils literal"><span class="pre">config.h</span></tt></td>
<td><tt class="docutils literal"><span class="pre">AVER_AND_CHECK</span></tt>, <tt class="docutils literal"><span class="pre">EVENT_ALL</span></tt>, etc.</td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">_WIN32</span></tt></td>
<td><tt class="docutils literal"><span class="pre">mpstd.h</span></tt></td>
<td><tt class="docutils literal"><span class="pre">MPS_OS_W3</span></tt>, <tt class="docutils literal"><span class="pre">MPS_BUILD_MV</span></tt>, etc.</td>
</tr>
</tbody>
</table>
<p><span class="target" id="design.mps.config.impl.dep"></span><a class="mpstag reference internal" href="#design.mps.config.impl.dep">.impl.dep:</a> No source code, other than the directives in
impl.h.config and impl.h.mpstd, should depend on
any build parameters. That is, identifiers beginning <tt class="docutils literal"><span class="pre">CONFIG_</span></tt>
should only appear in impl.h.config. Code may depend on
configuration parameters in certain, limited ways, as defined
below (<a class="reference internal" href="#design.mps.config.conf">.conf</a>).</p>
<div class="section" id="target-platform-detection">
<h3>7.7.1. Target Platform Detection<a class="headerlink" href="#target-platform-detection" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.pf"></span><a class="mpstag reference internal" href="#design.mps.config.pf">.pf:</a> The target platform is &#8220;detected&#8221; by the preprocessor
directives in impl.h.mpstd.</p>
<p><span class="target" id="design.mps.config.pf.form"></span><a class="mpstag reference internal" href="#design.mps.config.pf.form">.pf.form:</a> This file consists of sets of directives of the
form:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#elif &lt;conjunction of builder predefinitions&gt;</span>
<span class="cp">#define MPS_PF_&lt;platform code&gt;</span>
<span class="cp">#define MPS_OS_&lt;operating system code&gt;</span>
<span class="cp">#define MPS_ARCH_&lt;architecture code&gt;</span>
<span class="cp">#define MPS_BUILD_&lt;builder code&gt;</span>
<span class="cp">#define MPS_T_WORD &lt;word type&gt;</span>
<span class="cp">#define MPS_WORD_SHIFT &lt;word shift&gt;</span>
<span class="cp">#define MPS_PF_ALIGN &lt;minimum alignment&gt;</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.detect"></span><a class="mpstag reference internal" href="#design.mps.config.pf.detect">.pf.detect:</a> The conjunction of builder predefinitions is a
constant expression which detects the target platform. It is a logical
conjunction of expressions which look for preprocessor symbols defined
by the build environment to indicate the target. These must be
accompanied by a reference to the build tool documentation from which
the symbols came. For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Visual C++ 2.0, Books Online, C/C++ Book, Preprocessor Reference,</span>
<span class="cm"> * Chapter 1: The Preprocessor, Macros, Predefined Macros.</span>
<span class="cm"> */</span>
<span class="cp">#elif defined(_MSC_VER) &amp;&amp; defined(_WIN32) &amp;&amp; defined(_M_IX86)</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.codes"></span><a class="mpstag reference internal" href="#design.mps.config.pf.codes">.pf.codes:</a> The declarations of the platform, operating
system, architecture, and builder codes define preprocessor macros
corresponding the the target detected (<a class="reference internal" href="#design.mps.config.pfm.detect">.pfm.detect</a>). For
example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define MPS_PF_W3I3MV</span>
<span class="cp">#define MPS_OS_W3</span>
<span class="cp">#define MPS_ARCH_I3</span>
<span class="cp">#define MPS_BUILD_MV</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.word"></span><a class="mpstag reference internal" href="#design.mps.config.pf.word">.pf.word:</a> The declaration of <a class="reference internal" href="../topic/platform.html#MPS_T_WORD" title="MPS_T_WORD"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_T_WORD</span></tt></a> defines
the unsigned integral type which corresponds, on the detected target,
to the machine word. It is used to defined the MPS <a class="reference internal" href="type.html#Word" title="Word"><tt class="xref c c-type docutils literal"><span class="pre">Word</span></tt></a> type
(design.mps.type.word). For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define MPS_T_WORD unsigned long</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.word-width"></span><a class="mpstag reference internal" href="#design.mps.config.pf.word-width">.pf.word-width:</a> The declaration of <a class="reference internal" href="../topic/platform.html#MPS_WORD_WIDTH" title="MPS_WORD_WIDTH"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_WORD_WIDTH</span></tt></a>
defines the number of bits in the type defined by
<a class="reference internal" href="../topic/platform.html#MPS_T_WORD" title="MPS_T_WORD"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_T_WORD</span></tt></a> (<a class="reference internal" href="#design.mps.config.pf.word">.pf.word</a>) on the target. For
example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define MPS_WORD_WIDTH 32</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.word-shift"></span><a class="mpstag reference internal" href="#design.mps.config.pf.word-shift">.pf.word-shift:</a> The declaration of <a class="reference internal" href="../topic/platform.html#MPS_WORD_SHIFT" title="MPS_WORD_SHIFT"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_WORD_SHIFT</span></tt></a>
defines the base-2 logarithm of <a class="reference internal" href="../topic/platform.html#MPS_WORD_WIDTH" title="MPS_WORD_WIDTH"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_WORD_WIDTH</span></tt></a>. For
example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define MPS_WORD_SHIFT 5</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.pf.pf-align"></span><a class="mpstag reference internal" href="#design.mps.config.pf.pf-align">.pf.pf-align:</a> The declaration of <a class="reference internal" href="../topic/platform.html#MPS_PF_ALIGN" title="MPS_PF_ALIGN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_PF_ALIGN</span></tt></a>
defines the minimum alignment which must be used for a memory block to
permit any normal processor memory access. In other words, it is the
maximum alignment required by the processor for normal memory access.
For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define MPS_PF_ALIGN 4</span>
</pre></div>
</div>
</div>
<div class="section" id="target-varieties">
<h3>7.7.2. Target varieties<a class="headerlink" href="#target-varieties" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.var"></span><a class="mpstag reference internal" href="#design.mps.config.var">.var:</a> The target variety is handled by preprocessor directives in
impl.h.config.</p>
<p><span class="target" id="design.mps.config.var.form"></span><a class="mpstag reference internal" href="#design.mps.config.var.form">.var.form:</a> The file contains sets of directives of the form:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#elif defined(CONFIG_VAR_DF)</span>
<span class="cp">#define MPS_VAR_DF</span>
<span class="cp">#define ASSERT_MPSI</span>
<span class="cp">#define ASSERT_MPM</span>
<span class="n">etc</span><span class="p">.</span>
</pre></div>
</div>
<p><span class="target" id="design.mps.config.var.detect"></span><a class="mpstag reference internal" href="#design.mps.config.var.detect">.var.detect:</a> The configured variety is one of the variety
preprocessor definitions passed to the build function
(<a class="reference internal" href="#design.mps.config.build.defs">.build.defs</a>), for example, <tt class="docutils literal"><span class="pre">CONFIG_VAR_DF</span></tt>. [These are
decoupled so that it&#8217;s possible to tell the difference between
overridden settings etc. Explain.]</p>
<p><span class="target" id="design.mps.config.var.symbols"></span><a class="mpstag reference internal" href="#design.mps.config.var.symbols">.var.symbols:</a> The directives should define whatever symbols
are necessary to control annotations. These symbols parameterize other
parts of the code, such as the declaration of assertions, etc. The
symbols should all begin with the prefix <tt class="docutils literal"><span class="pre">MPS_VAR_</span></tt>.</p>
<p>[Tidy this up:] Note, anything which can be configured, is configured,
even if it&#8217;s just configured to <tt class="docutils literal"><span class="pre">NONE</span></tt> meaning nothing. This makes
sure that you can&#8217;t choose something by omission. Where these symbols
are used there will be an <tt class="docutils literal"><span class="pre">#error</span></tt> to catch the unused case.
Exception: To allow simple building of the MPS with <tt class="docutils literal"><span class="pre">cc</span> <span class="pre">-c</span> <span class="pre">mps.c</span></tt> we
choose <a class="reference internal" href="../topic/error.html#CONFIG_VAR_HOT" title="CONFIG_VAR_HOT"><tt class="xref c c-macro docutils literal"><span class="pre">CONFIG_VAR_HOT</span></tt></a> by default. [This is a general
principle which applies to other configuration stuff too.]</p>
</div>
</div>
<div class="section" id="source-code-configuration">
<h2>7.8. Source code configuration<a class="headerlink" href="#source-code-configuration" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.config.conf"></span><a class="mpstag reference internal" href="#design.mps.config.conf">.conf:</a> This section describes how the configuration may
affect the source code of the MPS.</p>
<p><span class="target" id="design.mps.config.conf.limit"></span><a class="mpstag reference internal" href="#design.mps.config.conf.limit">.conf.limit:</a> The form of dependency allowed is carefully
limited to ensure that code remains maintainable and portable
(<a class="reference internal" href="#design.mps.config.req.impact">.req.impact</a>).</p>
<p><span class="target" id="design.mps.config.conf.min"></span><a class="mpstag reference internal" href="#design.mps.config.conf.min">.conf.min:</a> The dependency of code on configuration parameters
should be kept to a minimum in order to keep the system maintainable
(<a class="reference internal" href="#design.mps.config.req.impact">.req.impact</a>).</p>
<div class="section" id="configuration-parameters">
<h3>7.8.1. Configuration parameters<a class="headerlink" href="#configuration-parameters" title="Permalink to this headline"></a></h3>
<p><span class="target" id="design.mps.config.conf.params"></span><a class="mpstag reference internal" href="#design.mps.config.conf.params">.conf.params:</a> The compilation of a module is parameterized
by:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">MPS_ARCH_</span><span class="o">&lt;</span><span class="n">arch</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
<span class="n">MPS_OS_</span><span class="o">&lt;</span><span class="n">os</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
<span class="n">MPS_BUILDER_</span><span class="o">&lt;</span><span class="n">builder</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
<span class="n">MPS_PF_</span><span class="o">&lt;</span><span class="n">platform</span><span class="o">-</span><span class="n">code</span><span class="o">&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="abstract-and-concrete-module-interfaces">
<h3>7.8.2. Abstract and concrete module interfaces<a class="headerlink" href="#abstract-and-concrete-module-interfaces" title="Permalink to this headline"></a></h3>
<p>Basic principle: the caller must not be affected by configuration of a
module. This reduces complexity and dependency of configuration.</p>
<p>All callers use the same abstract interface. Caller code does not
change.</p>
<p>Abstract interface includes:</p>
<ul class="simple">
<li>method definitions (logical function prototypes which may be macro
methods)</li>
<li>names of types</li>
<li>names of constants</li>
<li>names of structures and fields which form part of the interface, and
possibly their types, depending on the protocol defined</li>
<li>the protocols</li>
</ul>
<p>The abstract interface to a module may not be altered by a configuration
parameter. However, the concrete interface may vary.</p>
</div>
<div class="section" id="configuring-module-implementations">
<h3>7.8.3. Configuring module implementations<a class="headerlink" href="#configuring-module-implementations" title="Permalink to this headline"></a></h3>
<p>For example, this isn&#8217;t allowed, because there is a change in the
interface:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(PROT_FOO)</span>
<span class="kt">void</span> <span class="n">ProtSpong</span><span class="p">(</span><span class="n">Foo</span> <span class="n">foo</span><span class="p">,</span> <span class="n">Bar</span> <span class="n">bar</span><span class="p">);</span>
<span class="cp">#else</span>
<span class="kt">int</span> <span class="n">ProtSpong</span><span class="p">(</span><span class="n">Bar</span> <span class="n">bar</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">foo</span><span class="p">);</span>
<span class="cp">#endif</span>
</pre></div>
</div>
<p>This example is allowed:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#ifdef PROTECTION</span>
<span class="kt">void</span> <span class="n">ProtSync</span><span class="p">(</span><span class="n">Space</span> <span class="n">space</span><span class="p">);</span>
<span class="cp">/* more decls. */</span>
<span class="cp">#else </span><span class="cm">/* PROTECTION not */</span><span class="cp"></span>
<span class="cp">#define ProtSync(space) NOOP</span>
<span class="cp">/* more decls. */</span>
<span class="cp">#endif </span><span class="cm">/* PROTECTION */</span><span class="cp"></span>
</pre></div>
</div>
<p>And so is this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if defined(PROT_FOO)</span>
<span class="k">typedef</span> <span class="k">struct</span> <span class="n">ProtStruct</span> <span class="p">{</span>
<span class="kt">int</span> <span class="n">foo</span><span class="p">;</span>
<span class="p">}</span> <span class="n">ProtStruct</span><span class="p">;</span>
<span class="cp">#define ProtSpong(prot) X((prot)-&gt;foo)</span>
<span class="cp">#elif defined(PROT_BAR)</span>
<span class="k">typedef</span> <span class="k">struct</span> <span class="n">ProtStruct</span> <span class="p">{</span>
<span class="kt">float</span> <span class="n">bar</span><span class="p">;</span>
<span class="p">}</span> <span class="n">ProtStruct</span><span class="p">;</span>
<span class="cp">#define ProtSpong(prot) Y((prot)-&gt;bar)</span>
<span class="cp">#else</span>
<span class="cp">#error &quot;No PROT_* configured.&quot;</span>
<span class="cp">#endif</span>
</pre></div>
</div>
<p>Configuration parameters may not be used to vary implementations in
<tt class="docutils literal"><span class="pre">.c</span></tt> files. For example, this sort of thing is not allowed:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">map</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">base</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
<span class="p">{</span>
<span class="cp">#if defined(MPS_OS_W3)</span>
<span class="n">VirtualAlloc</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="n">bar</span><span class="p">,</span> <span class="n">base</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="cp">#elif defined(MPS_OS_SU)</span>
<span class="n">mmap</span><span class="p">(</span><span class="n">base</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="n">frob</span><span class="p">);</span>
<span class="cp">#else</span>
<span class="cp">#error &quot;No implementation of map.&quot;</span>
<span class="cp">#endif</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This leads to extreme code spaghetti. In effect, it&#8217;s a &#8220;candy machine
interface&#8221; on source code. This kind of thing should be done by having
several implementations of the same interface in separate source
files. If this leads to duplication of code then that code should be
placed in a separate, common module.</p>
</div>
</div>
<div class="section" id="procedures">
<h2>7.9. Procedures<a class="headerlink" href="#procedures" title="Permalink to this headline"></a></h2>
<p>[Adding an architecture, etc.]</p>
</div>
<div class="section" id="notes">
<h2>7.10. Notes<a class="headerlink" href="#notes" title="Permalink to this headline"></a></h2>
<p>What about constants?</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">7. Configuration</a><ul>
<li><a class="reference internal" href="#introduction">7.1. Introduction</a></li>
<li><a class="reference internal" href="#history">7.2. History</a></li>
<li><a class="reference internal" href="#requirements">7.3. Requirements</a></li>
<li><a class="reference internal" href="#definitions">7.4. Definitions</a></li>
<li><a class="reference internal" href="#overview">7.5. Overview</a></li>
<li><a class="reference internal" href="#the-build-system">7.6. The build system</a><ul>
<li><a class="reference internal" href="#abstract-build-function">7.6.1. Abstract Build Function</a></li>
<li><a class="reference internal" href="#file-structure">7.6.2. File Structure</a></li>
<li><a class="reference internal" href="#modules-and-naming">7.6.3. Modules and Naming</a></li>
<li><a class="reference internal" href="#build-system-rationale">7.6.4. Build System Rationale</a></li>
</ul>
</li>
<li><a class="reference internal" href="#implementation">7.7. Implementation</a><ul>
<li><a class="reference internal" href="#target-platform-detection">7.7.1. Target Platform Detection</a></li>
<li><a class="reference internal" href="#target-varieties">7.7.2. Target varieties</a></li>
</ul>
</li>
<li><a class="reference internal" href="#source-code-configuration">7.8. Source code configuration</a><ul>
<li><a class="reference internal" href="#configuration-parameters">7.8.1. Configuration parameters</a></li>
<li><a class="reference internal" href="#abstract-and-concrete-module-interfaces">7.8.2. Abstract and concrete module interfaces</a></li>
<li><a class="reference internal" href="#configuring-module-implementations">7.8.3. Configuring module implementations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#procedures">7.9. Procedures</a></li>
<li><a class="reference internal" href="#notes">7.10. Notes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="collection.html"
title="previous chapter">6. Collection framework</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="finalize.html"
title="next chapter">8. Finalization</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
<a href="http://www.ravenbrook.com/project/mps/release/">All MPS Kit releases</a>
</p>
<h4>Issues</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/issue/?action=list&amp;view=status%3dopen&amp;display=Job:Priority:Title&amp;sort=Priority">Known issues</a><br>
<a href="http://www.ravenbrook.com/project/mps/issue/?action=fixed&release_fixed=1.111.0">Issues fixed in release 1.111.0</a>
</p><h4>Contact us</h4>
<p class="topless"><a href="mailto:mps-questions@ravenbrook.com">mps-questions@ravenbrook.com</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="finalize.html" title="8. Finalization"
>next</a> |</li>
<li class="right" >
<a href="collection.html" title="6. Collection framework"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Design</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2013, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink