Building the Memory Pool System
===============================


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

This document describes the various ways in which you can build the MPS,
its libraries, and the tests and tools that come with it.

You may be building the MPS for a number of different purposes.


Getting hold of the MPS Kit
---------------------------

Download the latest MPS Kit release from `<http://www.ravenbrook.com/project/mps/release/>`_.


Compiling the MPS for your project
----------------------------------

It is easy to compile the MPS.  You can do it separately, or include the
source in your own project'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.

The MPS also comes with Makefiles and IDE project files for building
libraries, tools, and tests.  See "Building the MPS for development".


Compiling for production
........................

In the simplest case, you can compile the MPS to an object file with just::

    cc -c mps.c           (Unix/Mac OS X)
    cl /c mps.c           (Windows)

This will build a "hot" variety (for production) object file for use
with ``mps.h``.  You can greatly improve performance by allowing global
optimization, for example::

    cc -O2 -c mps.c       (Unix/Mac OS X)
    cl /O2 /c mps.c       (Windows)


Compiling for debugging
.......................

You can get a "cool" variety MPS (with more internal checking, for
debugging and development) with::

    cc -g -DCONFIG_VAR_COOL -c mps.c    (Unix/Mac OS X)
    cl /Zi /DCONFIG_VAR_COOL /c mps.c   (Windows)


Optimizing for your object format
.................................

If you are using your own :term:`object format`, 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,
``myformat.c``, then you could make a file ``mymps.c`` containing::

    #include "mps.c"
    #include "myformat.c"

then::

    cc -O2 -c mymps.c     (Unix/Mac OS X)
    cl /O2 /c mymps.c     (Windows)

This will get your format code inlined with the MPS garbage collector.


Compiling without the C library
...............................

If you're building the MPS for an environment without the standard C
library, you can exclude :ref:`the plinth <topic-plinth>` component of
the MPS with::

    cc -DCONFIG_PLINTH_NONE -c mps.c
    cl /Gs /DCONFIG_PLINTH_NONE /c mps.c

but you must then provide your own implementation of ``mpslib.h``.
You can base this on the ANSI plinth in ``mpsliban.c``.

If you want to do anything beyond these simple cases, use the MPS build
as described in the section "Building the MPS for development" below.


Building the MPS for development
--------------------------------

If you'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.]


Prerequisites
.............

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's available free from
`<ftp://ftp.gnu.org/gnu/make/>`_.)  On FreeBSD this can be done as root
with ``pkg_add -r gmake``.

On Windows platforms the NMAKE tool is used. This comes with Microsoft
Visual Studio C++ or the Microsoft Windows SDK.

On Mac OS X the MPS is built using Xcode, either by opening
``mps.xcodeproj`` with the Xcode app, or using the command-line
"xcodebuild" tool, installed from Xcode → Preferences → Downloads →
Components → Command Line Tools.


Platforms
.........

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::

    OSARCT

Where ``OS`` denotes the operating system, ``AR`` the CPU
architecture, and ``CT`` the compiler toolchain.  Here are the
platforms that we have regular access to and on which the MPS works
well:

==========   =========   =============   ============  =================
Platform     OS          Architecture    Compiler      Makefile
==========   =========   =============   ============  =================
``fri3gc``   FreeBSD     IA-32           GCC           ``fri3gc.gmk``
``fri6gc``   FreeBSD     x86_64          GCC           ``fri6gc.gmk``
``lii3gc``   Linux       IA-32           GCC           ``lii3gc.gmk``
``lii6gc``   Linux       x86_64          GCC           ``lii6gc.gmk``
``lii6ll``   Linux       x86_64          Clang         ``lii6ll.gmk``
``xci3ll``   Mac OS X    IA-32           Clang         ``mps.xcodeproj``
``xci6ll``   Mac OS X    x86_64          Clang         ``mps.xcodeproj``
``xci3gc``   Mac OS X    IA-32           GCC (legacy)  ``xci3gc.gmk``
``w3i3mv``   Windows     IA-32           Microsoft C   ``w3i3mv.nmk``
``w3i6mv``   Windows     x86_64          Microsoft C   ``w3i6mv.nmk``
==========   =========   =============   ============  =================

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, Pelles C. If you are interested in support
on any of these platforms or any new platforms, please contact
Ravenbrook at `mps-questions@ravenbrook.com <mailto:mps-questions@ravenbrook.com>`_.


