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

Ondrej Bojar bojar at csse.unimelb.edu.au
Fri Mar 2 14:10:33 AEDT 2007


Incorporated Peter's and Julien's comments. The first @ref to "Installing 
libraries with Mmake" is in the context of Mmake targets only, no reference to 
mmc --make way is needed.
I also promote mmc --make instead of Mmake, so I ask for a second review.
Peter/Julien, could you please look at it? Thanks, O.



Estimated hours taken: 2.5

Promoting mmc --make instead of Mmake.
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.
Some additional occurrences of mmc wrapped in @samp{}.

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.512
diff -u -r1.512 user_guide.texi
--- doc/user_guide.texi	26 Feb 2007 06:54:20 -0000	1.512
+++ doc/user_guide.texi	2 Mar 2007 03:04:09 -0000
@@ -273,12 +273,17 @@
  @samp{mmc} will put the executable into a file called @file{@var{filename}},
  not @file{a.out}.

-For programs that consist of more than one source file, we @emph{strongly}
-recommend that you use Mmake (@pxref{Using Mmake}).  Mmake will perform
-all the steps listed below, using automatic dependency analysis
-to ensure that things are done in the right order, and that
-steps are not repeated unnecessarily.
-If you use Mmake, then you don't need to understand the details
+For programs that consist of more than one source file, you can use Mmake
+(@pxref{Using Mmake}) or the @samp{--make} option to @samp{mmc}. Currently, the
+use of @samp{mmc --make} is recommended:
+
+ at example
+mmc --make @var{filename}
+ at end example
+
+ at noindent
+If you use Mmake or @samp{mmc --make}, then you don't need to understand the
+details
  of how the Mercury implementation goes about building programs.
  Thus you may wish to skip the rest of this chapter.

@@ -445,8 +450,18 @@
  @cindex Recompiling

  Mmake, short for ``Mercury Make'',
-is a tool for building Mercury programs
-that is built on top of ordinary or GNU Make @footnote{
+is a tool for building Mercury programs.
+The same functionality is now provided in @samp{mmc} directly by using the
+ at samp{--make} option:
+
+ at example
+mmc --make @var{main-module}
+ at end example
+
+ at noindent
+Therefore, the usage of Mmake is currently discouraged.
+
+Mmake is built on top of ordinary or GNU Make @footnote{
  We might eventually add support for ordinary ``Make'' programs,
  but currently only GNU Make is supported.}.
  With Mmake, building even a complicated Mercury program
@@ -552,9 +567,6 @@
  the name of the command to use to install each file, by default
  @samp{cp}. The variable @code{INSTALL_MKDIR} specifies the command to use
  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}.
  @vindex LIBGRADES
  @vindex LIB_LINKAGES
  @vindex INSTALL
@@ -693,6 +705,7 @@
  or @samp{static} to always link with the static versions of Mercury libraries.
  The default is system dependent.
  This variable only has an effect with @samp{mmc --make}.
+ at xref{Using installed libraries with mmc --make}.

  @item MLFLAGS and EXTRA_MLFLAGS
  @vindex MLFLAGS
@@ -721,7 +734,8 @@
  @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}.
+ at xref{Using installed libraries with mmc --make}.

  @item MLOBJS and EXTRA_MLOBJS
  @vindex MLOBJS
@@ -756,12 +770,14 @@
  @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}.
+ at xref{Using installed libraries with mmc --make}.

  @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}.
+ at xref{Using installed libraries with mmc --make}.

  @item INSTALL_PREFIX
  @vindex INSTALL_PREFIX
@@ -837,7 +853,7 @@
  is very useful if you have a machine with more than one CPU.

  As an alternative to Mmake, the Mercury compiler now contains a
-significant part of the functionality of Mmake, using mmc's
+significant part of the functionality of Mmake, using @samp{mmc}'s
  @samp{--make} option.
  @findex --make

@@ -899,9 +915,8 @@

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

@@ -943,8 +958,148 @@
  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 --make
+ at section Building with mmc --make
+
+ at menu
+* Building and installing libraries with mmc --make::
+* Using installed libraries with mmc --make::
+* Using non-installed libraries with mmc --make::
+ at end menu
+
+
+ at node Building and installing libraries with mmc --make
+ at subsection Building and installing libraries with mmc --make
+
+To build a library from the source @samp{mypackage.m} (and other included
+modules), run @samp{mmc} with the following arguments:
+
+ at example
+mmc --make libmypackage
+ at end example
+
+ at noindent
+ at samp{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.
+Use the @samp{mmc} option @samp{--lib-linkage} to specify which versions of the
+library should be created: @samp{shared} or @samp{static}. The
+ at samp{--lib-linkage} option can be specified multiple times.
+In our example, the files @samp{libmypackage.a} and @samp{libmypackage.so}
+should appear in the current directory.
+
+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
+ at samp{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 lengthy
+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
+wish 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 --make
+ at subsection Using installed libraries with mmc --make
+ 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, it can be used by running @samp{mmc} with the
+following options:
+
+ at example
+mmc ... --ml mypackage ... --ml myotherlib ... --ml my_yet_another_lib ...
+ 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 --make
+ at subsection Using non-installed libraries with mmc --make
+ 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. The source of the library is stored in the directory
+ at 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 @samp{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 in 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 ... --use-grade-subdirs \\
+        --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
+Future versions of @samp{mmc} will probably allow to use just the simple
+ at samp{--ml} and @samp{--mld} options even for non-installed libraries.
+
+
+ at node Building with Mmake
+ at section Building with Mmake
+
+Note that the use of Mmake is discouraged. Instead, use the @samp{--make}
+option to call @samp{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 +1207,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 +1255,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 +1284,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
@@ -6197,7 +6341,7 @@
  @itemx --generate-source-file-mapping
  @findex --generate-source-file-mapping
  Output the module name to file name mapping for the list
-of source files given as non-option arguments to mmc
+of source files given as non-option arguments to @samp{mmc}
  to @file{Mercury.modules}. This must be done before
  @samp{mmc --generate-dependencies} if there are any modules
  for which the file name does not match the module name.
@@ -8377,7 +8521,7 @@
  @cindex Options files
  Read the Mercury compiler's configuration information from @var{file}.
  If the @samp{--config-file} option is not set, a default configuration
-will be used, unless @samp{--no-mercury-stdlib-dir} is passed to mmc.
+will be used, unless @samp{--no-mercury-stdlib-dir} is passed to @samp{mmc}.
  The configuration file is just an options file (@pxref{Using Mmake}).

  @sp 1
@@ -8618,7 +8762,7 @@
  @findex --ld-flags
  @findex --ld-flag
  Specify options to be passed to the command
-invoked by mmc to link an executable.
+invoked by @samp{mmc} to link an executable.
  Use @code{mmc --output-link-command} to find out
  which command is used.
  @samp{--ld-flag} should be used for single words which need
@@ -8630,7 +8774,7 @@
  @findex --ld-libflags
  @findex --ld-libflag
  Specify options to be passed to the command
-invoked by mmc to link a shared library.
+invoked by @samp{mmc} to link a shared library.
  Use @code{mmc --output-shared-lib-link-command}
  to find out which command is used.
  @samp{--ld-libflag} should be used for single words which need
@@ -8703,7 +8847,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 --make}.

  @sp 1
  @item --ml @var{library}
@@ -8711,7 +8855,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 --make}.

  @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
--------------------------------------------------------------------------



More information about the reviews mailing list