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

[Peter Wang]

On 2007-03-01, Ondrej Bojar <bojar at csse.unimelb.edu.au> wrote:
> Julien or Peter (the one from the Mercury office), could you please have a 
> look at this?
> Thanks, Ondrej.

Not sure if you meant me, but I'll do it.

> 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}.

Do you need a link to "Installing libraries with mmc" as well?

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

Ditto.

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

Ditto.

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

I'd name this "Building with mmc --make".

> +* 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

Ditto.

> +
> + at menu
> +* Building and installing libraries with mmc::
> +* Using installed libraries with mmc::
> +* Using non-installed libraries with mmc::
> + at end menu

Ditto.

> +
> +
> + 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:

@samp{mmc} here and elsewhere.

> +
> + 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}.

I don't think it's necessary to discuss ar and ranlib and ml here.

You probably want to mention --lib-linkage {static,shared} here as well.

> +In our example, the files @samp{libmypackage.a} and @samp{libmypackage.so}
> +should appear next to @samp{mypackage.m}.

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
> +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.

lengthy

> +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.

wish

> +
> +If no @samp{--install-prefix <dir>} is specified, the library will be
> installed in standard location, next to the Mercury standard library.

in the same directory as 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:

I suggest,
    Once a library is installed, it can be used by running mmc with the
    following options:

> +
> + 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.

lengthy

I don't think you need to give a reason for not installing libraries.
Compilation is not really lengthy anyway, if you use --no-libgrade.

> +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:

Express that without using "Suppose ..." twice in a row :-)

> +
> + 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.

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:

mmc --use-grade-subdirs ...

> +
> + 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}.

The user really shouldn't have to care about the "Mercury/..."
directories, or remembering to include the init file.

I think I read somewhere that the long-term plan was to make the
installed directory hierarchy the same as the uninstalled hierarchy.
Then you could use the --mld and --ml options in all cases (if there was
only --use-grade-subdirs).  But it seems like a lot of work and would
break Mmake in the process.  Anyway, it's just a comment.

> + 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.

Instead, use the ...

I think the rest was fine.

Peter

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