mercury/README.MacOS

This file documents the port of Mercury to PowerPC Macs running Mac OS X,
i.e. the "powerpc-apple-darwin" configuration. 

-----------------------------
Supported version of Mac OS X
-----------------------------

Mercury has been heavily tested on Mac OS X 10.3 and should build
"out-of-the-box".  Mercury also works with Mac OS X 10.4 subject to the caveat
below regarding which version of gcc to use.

There may be problems with building Mercury on versions of Mac OS X less than
10.3.0.  In particular there may be problems with building and using shared
libraries.  On these systems you will need to pass the
`--enable-darwin-flat-namespace' option to configure.

---------------------------
C compilers and other tools
---------------------------

Assuming that you have installed the Developer Tools, a typical Mac OS X
installation will provide several different versions of gcc.  These will be
from the Apple branch of gcc development rather than mainline branch (although
the differences are relatively minor as far as Mercury is concerned).

Apple gcc 2.95 does not work with Mercury because it cannot handle the length
of some of the identifier names that the Mercury compiler generates.

Apple gcc 3.3 works with Mercury and there are no known issues (other than the
problem with gcc's powerpc backend described below).  We recommend that users
of Mac OS X 10.3 and 10.4 use this version.

Apple gcc 4.0 does not work with Mercury.  Users of Mac OS X 10.4 should
note that this version of gcc is the default one on their systems.

If you are using an Apple build of gcc then you must use the gcc_select
command to set the system's default gcc to that version of gcc.  It is not
sufficient to just point Mercury to a version of gcc using the configure
script's `--with-cc' option.  This restriction applies only to the builds
of gcc supplied by Apple.

Also, Apple's version of gcc includes support for precompiled headers.
Unfortunately this support seems to be somewhat buggy, causing it to sometimes
crash with mysterious errors when building Mercury.  Furthermore, for the
kinds of C code that the Mercury compiler generates, it results in a very big
slow-down, rather than any speedup.  Fortunately this can be disabled by using
the `--traditional-cpp' option.  The Mercury configure script should enable
this option automatically if it is needed.

Mainline gcc 3.3.X and 3.4.X are known to work with Mercury.
Mainline gcc 4.0.X does not.

The version of tar in /usr/bin/tar on some older versions of Mac OS X (e.g.
10.1) doesn't work properly -- it truncates long path names.  Make sure you
use GNU tar, which is available in /sw/bin/gtar, when unpacking the Mercury
source or binary distributions.  (Also, make sure to use GNU tar if/when
*building* such distributions!) The version of tar that comes with Mac OS X
10.3.3 doesn't have this problem.

On PowerPC machines, the linker may have problems linking large executables
(particularly in debug grades; technically when the program requires a branch
larger than +/- 32 MB). It complains about relocation displacements being too
large. The only known workaround for this problem is to replace the
system-provided versions of crt1.o (Darwin module 'Csu') and crt2.o (part of
gcc) with versions that are compiled with the gcc options `-mlongcall' and (if
using gcc < ~ 3.4) `-mlong-branch'. C code generated by the Mercury compiler
will also need to be compiled with the above options. This can be achieved by
adding:

    EXTRA_CFLAGS=-mlongcall -mlong-branch

to your Mercury.options or Mmakefile.

-----------------------------------
Known bugs and unsupported features
-----------------------------------

The following feature is not supported on Mac OS X:
	- interactive queries in mdb

The 'asm_fast' grades will not work on powerpc-darwin machines, primarily
because of a (long-standing) bug in gcc's powerpc backend (GCC bug #10901).
By default the configure script will choose 'reg' as the default base grade.
If you do not intend to use debugging (e.g. with production code), then you
will probably get better performance by using the hlc.gc grade.

Executables created by the Mercury compiler cannot be statically linked
against the system libraries, on Mac OS X.  Setting `MLFLAGS=-static' will
result in an error message like the following from the linker:
	
	ld: can't locate file for: -lcrt0.o
 
The reason that this does not work is that static version of the system
libraries are not installed on OS X systems by default.  (See Technical Q&A
QA118 <http://developer.apple.com/qa/qa2001/qa1118.html> for further details.)

This restriction only applies to system libraries.  Statically linking against
Mercury libraries is fine.

--------------------------
Deep profiling on Mac OS X
--------------------------

The following discussion assumes a standard installation of Mac OS X.  By
default Apache should have been installed as the default webserver.

In order to use the deep profiler you need to ensure that the deep profiling
CGI "script" is installed and that the webserver is running.

The deep profiling CGI script, mdprof_cgi, should be installed in the
directory /Library/WebServer/CGI-Executables.  Mercury's normal installation
process should take care of this if deep profiling is enabled.

To ensure the webserver is running:

- Open the Apple Menu and open the System Preferences window.
- In the `System Preferences' window, click on the icon labelled `Sharing'.
- Make sure that `Personal Web Sharing' is enabled.  If it is then
  the webserver should be running.

The remaining instructions for using the deep profiler are the same as those
in the user guide.  We recommend against using Safari 1.5 as it has been found
to be somewhat unstable with the deep profiler.  (Safari 2 is fine however.)