[m-rev.] for review: document stand-alone interfaces

[Julien Fischer]

For review by anyone.

Estimated hours taken: 5
Branches: main

Document stand-alone interfaces.

Minor fixes to user's guide.

doc/user_guide.texi:
 	Add a new chapter on stand-alone interfaces.

 	Fix some doubled-up words.

 	Fix some typos:
 		s/procecedure/procedure/
 		s/managment/management/

 	Fix some omissions from the function index.

compiler/options.m:
 	Uncomment (actually, rewrite) the documentation for the
 	`--generate-standalone-interface' option.

NEWS:
 	Announce stand-alone interfaces.

Julien.

Index: NEWS
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/NEWS,v
retrieving revision 1.466
diff -u -r1.466 NEWS
--- NEWS	12 Jun 2007 06:06:25 -0000	1.466
+++ NEWS	18 Jun 2007 08:40:19 -0000
@@ -188,6 +188,9 @@
  * We have made it easier to use single-precision floats, which do not need
    to be boxed on 32-bit machines.

+* A new option, `--generate-standalone-interface', simplifies the task
+  of calling Mercury procedures from programs written in other languages.
+
  Changes to the Mercury deep profiler:

  * The deep profiler now supports measuring a proxy for time: a counter that
@@ -281,6 +284,12 @@
  * Single-precision floats can now be selected for the C backends by using the
    `.spf' grade component, or passing the `--single-prec-float' option to the
    compiler.
+
+* The option `--generate-standalone-interface', causes the compiler to
+  create a "stand-alone" interface to the Mercury runtime and a set of
+  Mercury libraries.  This interface allows programs written in languages
+  such as C or C++ to correctly initialise the Mercury runtime and libraries
+  prior to calling any foreign exported procedures defined in those libraries.

  Changes to the Mercury standard library:

Index: compiler/options.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.566
diff -u -r1.566 options.m
--- compiler/options.m	13 Jun 2007 02:48:43 -0000	1.566
+++ compiler/options.m	18 Jun 2007 08:40:19 -0000
@@ -3151,12 +3151,11 @@
          "\tOutput the strongly connected components of the module",
          "\tdependency graph in top-down order to `<module>.order'.",
          "\tImplies --generate-dependencies.",
-        % XXX This documentation is commented out until the user's
-        % guide is updated.
-        %"--generate-standalone-interface <name>",
-        %"\tOutput an object file that can be used to embed the Mercury",
-        %"\truntime in an application written in a foreign language.",
-        %"\tSee Users's guide for more details.",
+        "--generate-standalone-interface <basename>",
+        "\tOutput a stand-alone interface.",
+        "\t<basename> is used as the basename of any files generated for",
+        "\tthe stand-alone interface.  (See the Stand-alone Interface",
+        "\tchapter of the Mercury User's Guide for further details.)",
          "-i, --make-int, --make-interface",
          "\tWrite the module interface to `<module>.int',",
          "\tand write the short interface to `<module>.int2'",
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.527
diff -u -r1.527 user_guide.texi
--- doc/user_guide.texi	15 Jun 2007 08:26:40 -0000	1.527
+++ doc/user_guide.texi	18 Jun 2007 08:40:19 -0000
@@ -118,6 +118,8 @@
  * C compilers::     How to use a C compiler other than GNU C.
  * Foreign language interface:: Interfacing to other programming
  		    languages from Mercury.
+* Stand-alone Interfaces:: Calling procedures in Mercury libraries from
+                           programs written in other languages.
  * Index::
  @end menu
  @end ifnottex
@@ -2350,7 +2352,7 @@
  they may be either ordinary attributes, or previously synthesized attributes.
  A synthesized attribute is not allowed
  to depend on itself directly or indirectly,
-but there are no restrictions on the positions of of synthesized attributes
+but there are no restrictions on the positions of synthesized attributes
  compared to the positions of the function attributes computing them
  or of the argument attributes of the synthesis functions.
  @end itemize
@@ -4538,7 +4540,7 @@
  @sp 1
  @item ambiguity [-o @var{filename}] [-ptf] [@var{modulename} ...]
  @kindex ambiguity (mdb command)
-Print ambiguous procecedure, type constructor and/or function symbol names.
+Print ambiguous procedure, type constructor and/or function symbol names.
  A procedure name is ambiguous
  if a predicate or function is defined with that name
  in more than one module or with more than one arity.
@@ -5507,7 +5509,7 @@
  unless this is overridden by the @samp{-o} or @samp{--output-file} option.
  @sp 1
  If the @samp{-d} or @samp{--detailed} option is specified,
-then the the output will list all the @emph{events} in the program
+then the output will list all the @emph{events} in the program
  that were not executed in any of these runs.
  This option can thus show the unexecuted parts of the executed procedures.
  @sp 1
@@ -6418,6 +6420,7 @@
  If there are no such modules the mapping need not be
  generated.

+ at sp 1
  @item -M
  @itemx --generate-dependencies
  @findex -M
