doc bug - building packages.

[Fergus Henderson]

On 20-Jan-1998, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> The instructions for using a package in the Mercury User's Guide
> don't adequately cover the case where you are using a package to
> build a package. In particular, the -lsome_package should be
> removed in this case (unless you deliberately want to package a
> package inside another one).

Hmm.  This seems to be system-dependent.  On at least some systems,
I think Alpha and/or Irix, the `-lsome_package' is needed when
building shared libraries to avoid warnings and/or errors
about unresolved externals. 

>From the dec-alpha-osf3.2 man page for `ld':

 |   -warning_unresolved
 |	Unresolved symbols, except those matching -expect_unresolved, produce a
 |	warning message.  This is the default behavior for building shared
 |	libraries.
 |
 |  -error_unresolved
 |	Unresolved symbols, except those matching -expect_unresolved, produce
 |	an error and the link fails.  This is the default behavior for linking
 |	executable programs.

If on the particular platform, Mercury does not support shared libraries,
then include `-lsome_package' in MLLIBS won't matter, since the MLLIBS
variable is ignored when creating ordinary `.a' libraries.
On the other hand, if Mercury does support shared libraries, then
the other package you are linking in will presumably be a shared library too,
and in that case the `-lsome_package' (a) is important for preventing
warnings and/or errors about unresolved symbols and (b) will not
result in some_package being packaged inside this package, but
will merely result in this package dynamically linking in some_package.

Note that if you *don't* specify appropriate `-l' options, there is
no way for the linker to warn you if the shared library you create
contains genuine unresolved references.

> The -R and -L MLFLAGS are useless, but don't seem to do any harm.

The `-R' flag is definitely necessary in some circumstances,
e.g. when creating a shared library on Linux that links in other
shared libraries.  To quote from a previous log message for
library/Mmakefile:

	"Linux requires the `-rpath' option be specified when linking
	the shared libraries, as well as when linking executables."

Of course, it may be that on Linux you don't have to link in the
other shared libraries at all, but that's needed to avoid warnings
on Alpha/OSF.

Still, despite all the above, if you think the user guide could be
improved, then I'm open to suggestions.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.