Running make
............

To build all MPS targets on Unix-like platforms, change to the ``code``
directory and run the command::

    make -f <makefile>

where ``make`` is the command for GNU Make.  (Sometimes this will be
``gmake`` or ``gnumake``.)

To build just one target, run::

    make -f <makefile> <target>

To build a restricted set of targets for just one variety, run::

    make -f <makefile> 'VARIETY=<variety>' <target>

For example, to build just the "cool" variety of the ``amcss`` test on
FreeBSD::

    gmake -f fri3gc.gmk VARIETY=cool amcss

On Windows platforms you need to run the "Visual Studio Command Prompt"
from the Start menu.  Then run one of these commands::

    nmake /f w3i3mv.nmk         (32-bit)
    nmake /f w3i6mv.nmk         (64-bit)

You will need to switch your build environment between 32-bit and
64-bit using Microsoft's ``setenv`` command, for example, ``setenv
/x86`` or ``setenv /x64``.

To build just one target, run one of these commands::

    nmake /f w3i3mv.nmk <target>         (32-bit)
    nmake /f w3i6mv.nmk <target>         (64-bit)

On Mac OS X, you can build from the command line with::

    xcodebuild

On most platforms, the output of the build goes to a directory named
after the platform (e.g. ``fri3gc``) so that you can share the source
tree across platforms.  On Mac OS X the output goes in a directory
called ``xc``.  Building generates ``mps.a`` or ``mps.lib`` or
equivalent, a library of object code which you can link with your
application, subject to the :ref:`MPS licensing conditions <license>`.
It also generates a number of test programs, such as ``amcss`` (a
stress test for the Automatic Mostly-Copying pool class) and tools
such as ``mpseventcnv`` (for decoding telemetry logs).


Installing the Memory Pool System
---------------------------------

Unix-like platforms can use the GNU Autoconf ``configure`` script in the
root directory of the MPS Kit to generate a Makefile that can build and
install the MPS.  For example::

    ./configure --prefix=/opt/mps
    make install

will install the MPS public headers in ``/opt/mps/include``, the
libraries in ``/opt/mps/lib`` etc.
    
There is currently no automatic way to "install" the MPS on Windows.

On any platform, you can install by copying the libraries built by the
make to, for example, ``/usr/local/lib``, and all the headers beginning
with ``mps`` to ``/usr/local/include``.

Note, however, that you may get better performance by using the method
described in the section "Optimizing for your object format" above.


mpseventsql
...........

The MPS Kit can build a command-line program ``mpseventsql`` that
loads a diagnostic stream of events into a `SQLite3
<http://www.sqlite.org/>`_ database for processing. In order to build
this program, you need to install the SQLite3 development resources.

* On Mac OS X, SQLite3 is pre-installed, so this tool builds by
  default.

* On Linux, you need to install the ``libsqlite3-dev`` package::

      apt-get install libsqlite3-dev

  and then re-run ``./configure`` and ``make`` as described above.

* On FreeBSD, you need to build and install the ``databases/sqlite3``
  port from the ports collection::

      cd /usr/ports/databases/sqlite3
      make install clean

  and then re-run ``./configure`` and ``make`` as described above.

* On Windows, you should visit the `SQLite Download Page
  <http://www.sqlite.org/download.html>`_ and download the
  ``sqlite-amalgamation`` ZIP archive. (At time of writing this is the
  first download on the page.) When you unzip the archive, you'll find
  it contains files named ``sqlite3.c`` and ``sqlite3.h``. Copy these
  two files into the ``code`` directory in the MPS Kit. Then in the
  "Visual Studio Command Prompt", visit the ``code`` directory and run
  one of these commands::

      nmake /f w3i3mv.nmk mpseventsql.exe         (32-bit)
      nmake /f w3i6mv.nmk mpseventsql.exe         (64-bit)