@@ -6427,15 +6430,26 @@
  dependencies to @file{@var{module}.dep}, @file{@var{module}.dv} and the
  relevant @samp{.d} files.

+ at sp 1
  @itemx --generate-dependency-file
  @findex --generate-dependency-file
  Output `Make'-style dependencies for the module to @file{@var{module}.d}'.

+ at sp 1
  @item --generate-module-order
+ at findex --generate-module-order
  Output the strongly connected components of the module
  dependency graph in top-down order to @file{@var{module}.order}.
  Implies @samp{--generate-dependencies}.

+ at sp 1
+ at item --generate-standalone-interface @var{basename}
+ at findex --generate-standalone-interface @var{basename}
+Output a stand-alone interface.  @var{basename} is used as
+the basename of any files generated for the stand-alone interface.
+(See @pxref{Stand-alone Interfaces} for further details.)
+
+ at sp 1
  @item --generate-mmc-deps
  @itemx --generate-mmc-make-module-dependencies
  @findex --generate-mmc-deps
@@ -7512,7 +7526,7 @@
  @c RBMM is undocumented since it is still experimental.
  @c @sp 1
  @c @item @code{--use-regions} (grades: any grade containing @samp{.rbmm}) 
- at c Enable support for region-based memory managment."
+ at c Enable support for region-based memory management."

  @end table

@@ -9682,8 +9696,100 @@
  Only available on backends that compile to IL.
  This is the third preferred foreign language for IL code generation.

-
  @end table
+
+ at c ----------------------------------------------------------------------------
+
+ at node Stand-alone Interfaces
+ at chapter Stand-alone Interfaces
+
+Programs written in a language other than Mercury should not make calls
+to foreign exported Mercury procedures unless the Mercury runtime has been
+initialised.
+(In the case where the Mercury runtime has not been intialised the
+behaviour of these calls is undefined.)
+Such programs must also ensure that any module specific initialisation is
+performed before calling foreign exported procedures in Mercury modules.
+Likewise, module specific finalisation may need to be performed after
+all calls to Mercury procedures have been made.
+
+A stand-alone interface provides a mechanism by which non-Mercury programs
+may initialise (and shut down) the Mercury runtime plus a specified set
+of Mercury libraries.
+
+A stand-alone interface is created by invoking the compiler with the
+ at samp{--generate-standalone-interface} option. 
+The set of Mercury libraries to be included in the stand-alone interface
+is given via one of the usual mechanisms for specifying what libraries to link
+against, e.g. the @samp{--ml} and @samp{--mld} options.
+(See @pxref{Libraries} for further details).
+The Mercury standard library is always included in this set.
+
+In C grades the @samp{--generate-standalone-interface} option causes
+the compiler to generate an object file that should be linked into
+the executable.
+This object file contains two functions:
+ at code{mercury_init()} and @code{mercury_terminate()}.
+The compiler also generates a C header file that contains 
+the prototypes of these functions.
+(This header file may be included in C++ programs.)
+The roles of the two functions are described below.
+
+ at table @b
+ at item @bullet{} @code{mercury_init()}
+Prototype:
+ at example
+void mercury_init(int @var{argc}, char **@var{argv}, void *@var{stackbottom});
+ at end example
+
+Initialise the Mercury runtime, standard library and any other Mercury
+libraries that were specified when the stand-alone interface was generated.
+ at var{argc} and @var{argv} are the argument count and argument vector,
+as would be passed to the function @code{main()} in a C program.
+ at var{stackbottom} is the address of the base of the stack.
+In grades that use conservative garbage collection this is used to
+tell the collector where to begin tracing.
+This function must be called before any Mercury procedures
+and must only be called once.
+It is recommended that the value of @var{stackbottom} be set by passing
+the address of a local variable in the @code{main()} function of a program,
+for example:
+ at example
+    int main(int argc, char **argv) @{
+        void *dummy;
+        mercury_init(argc, argv, &dummy);
+        @dots{}
+    @}
+ at end example
+Note that the address of the stack base should be word aligned as
+some garbage collectors rely upon this.
+(This is why the type of the dummy variable in the above example is
+ at code{void *}.)
+
+ at sp 1
+ at item @bullet{} @code{mercury_terminate()}
+Prototype:
+ at example
+int mercury_terminate(void);
+ at end example
+
+Shut down the Mercury runtime.
+The value returned by this function is Mercury's exit status
+(as set by the predicate io.set_exit_status/3).
+This function will also invoke any finalisers contained in the set
+of libraries for which the stand-alone interface was generated.
+ at end table
+
+The basename of the object and header file are provided as
+the argument of @samp{--generate-standalone-interface} option.
+
+ at c XXX Mention that stand-alone interfaces work with debugging or
+ at c (deep) profiling?
+
+Stand-alone interfaces are not currently supported for target languages
+other than C.
+For an example of using a stand-alone interface see the
+ at samp{samples/c_interface/standalone_c} directory in the Mercury distribution.

  @c ----------------------------------------------------------------------------


--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------