1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-28 00:01:33 -08:00
emacs/mps/manual/html/guide/build.html
Gareth Rees 28419106ca Build html version of the manual in manual/html.
Check in HTML version of the manual (writable on client) so that it will display automatically on the Ravenbrook server and so that we can easily include it in product releases.

Copied from Perforce
 Change: 180338
 ServerID: perforce.ravenbrook.com
2012-11-05 17:18:50 +00:00

375 lines
No EOL
24 KiB
HTML

<!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>2. Building the Memory Pool System &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="Guide" href="index.html" />
<link rel="next" title="3. Garbage collecting a language with the Memory Pool System" href="lang.html" />
<link rel="prev" title="1. Overview of the Memory Pool System" href="overview.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="lang.html" title="3. Garbage collecting a language with the Memory Pool System"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="overview.html" title="1. Overview of the Memory Pool System"
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">Guide</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="building-the-memory-pool-system">
<span id="guide-build"></span><span id="index-0"></span><h1>2. Building the Memory Pool System<a class="headerlink" href="#building-the-memory-pool-system" title="Permalink to this headline"></a></h1>
<div class="section" id="introduction">
<h2>2.1. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>This document describes the various ways in which you can build the MPS,
its libraries, and the tests and tools that come with it.</p>
<p>You may be building the MPS for a number of different purposes.</p>
</div>
<div class="section" id="compiling-the-mps-for-your-project">
<h2>2.2. Compiling the MPS for your project<a class="headerlink" href="#compiling-the-mps-for-your-project" title="Permalink to this headline"></a></h2>
<p>It is easy to compile the MPS. You can do it separately, or include the
source in your own project&#8217;s build system. This section describes
compilation in terms of command lines, but you can equally add the files
to a project in an IDE.</p>
<p>The MPS also comes with Makefiles and IDE project files for building
libraries, tools, and tests. See &#8220;Building the MPS for development&#8221;.</p>
<div class="section" id="compiling-for-production">
<h3>2.2.1. Compiling for production<a class="headerlink" href="#compiling-for-production" title="Permalink to this headline"></a></h3>
<p>In the simplest case, you can compile the MPS to an object file with just:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Unix</span><span class="o">/</span><span class="n">Mac</span> <span class="n">OS</span> <span class="n">X</span><span class="p">)</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Windows</span><span class="p">)</span>
</pre></div>
</div>
<p>This will build a &#8220;hot&#8221; variety (for production) object file for use
with <tt class="docutils literal"><span class="pre">mps.h</span></tt>. You can greatly improve performance by allowing global
optimization, for example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">O2</span> <span class="o">-</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Unix</span><span class="o">/</span><span class="n">Mac</span> <span class="n">OS</span> <span class="n">X</span><span class="p">)</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">O2</span> <span class="o">/</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Windows</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="compiling-for-debugging">
<h3>2.2.2. Compiling for debugging<a class="headerlink" href="#compiling-for-debugging" title="Permalink to this headline"></a></h3>
<p>You can get a &#8220;cool&#8221; variety MPS (with more internal checking, for
debugging and development) with:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">DCONFIG_VAR_COOL</span> <span class="o">-</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Unix</span><span class="o">/</span><span class="n">Mac</span> <span class="n">OS</span> <span class="n">X</span><span class="p">)</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">Zi</span> <span class="o">/</span><span class="n">DCONFIG_VAR_COOL</span> <span class="o">/</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Windows</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="optimizing-for-your-object-format">
<h3>2.2.3. Optimizing for your object format<a class="headerlink" href="#optimizing-for-your-object-format" title="Permalink to this headline"></a></h3>
<p>If you are using your own <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>, you will also get
improved performance by allowing the compiler to do global optimizations
between it and the MPS. So if your format implementation is in, say,
<tt class="docutils literal"><span class="pre">myformat.c</span></tt>, then you could make a file <tt class="docutils literal"><span class="pre">mymps.c</span></tt> containing:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mps.c&quot;</span>
<span class="cp">#include &quot;myformat.c&quot;</span>
</pre></div>
</div>
<p>then:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">O2</span> <span class="o">-</span><span class="n">c</span> <span class="n">mymps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Unix</span><span class="o">/</span><span class="n">Mac</span> <span class="n">OS</span> <span class="n">X</span><span class="p">)</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">O2</span> <span class="o">/</span><span class="n">c</span> <span class="n">mymps</span><span class="p">.</span><span class="n">c</span> <span class="p">(</span><span class="n">Windows</span><span class="p">)</span>
</pre></div>
</div>
<p>This will get your format code inlined with the MPS garbage collector.</p>
</div>
<div class="section" id="compiling-without-the-c-library">
<h3>2.2.4. Compiling without the C library<a class="headerlink" href="#compiling-without-the-c-library" title="Permalink to this headline"></a></h3>
<p>If you&#8217;re building the MPS for an environment without the standard C
library, you can exclude <a class="reference internal" href="../topic/plinth.html#topic-plinth"><em>the plinth</em></a> component of
the MPS with:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">cc</span> <span class="o">-</span><span class="n">DCONFIG_PLINTH_NONE</span> <span class="o">-</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span>
<span class="n">cl</span> <span class="o">/</span><span class="n">Gs</span> <span class="o">/</span><span class="n">DCONFIG_PLINTH_NONE</span> <span class="o">/</span><span class="n">c</span> <span class="n">mps</span><span class="p">.</span><span class="n">c</span>
</pre></div>
</div>
<p>but you must then provide your own implementation of <tt class="docutils literal"><span class="pre">mpslib.h</span></tt>.
You can base this on the ANSI plinth in <tt class="docutils literal"><span class="pre">mpsliban.c</span></tt>.</p>
<p>If you want to do anything beyond these simple cases, use the MPS build
as described in the section &#8220;Building the MPS for development&#8221; below.</p>
</div>
</div>
<div class="section" id="building-the-mps-for-development">
<h2>2.3. Building the MPS for development<a class="headerlink" href="#building-the-mps-for-development" title="Permalink to this headline"></a></h2>
<p>If you&#8217;re making modifications to the MPS itself, want to build MPS
libraries for linking, or want to build MPS tests and tools, you should
use the MPS build. This uses makefiles or Xcode projects. [Coming
soon, Microsoft Visual Studio solutions.]</p>
<div class="section" id="prerequisites">
<h3>2.3.1. Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h3>
<p>For Unix-like platforms you will need the GNU Make tool. Some platforms
(such as Linux) have GNU Make as their default make tool. For others
you will need to get and install it. (It&#8217;s available free from
<a class="reference external" href="ftp://ftp.gnu.org/gnu/make/">ftp://ftp.gnu.org/gnu/make/</a>.) On FreeBSD this can be done as root
with <tt class="docutils literal"><span class="pre">pkg_add</span> <span class="pre">-r</span> <span class="pre">gmake</span></tt>.</p>
<p>On Windows platforms the NMAKE tool is used. This comes with Microsoft
Visual Studio C++ or the Microsoft Windows SDK.</p>
<p>On Mac OS X the MPS is built using Xcode, either by opening
<tt class="docutils literal"><span class="pre">mps.xcodeproj</span></tt> with the Xcode app, or using the command-line
&#8220;xcodebuild&#8221; tool, installed from Xcode → Preferences → Downloads →
Components → Command Line Tools.</p>
</div>
<div class="section" id="platforms">
<h3>2.3.2. Platforms<a class="headerlink" href="#platforms" title="Permalink to this headline"></a></h3>
<p>The MPS uses a six-character platform code to express a combination of
operating system, CPU architecture, and compiler toolchain. Each
six-character code breaks down into three pairs of characters, like
this:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">OSARCT</span>
</pre></div>
</div>
<p>Where <tt class="docutils literal"><span class="pre">OS</span></tt> denotes the operating system, <tt class="docutils literal"><span class="pre">AR</span></tt> the CPU
architecture, and <tt class="docutils literal"><span class="pre">CT</span></tt> the compiler toolchain. Here are the
platforms that we have regular access to and on which the MPS works
well:</p>
<table border="1" class="docutils">
<colgroup>
<col width="16%" />
<col width="15%" />
<col width="21%" />
<col width="20%" />
<col width="28%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Platform</th>
<th class="head">OS</th>
<th class="head">Architecture</th>
<th class="head">Compiler</th>
<th class="head">Makefile</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">fri3gc</span></tt></td>
<td>FreeBSD</td>
<td>IA-32</td>
<td>GCC</td>
<td><tt class="docutils literal"><span class="pre">fri3gc.gmk</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">fri6gc</span></tt></td>
<td>FreeBSD</td>
<td>x86_64</td>
<td>GCC</td>
<td><tt class="docutils literal"><span class="pre">fri6gc.gmk</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">lii3gc</span></tt></td>
<td>Linux</td>
<td>IA-32</td>
<td>GCC</td>
<td><tt class="docutils literal"><span class="pre">lii3gc.gmk</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">lii6gc</span></tt></td>
<td>Linux</td>
<td>x86_64</td>
<td>GCC</td>
<td><tt class="docutils literal"><span class="pre">lii6gc.gmk</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">xci3ll</span></tt></td>
<td>Mac OS X</td>
<td>IA-32</td>
<td>Clang</td>
<td><tt class="docutils literal"><span class="pre">mps.xcodeproj</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">xci6ll</span></tt></td>
<td>Mac OS X</td>
<td>x86_64</td>
<td>Clang</td>
<td><tt class="docutils literal"><span class="pre">mps.xcodeproj</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">xci3gc</span></tt></td>
<td>Mac OS X</td>
<td>IA-32</td>
<td>GCC (legacy)</td>
<td><tt class="docutils literal"><span class="pre">xci3gc.gmk</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">w3i3mv</span></tt></td>
<td>Windows</td>
<td>IA-32</td>
<td>Microsoft C</td>
<td><tt class="docutils literal"><span class="pre">w3i3mv.nmk</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">w3i6mv</span></tt></td>
<td>Windows</td>
<td>x86_64</td>
<td>Microsoft C</td>
<td><tt class="docutils literal"><span class="pre">w3i6mv.nmk</span></tt></td>
</tr>
</tbody>
</table>
<p>Historically, the MPS worked on a much wider variety of platforms, and
still could: IRIX, OSF/1 (Tru64), Solaris, SunOS, Classic Mac OS;
MIPS, PowerPC, ALPHA, SPARC v8, SPARC v9; Metrowerks Codewarrior,
SunPro C, Digital C, EGCS. If you are interested in support on any of
these platforms or any new platforms, please contact Ravenbrook at
<a class="reference external" href="mailto:mps-questions&#37;&#52;&#48;ravenbrook&#46;com">mps-questions<span>&#64;</span>ravenbrook<span>&#46;</span>com</a>.</p>
</div>
<div class="section" id="running-make">
<h3>2.3.3. Running make<a class="headerlink" href="#running-make" title="Permalink to this headline"></a></h3>
<p>To build all MPS targets on Unix-like platforms, change to the <tt class="docutils literal"><span class="pre">code</span></tt>
directory and type:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="o">&lt;</span><span class="n">makefile</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>where <tt class="docutils literal"><span class="pre">make</span></tt> is the command for GNU Make. (Sometimes this will be
<tt class="docutils literal"><span class="pre">gmake</span></tt> or <tt class="docutils literal"><span class="pre">gnumake</span></tt>.)</p>
<p>To build just one target, type:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="o">&lt;</span><span class="n">makefile</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">target</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>To build a restricted set of targets for just one variety, type:</p>
<div class="highlight-c"><pre>make -f &lt;makefile&gt; 'VARIETY=&lt;variety&gt;' &lt;target&gt;</pre>
</div>
<p>For example, to build just the &#8220;cool&#8221; variety of the <tt class="docutils literal"><span class="pre">amcss</span></tt> test on
FreeBSD:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">gmake</span> <span class="o">-</span><span class="n">f</span> <span class="n">fri3gc</span><span class="p">.</span><span class="n">gmk</span> <span class="n">VARIETY</span><span class="o">=</span><span class="n">cool</span> <span class="n">amcss</span>
</pre></div>
</div>
<p>On Windows platforms you need to run the &#8220;Visual Studio Command Prompt&#8221;
from the Start menu. Then type:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">nmake</span> <span class="o">/</span><span class="n">f</span> <span class="n">w3i3mv</span><span class="p">.</span><span class="n">nmk</span> <span class="p">(</span><span class="mi">32</span><span class="o">-</span><span class="n">bit</span><span class="p">)</span>
<span class="n">nmake</span> <span class="o">/</span><span class="n">f</span> <span class="n">w3i6mv</span><span class="p">.</span><span class="n">nmk</span> <span class="p">(</span><span class="mi">64</span><span class="o">-</span><span class="n">bit</span><span class="p">)</span>
</pre></div>
</div>
<p>You will need to switch your build environment between 32-bit and
64-bit using Microsoft&#8217;s <tt class="docutils literal"><span class="pre">setenv</span></tt> command, for example, <tt class="docutils literal"><span class="pre">setenv</span>
<span class="pre">/x86</span></tt> or <tt class="docutils literal"><span class="pre">setenv</span> <span class="pre">/x64</span></tt>.</p>
<p>To build just one target, type:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">nmake</span> <span class="o">/</span><span class="n">f</span> <span class="n">w3i3mv</span><span class="p">.</span><span class="n">nmk</span> <span class="o">&lt;</span><span class="n">target</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>On Mac OS X, you can build from the command line with:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">xcodebuild</span>
</pre></div>
</div>
<p>On most platforms, the output of the build goes to a directory named
after the platform (e.g. <tt class="docutils literal"><span class="pre">fri3gc</span></tt>) so that you can share the source
tree across platforms. On Mac OS X the output goes in a directory
called <tt class="docutils literal"><span class="pre">xc</span></tt>. Building generates <tt class="docutils literal"><span class="pre">mps.a</span></tt> or <tt class="docutils literal"><span class="pre">mps.lib</span></tt> or
equivalent, a library of object code which you can link with your
application, subject to the <a class="reference internal" href="../copyright.html#license"><em>MPS licensing conditions</em></a>.
It also generates a number of test programs, such as <tt class="docutils literal"><span class="pre">amcss</span></tt> (a
stress test for the Automatic Mostly-Copying pool class) and tools
such as <tt class="docutils literal"><span class="pre">eventcnv</span></tt> (for decoding telemetry logs).</p>
</div>
</div>
<div class="section" id="installing-the-memory-pool-system">
<h2>2.4. Installing the Memory Pool System<a class="headerlink" href="#installing-the-memory-pool-system" title="Permalink to this headline"></a></h2>
<p>Unix-like platforms can use the GNU Autoconf <tt class="docutils literal"><span class="pre">configure</span></tt> script in the
root directory of the MPS Kit to generate a Makefile that can build and
install the MPS. For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="p">.</span><span class="o">/</span><span class="n">configure</span> <span class="o">--</span><span class="n">prefix</span><span class="o">=/</span><span class="n">opt</span><span class="o">/</span><span class="n">mps</span>
<span class="n">make</span> <span class="n">install</span>
</pre></div>
</div>
<p>will install the MPS public headers in <tt class="docutils literal"><span class="pre">/opt/mps/include</span></tt>, the
libraries in <tt class="docutils literal"><span class="pre">/opt/mps/lib</span></tt> etc.</p>
<p>There is currently no automatic way to &#8220;install&#8221; the MPS on Windows.</p>
<p>On any platform, you can install by copying the libraries built by the
make to, for example, <tt class="docutils literal"><span class="pre">/usr/local/lib</span></tt>, and all the headers beginning
with <tt class="docutils literal"><span class="pre">mps</span></tt> to <tt class="docutils literal"><span class="pre">/usr/local/include</span></tt>.</p>
<p>Note, however, that you may get better performance by using the method
described in the section &#8220;Optimizing for your object format&#8221; above.</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="#">2. Building the Memory Pool System</a><ul>
<li><a class="reference internal" href="#introduction">2.1. Introduction</a></li>
<li><a class="reference internal" href="#compiling-the-mps-for-your-project">2.2. Compiling the MPS for your project</a><ul>
<li><a class="reference internal" href="#compiling-for-production">2.2.1. Compiling for production</a></li>
<li><a class="reference internal" href="#compiling-for-debugging">2.2.2. Compiling for debugging</a></li>
<li><a class="reference internal" href="#optimizing-for-your-object-format">2.2.3. Optimizing for your object format</a></li>
<li><a class="reference internal" href="#compiling-without-the-c-library">2.2.4. Compiling without the C library</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-the-mps-for-development">2.3. Building the MPS for development</a><ul>
<li><a class="reference internal" href="#prerequisites">2.3.1. Prerequisites</a></li>
<li><a class="reference internal" href="#platforms">2.3.2. Platforms</a></li>
<li><a class="reference internal" href="#running-make">2.3.3. Running make</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-the-memory-pool-system">2.4. Installing the Memory Pool System</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="overview.html"
title="previous chapter">1. Overview of the Memory Pool System</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="lang.html"
title="next chapter">3. Garbage collecting a language with the Memory Pool System</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="lang.html" title="3. Garbage collecting a language with the Memory Pool System"
>next</a> |</li>
<li class="right" >
<a href="overview.html" title="1. Overview of the Memory Pool System"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Guide</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2012, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>