for review: fix for "Including .c files in libraries."

[Fergus Henderson]

On 26-Jan-1998, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> On 26-Jan-1998, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > Add support to Mmake for new variables MLOBJS and MLPICOBJS,
> > since simply listing object files in MLLIBS doesn't do the
> > right thing in the case when you're building a library package
> > rather than a program.
...
> > doc/user_guide.texi:
> > 	Document the use of MLOBJS and MLPICOBJS.
> 
> This change is fine, but the section in the Mercury Language
> Reference also needs to be updated (it really doesn't belong there,
> but it's probably best to have it there).

Oh, I forgot about that one.  Thanks for pointing that out.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.84
diff -u -u -r1.84 reference_manual.texi
--- reference_manual.texi	1998/01/23 05:41:56	1.84
+++ reference_manual.texi	1998/01/27 04:43:34
@@ -3232,6 +3232,11 @@
 @noindent
 exports a procedure for use by C.
 
+Note that the exported procedure need not be in the same module
+as the @samp{pragma export} declaration; you can export to C
+procedures defined in other modules, including standard library
+procedures, if you wish.
+
 For each Mercury module containing @samp{pragma export} declarations,
 the Mercury implementation will automatically create a header file
 for that module which declares a C function @var{C_Name()}
@@ -3266,7 +3271,21 @@
 in appropriate @samp{type_info} values corresponding to the types
 of the other arguments passed.  These @samp{type_info} arguments can
 be obtained using the Mercury @samp{type_of} function in the Mercury
-standard library module @samp{std_util}.
+standard library module @samp{std_util}.  You may need to also export
+Mercury procedures that call @samp{type_of}, so that the C code can
+construct the appropriate types.  (Note that exporting @samp{type_of}
+directly would be of no help, since it is itself polymorphic!)
+
+Here are some examples of Mercury functions that call @samp{type_of}
+which you might wish to export to C for this purpose.
+
+ at example
+:- func int_type = type_info.
+int_type = type_of(0).
+
+:- func list_type(T) = type_info.
+list_type(X) = type_of([X]).
+ at end example
 
 @node Linking with C object files 
 @subsection Linking with C object files 
@@ -3277,13 +3296,16 @@
 implementation-dependent.  The following text describes how
 it is done for the University of Melbourne Mercury implementation.
 
-To link an existing object file or library into the Mercury executable,
-set the @samp{Mmake} variable @samp{MLLIBS} in the
- at samp{Mmake} file in the directory in which you are working.  For
-example add the following line to the @samp{Mmake} file:
+To link an existing object file into your Mercury code,
+set the @samp{Mmake} variable @samp{MLOBJS} in the
+ at samp{Mmake} file in the directory in which you are working.
+To link an existing library into your Mercury code,
+set the @samp{Mmake} variable @samp{MLLIBS}.
+For example add the following line to the @samp{Mmake} file:
 
 @example
-MLLIBS = my_functions.o -L/usr/local/contrib/lib -lfancy_library
+MLOBJS = my_functions.o
+MLLIBS = -L/usr/local/contrib/lib -lfancy_library
 @end example
 
 As illustrated by the example, the values for @samp{MLLIBS} are similar to
@@ -4118,6 +4140,8 @@
 @example
 :- pragma terminates(@var{Name}/@var{Arity}).
 @end example
+
+ at noindent
 This declaration may be used to inform the compiler that this predicate
 or function is guaranteed to terminate for any input.  This is useful
 when the compiler cannot prove termination of some predicates or 
@@ -4127,6 +4151,8 @@
 @example
 :- pragma does_not_terminate(@var{Name}/@var{Arity}).
 @end example
+
+ at noindent
 This declaration may be used to inform the compiler that this predicate
 does not necessarily terminate.  This is useful for procedures defined
 using the C interface, which the compiler assumes to terminate by
@@ -4135,6 +4161,8 @@
 @example
 :- pragma check_termination(@var{Name}/@var{Arity}).
 @end example
+
+ at noindent
 This pragma forces the compiler to prove termination of this predicate.
 If it cannot prove the termination of the specified predicate or
 function then the compiler will quit with an error message.
-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.