INTRODUCTION
============
Michael T. Richter <ttmrichter@gmail.com>

This document explains the process of bootstrapping a Mercury environment from
the Git repository.

PREREQUISITES
-------------
If you do not have a Mercury environment already set up on your system, you
cannot build the Mercury compiler from revision control, full stop.  Mercury,
like almost every other self-hosted natively-compiled language, needs itself to
compile itself.  To accomplish this you will have to build one of the releases:
either a numbered release (like, say, 11.07.2) or one of the ROTD releases.  For
purposes of bootstrapping from the master branch of the Git repository it is
recommended to start with the most recent ROTD release since older versions of
the Mercury compiler are frequently not able to build the bleeding edge in Git.

The releases can be downloaded from the Mercury website's downloads page:
https://dl.mercurylang.org/index.html.

Other prerequisites can be found in relevant README.* files in the
distribution's root directory.

BUILDING THE PREREQUISITE RELEASE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default the Mercury distribution builds a number and variety of "grades"
(c.f. the user guide).  Building numerous grades is overkill for purposes of
bootstrapping.  After downloading and expanding the selected prerequisite, the
following command sequence should be issued:

----
./configure --enable-minimal-install
make
sudo make install
----

This will do the minimal build necessary to have a usable Mercury compiler for
bootstrapping.  Note that once this prerequisite release is built, there is no
further need for tarballs when building Mercury from Git.

BOOTSTRAPPING
-------------
Once the minimal prerequisite compiler has been built and installed, a
reasonably complete distribution can be bootstrapped.  However the build
tree must be clean or the build may fail.  Clean and then build the complete
distribution by issuing the following command sequence:

----
make realclean
./prepare.sh
./configure
make
sudo make install
----

This, however, will take a surprisingly long time by most prospective users'
standards.  (In particular the `make install` phase will take a very long time.)
This is because, as mentioned above, Mercury compiles its standard library in a
number of grades.  The number of grades, and therefore build time, can be
reduced by using the configure script's `--enable-libgrades=<grade list>`
option, where <grade list> is a comma separated list of grades.  For information
about which grades may be relevant, see the documentation on grades and grade
components:

   https://www.mercurylang.org/information/doc-latest/mercury_user_guide/Grades-and-grade-components.html

People wanting to simply experiment with Mercury would be best-served with
using only the `asm_fast.gc` grade or `hlc.gc` on OS X.

Since building Mercury can take a long time, you may prefer to use multiple
processors during the build process.  Adding "PARALLEL=-jN" without the
quotes to make's command line will tell make to run N tasks at once.
Substitute N with the number of processors in your system, or fewer if you
want to use other processors for other tasks.  For example:

----
make PARALLEL=-j4
sudo make PARALLEL=-j4 install
----

ALTERNATIVES TO BOOTSTRAPPING
-----------------------------
Unless you are planning to contribute to the Mercury project, bootstrapping
from the SCM head is likely not a desired approach.  For just experimenting
with and/or learning the language the best approach is to either download one
of the stable (numbered, like 11.07.2) releases or, if you want to experiment
with the latest and greatest features, one of the more recent ROTD releases.
Doing this eliminates the need to build the compiler twice since a full build
and install can be done directly from the tarballs.

One possible reason to go through a bootstrap (or at least through a quick
`asm_fast.gc` build followed by a more complete build) is that on 64-bit
systems in specific, a bootstrapped compiler is very slightly faster than one
built once from the tarballs.  This is because the tarballs must be compatible
with both 32- and 64-bit systems while a bootstrapped system can take advantage
of 64-bit specific enhancements.

We strongly recommend the use of the `hlc.gc` grade on OS X (See README.macOS.md).

