[m-dev.] diff: document work-around for profiling problem

[Fergus Henderson]

For both main and release branches (as was my previous change to
user_guide.texi).

Estimated hours taken: 1

Document the work-around for a problem with profiling that was
reported by Tomas By <T.By at dcs.shef.ac.uk>.

doc/user_guide.texi:
	Document problems with profiling of dynamically linked executables,
	and suggest using static linking or LD_BIND_NOW as work-arounds.

Workspace: /home/hg/fjh/mercury
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.242
diff -u -d -r1.242 user_guide.texi
--- doc/user_guide.texi	2001/02/24 16:46:27	1.242
+++ doc/user_guide.texi	2001/02/24 16:47:21
@@ -2527,6 +2527,7 @@
 * Displaying the profile::          How to display the profile data.
 * Analysis of results::             How to interpret the output.
 * Memory profiling::                Profiling memory usage rather than time.
+* Profiling and shared libraries::  Profiling dynamically linked executables.
 @end menu
 
 @node Profiling introduction
@@ -2829,6 +2830,24 @@
 It can tell you how much memory was allocated by each procedure,
 but it won't tell you how long the memory was live for,
 or how much of that memory was garbage-collected.
+
+ at node Profiling and shared libraries
+ at section Profiling and shared libraries
+
+On some operating systems, Mercury's profiling doesn't work properly
+with shared libraries.  The symptom is errors ("map__lookup failed")
+or warnings from @samp{mprof}.  On some systems, the problem occurs
+because the C implementation fails to conform to the semantics
+specified by the ISO C standard for programs that use shared
+libraries.  For other systems, we have not been able to analyze the
+cause of the failure (but we suspect that the cause may be the same as
+on those systems where we have been able to analyze it).
+
+If you get errors or warnings from @samp{mprof}, and your program is
+dynamically linked, try rebuilding your application statically linked,
+e.g. by using @samp{MLFLAGS=--static} in your Mmakefile.  Another
+work-around that sometimes works is to set the environment variable
+ at samp{LD_BIND_NOW} to a non-null value before running the program.
 
 @node Invocation
 @chapter Invocation

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
                                    |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------