[m-rev.] diff: simplified user's guide on building and using libraries with mmc
Ondrej Bojar
bojar at csse.unimelb.edu.au
Fri Mar 2 16:51:32 AEDT 2007
Estimated hours taken: 2.5
Promote 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 05:49:10 -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
+The usage of Mmake is 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,141 @@
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 node Building with Mmake
+ at section Building with Mmake
+
+ 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 +1200,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 +1248,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 +1277,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 +6334,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 +8514,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 +8755,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 +8767,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 +8840,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 +8848,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