This directory tree contains a version of Emacs master branch that
implements a new garbage collector (GC) for Emacs that is based on
Ravenbrook's Memory Pool System (MPS) library.  The new GC is
concurrent, incremental, and generational.

The maintainers ask users to help the Emacs developers stabilize this
branch, so that we can merge it into the Emacs master branch faster.
That means building this branch, running it, and, crucially, reporting
any bugs that you run into to bug-gnu-emacs@gnu.org.  See the BUGS file
for more information.


Building this branch
====================

This branch can be built with and without the new GC (igc). If you want
to build with igc, you will need to install the MPS library
'libmps'.  How to install the library differs from system to system, see
'Installing libmps' below.

How to build Emacs from a Git checkout is described in the file
INSTALL.REPO.  Everything said there applies to this branch as well.
When you have 'libmps' installed, you can configure Emacs to use it with
the new configure option '--with-mps'.

Use the following configure flags:

  --with-mps=yes	to use the production version of libmps
  --with-mps=debug      to use the debug version of libmps
  --with-mps=no         to not use MPS (or don't use '--with-mps')

In addition, you can run configure with

  --enable-checking=igc_debug

to enable igc-specific assertions.


Installing 'libmps'
===================

macOS with Homebrew
-------------------

Install 'libmps' from Homebrew with

  brew install libmps

Then add something like this to your environment (e.g., to ~/.zprofile):

  export CFLAGS="$CFLAGS -I$(brew --prefix libmps)/include"
  export LDFLAGS="$LDFLAGS -L$(brew --prefix libmps)/lib"

MS-Windows
----------

TDB

Debian...
---------

TBD

Building MPS yourself
---------------------

Clone the MPS repository:

$ git clone https://github.com/Ravenbrook/mps.git

See the file mps/INSTALL for instructions on how to build MPS.  But in
short:

$ cd mps/code

$ gcc -O2 -c mps.c
$ ar rvs libmps.a mps.o

Now copy the header files and libmps.a to a new empty directory of your
choosing (~/mps-artifacts in what follows):

$ mkdir ~/mps-artifacts
$ cp mps*.h libmps.a ~/mps-artifacts

Then you can proceed with building Emacs, telling the `configure` script
where the mps header files and libmps.a are:

$ configure CPPFLAGS=-I/path/to/mps-artifacts LDFLAGS=-L/path/to/mps-artifacts --with-mps=yes <... rest of options ...>

(Replace /path/to/mps-artifacts with the full path to the directory
where you copied the MPS header files and library.)

To build the debug version of MPS:

$ gcc -O0 -g -DCONFIG_VAR_COOL -c mps.c -o mps-debug.o
$ ar rvs libmps-debug.a mps-debug.o
$ cp libmps-debug.a ~/mps-artifacts

Then pass --with-mps=debug instead --with-mps=yes to the Emacs configure
script (it is recommended that you build Emacs in debug mode while
debugging MPS problems, see the INSTALL in the root directory of the
Emacs source tree.)


Debugging the MPS build
=======================

On most systems, MPS uses the SIGSEGV POSIX signal or its emulation as
part of its normal operation.  When running Emacs with MPS support in a
debugger such as GDB, it is important to take this into account, because
the debugger might stop when this signal is raised, and make it look
like Emacs segfaulted.

If you use GDB, it's recommended to use the .gdbinit file in the src/
subdirectory, which configures GDB not to stop in this situation.
Starting GDB from the src directory will cause it automatically load and
read the file, subject to the "auto-load safe-path" setting;
alternatively, you can force GDB to read that file manually, after
starting the debugger:

  (gdb) source /path/to/emacs-igc/src/.gdbinit