[m-rev.] for review: simplified user's guide on building and using libraries with mmc

[Ondrej Bojar]

for review by anyone (Julien? Peter [Ross, if I'm not confusing names]?)

Estimated hours taken: 1.5

Splitted the section on building and using libraries depending on whether 
Mmake or 'mmc --make' is used. Added the instructions for 'mmc --make', 
including instructions on using libraries without installation.

doc/user_guide.texi:
     See above.

Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.511
diff -u -r1.511 user_guide.texi
--- doc/user_guide.texi	22 Feb 2007 07:07:02 -0000	1.511
+++ doc/user_guide.texi	23 Feb 2007 02:05:54 -0000
@@ -554,7 +554,7 @@
  to create directories, by default @samp{mkdir -p}.
  For @samp{mmc --make} whether to install libraries for static or shared
  linking can be specified with the @code{LIB_LINKAGES} variable.
-For more information, see @ref{Installing libraries}.
+For more information, see @ref{Installing libraries with Mmake}.
  @vindex LIBGRADES
  @vindex LIB_LINKAGES
  @vindex INSTALL
@@ -721,7 +721,7 @@
  @vindex MLLIBS
  @vindex EXTRA_MLLIBS
  A list of @samp{-l} options specifying libraries used by the program
-(or library) that you are building.  @xref{Using libraries}.
+(or library) that you are building.  @xref{Using libraries with Mmake}.

  @item MLOBJS and EXTRA_MLOBJS
  @vindex MLOBJS
@@ -756,12 +756,12 @@
  @samp{lib} prefix or extension.
  For example the library including the files @file{libfoo.a} and
  @file{foo.init} would be referred to as just @samp{foo}.
- at xref{Using libraries}.
+ at xref{Using libraries with Mmake}.

  @item EXTRA_LIB_DIRS
  @vindex EXTRA_LIB_DIRS
  A list of extra Mercury library directory hierarchies to search when
-looking for extra libraries.  @xref{Using libraries}.
+looking for extra libraries.  @xref{Using libraries with Mmake}.

  @item INSTALL_PREFIX
  @vindex INSTALL_PREFIX
@@ -899,9 +899,8 @@

  @menu
  * Writing libraries::
-* Building libraries::
-* Installing libraries::
-* Using libraries::
+* Building with mmc::
+* Building with Mmake::
  * Libraries and the Java grade::
  @end menu

@@ -943,8 +942,149 @@
  as in the first example, rather than just a group of
  unrelated modules, as in the second example.

- at node Building libraries
- at section Building libraries
+ at node Building with mmc
+ at section Building with mmc
+
+ at menu
+* Building and installing libraries with mmc::
+* Using installed libraries with mmc::
+* Using non-installed libraries with mmc::
+ at end menu
+
+
+ at node Building and installing libraries with mmc
+ at subsection Building and installing libraries with mmc
+
+To build a library from the source @samp{mypackage.m} (and other included
+modules), run mmc with the following arguments:
+
+ at example
+mmc --make libmypackage
+ at end example
+
+ at noindent
+mmc will create static (non-shared) object libraries
+and, on most platforms, shared object libraries;
+however, we do not yet support the creation of dynamic link
+libraries (DLLs) on Windows.
+Static libraries are created using the standard tools @samp{ar}
+and @samp{ranlib}.
+Shared libraries are created using the @samp{--make-shared-lib}
+option to @samp{ml}.
+In our example, the files @samp{libmypackage.a} and @samp{libmypackage.so}
+should appear next to @samp{mypackage.m}.
+
+The library is most easily used in other programs if you install it to a
+directory. To install the library, issue the following command:
+
+ at example
+mmc --make --install-prefix <dir> libmypackage.install
+ at end example
+
+ at noindent
+mmc will create the directory @samp{<dir>/lib/mercury} and install the library
+compiled in all valid grades and with all interface files. Because several
+grades are usually compiled, installing the library can be a lenghtly process.
+You can specify the set of installed grades using the option
+ at samp{--no-libgrade} followed by @samp{--libgrade <grade>} for all grades you
+with to install.
+
+If no @samp{--install-prefix <dir>} is specified, the library will be 
installed in standard location, next to the Mercury standard library.
+
+
+ at node Using installed libraries with mmc
+ at subsection Using installed libraries with mmc
+ at cindex Libraries, linking with
+ at findex --mld
+ at findex --mercury-library-directory
+ at findex --ml
+ at findex --mercury-library
+
+Once a library is installed, using it is easy.  To use the libraries
+ at samp{mypackage} and @samp{myotherlib}, run mmc with the following options
+added:
+
+ at example
+mmc ... --ml mypackage ... --ml myotherlib ...
+ at end example
+
+ at noindent
+If a library was installed in a different place (using @samp{--install-prefix
+<dir>}), you will also need to add this option:
+
+ at example
+mmc ... --mld <dir>/lib/mercury ...
+ at end example
+
+ at noindent
+Note that @samp{/lib/mercury} has to be added to the searched path. The
+ at samp{--mld} option can be used several times to add more directories to the
+library search path.
+
+You can also specify whether to link executables with the shared or static
+versions of Mercury libraries using @samp{--mercury-linkage shared} or
+ at samp{--mercury-linkage static}.
+
+ at node Using non-installed libraries with mmc
+ at subsection Using non-installed libraries with mmc
+ at cindex Libraries, linking with
+ at findex --search-lib-files-dir
+ at findex --init-file
+ at findex --link-object
+
+Suppose the user wants to link against library @samp{mypackage} without
+installing the library to avoid lenghtly compilation of all installed grades.
+Suppose that the source of the library is stored in the directory @samp{<dir>}
+and that the library has been properly built using @samp{mmc --make
+libmypackage}. To link against the library, the following options have to be
+added to mmc:
+
+ at example
+mmc ... --search-lib-files-dir <dir> \\
+        --init-file <dir>/mypackage.init \\
+        --link-object <dir>/libmypackage.a \\
+    ...
+ at end example
+
+ at noindent
+Note that the option @samp{--ml} is not used.
+
+You need to make sure the library @samp{libmypackage.a} and the main program
+were compiled at the same grade.
+
+If you need to experiment with more grades, be sure to build the library in all
+the grades (building several times using @samp{mmc --grade <grade> --make
+libmypackage}) and use the @samp{libmypackage.a} that is compatible with your
+main program's grade:
+
+ at example
+mmc ... --grade <grade> \\
+        --search-lib-files-dir <dir> \\
+        --init-file <dir>/mypackage.init \\
+        --link-object <dir>/Mercury/<grade>/*/Mercury/lib/libmypackage.a \\
+    ...
+ at end example
+
+ at noindent
+The asterisk @samp{*} represents the architecture of your build system, e.g.
+ at samp{i686-pc-linux-gnu}.
+
+
+ at node Building with Mmake
+ at section Building with Mmake
+
+Note that the use of Mmake is discouraged. Use rather the @samp{--make} option
+to call mmc directly.
+
+ at menu
+* Building libraries with Mmake::
+* Installing libraries with Mmake::
+* Using libraries with Mmake::
+ at end menu
+
+
+ at node Building libraries with Mmake
+ at subsection Building libraries with Mmake
  @cindex Shared objects
  @cindex Shared libraries
  @cindex Static libraries
@@ -1052,8 +1192,8 @@
  which contains a list of the @file{.o} files for that module,
  and @samp{$(MLPICOBJS)} will be the same as @samp{$(MLOBJS)}.

- at node Installing libraries
- at section Installing libraries
+ at node Installing libraries with Mmake
+ at subsection Installing libraries with Mmake

  @samp{mmake} has support for alternative library directory hierarchies.
  These have the same structure as the @file{@var{prefix}/lib/mercury} tree,
@@ -1100,8 +1240,8 @@
  Note that currently it is not possible to set the installation prefix
  on a library-by-library basis.

- at node Using libraries
- at section Using libraries
+ at node Using libraries with Mmake
+ at subsection Using libraries with Mmake
  @cindex Libraries, linking with

  Once a library is installed, using it is easy.
@@ -1129,17 +1269,6 @@
  the relevant interface files, module initialisation files, compiled
  libraries, etc.

- at findex --mld
- at findex --mercury-library-directory
- at findex --ml
- at findex --mercury-library
-To use a library when invoking @samp{mmc} directly, use the @samp{--mld}
-and @samp{--ml} options (@pxref{Link options}).  You can also specify
-whether to link executables with the shared or static versions of Mercury
-libraries using @samp{--mercury-linkage shared} or
- at samp{--mercury-linkage static} (shared libraries are always linked with
-the shared versions of libraries).
-
  Beware that the directory name that you must use in @samp{EXTRA_LIB_DIRS}
  or as the argument of the @samp{--mld} option is not quite the same as
  the name that was specified in the @samp{INSTALL_PREFIX} when the library
@@ -8703,7 +8832,7 @@
  be searched for Mercury libraries.
  This will add @samp{--search-directory}, @samp{--library-directory},
  @samp{--init-file-directory} and @samp{--c-include-directory}
-options as needed.  @xref{Using libraries}.
+options as needed.  @xref{Using installed libraries with mmc}.

  @sp 1
  @item --ml @var{library}
@@ -8711,7 +8840,8 @@
  @findex --ml
  @findex --mercury-library
  @cindex Libraries, linking with
-Link with the specified Mercury library.  @xref{Using libraries}.
+Link with the specified Mercury library.
+  @xref{Using installed libraries with mmc}.

  @sp 1
  @item --mercury-standard-library-directory @var{directory}

-- 
Ondrej Bojar (mailto:obo at cuni.cz / bojar at ufal.mff.cuni.cz)
http://www.cuni.cz/~obo
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------