This document describes the various ways in which you can build the MPS, its manual, its libraries, and the tests and tools that come with it.
You may be building the MPS for a number of different purposes.
Download the latest MPS Kit release from https://www.ravenbrook.com/project/mps/release/.
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".
In the simplest case, you can compile the MPS to an object file with just:
cc -c mps.c (Unix/macOS)
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/macOS)
cl /O2 /c mps.c (Windows)
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/macOS)
cl /Zi /DCONFIG_VAR_COOL /c mps.c (Windows)
If you are using your own 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/macOS)
cl /O2 /c mymps.c (Windows)
This will get your format code inlined with the MPS garbage collector.
If you're building the MPS for an environment without the standard C library, you can exclude 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.
Builds of the MPS manual from the main MPS repo should be available at https://memory-pool-system.readthedocs.io/.
If that's not available, or if you have a variant of the MPS Kit, or are making modifications to the MPS itself, then you should build the manual for yourself. This uses Sphinx https://www.sphinx-doc.org/.
On Unix-like platforms (including macOS), the Makefile in the manual directory can fetch and install a local copy of Sphinx and build the manual, like this:
cd manual
make html
then open manual/html/index.html.
On Windows platforms, follow the Sphinx installation instructions for Windows, then invoke Sphinx as shown in the Makefile in the manual directory.
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.
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 macOS 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.
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 |
fri3ll |
FreeBSD | IA-32 | Clang | fri3ll.gmk |
fri6gc |
FreeBSD | x86-64 | GCC | fri6gc.gmk |
fri6ll |
FreeBSD | x86-64 | Clang | fri6ll.gmk |
lia6gc |
Linux | ARM64 | GCC | lia6gc.gmk |
lia6ll |
Linux | ARM64 | Clang | lia6ll.gmk |
lii3gc |
Linux | IA-32 | GCC | lii3gc.gmk |
lii6gc |
Linux | x86-64 | GCC | lii6gc.gmk |
lii6ll |
Linux | x86-64 | Clang | lii6ll.gmk |
w3i3mv |
Windows | IA-32 | Microsoft C | w3i3mv.nmk |
w3i6mv |
Windows | x86-64 | Microsoft C | w3i6mv.nmk |
xca6ll |
macOS | ARM64 | Clang | mps.xcodeproj |
xci6ll |
macOS | x86-64 | Clang | mps.xcodeproj |
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.
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 64-bit Linux with Clang:
gmake -f lii6ll.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 macOS (64-bit only), 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. lii6ll
) so that you can share the source tree across platforms. On macOS 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 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).
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.
The MPS Kit can build a command-line program mpseventsql
that loads a diagnostic stream of events into a SQLite3 database for processing. In order to build this program, you need to install the SQLite3 development resources.
- On macOS, 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
andmake
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
andmake
as described above.On Windows, you should visit the SQLite Download Page 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 namedsqlite3.c
andsqlite3.h
. Copy these two files into thecode
directory in the MPS Kit. Then in the "Visual Studio Command Prompt", visit thecode
directory and run one of these commands:nmake /f w3i3mv.nmk mpseventsql.exe (32-bit) nmake /f w3i6mv.nmk mpseventsql.exe (64-bit)