[m-rev.] for review: Fix --link-object <archive> with --restricted-command-line.

[Peter Wang]

On Wed, 6 Aug 2014 12:58:35 +1000 (EST), Julien Fischer <jfischer at opturion.com> wrote:
> 
> Hi Peter,
> 
> On Wed, 6 Aug 2014, Peter Wang wrote:
> 
> > Branches: master, 14.01
> >
> > When --restricted-command-line is enabled, we try to shorten the link
> > command by creating a temporary archive of object files, including files
> > specified with --link-object.  --link-object can also be used to specify
> > archives (.a) to link with,
> 
> The documentation for --link-object says nothing about using it with
> archives, although the first example of its use in the user's guide is
> with an archive.
> 
> If it is intended that --link-object be used with archives, then I think
> the documentation should explicitly say that.

Yes, I think it should be allowed as it's been around and in use for a
while.

Here is a patch for review.

Peter

---

It was not explicitly stated that --link-object and MLOBJS may specify
archives to link with.  The Mercury build system uses that fact, the
documentation contains some examples doing so, and it has been a
consideration since at least commit eadcd7ab00ca5599f4bc371803afd5b106c581f6,
so document it as a supported feature.

compiler/options.m:
doc/reference_manual.texi:
doc/user_guide.texi:
	Mention archives in --link-object and MLOBJS documentation.

diff --git a/compiler/options.m b/compiler/options.m
index 46b817c..15a5533 100644
--- a/compiler/options.m
+++ b/compiler/options.m
@@ -5618,8 +5618,8 @@ options_help_link -->
         "\t-R option above (such as Mac OS X).",
         "-l <library>, --library <library>",
         "\tLink with the specified library.",
-        "--link-object <object-file>",
-        "\tLink with the specified object file.",
+        "--link-object <file>",
+        "\tLink with the specified object or archive file.",
         "--search-lib-files-dir <directory>",
         "--search-library-files-directory <directory>",
         "\tSearch <directory> for Mercury library files have not yet been",
diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index 05b38ac..84ac82d 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -7843,8 +7843,8 @@ implementation-dependent.
 The following text describes how it is done for the University of Melbourne
 Mercury implementation.
 
-To link an existing object file into your Mercury code, use the command line
-option @samp{--link-object}.
+To link an existing object file or archive of object files into your Mercury
+code, use the command line option @samp{--link-object}.
 For example, the following will link the object file @samp{my_function.o} from
 the current directory when compiling the program @samp{prog}:
 
@@ -7859,7 +7859,7 @@ or perhaps the shared version @samp{libfancy_library.so}, from the directory
 @samp{/usr/local/contrib/lib}, when compiling the program @samp{prog}:
 
 @example
-mmc -R/usr/local/contrib/lib -L/usr/local/contrib/lib --lfancy_library prog
+mmc -R/usr/local/contrib/lib -L/usr/local/contrib/lib -lfancy_library prog
 @end example
 
 As illustrated by the example, the command line options @samp{-R}, @samp{-L}
diff --git a/doc/user_guide.texi b/doc/user_guide.texi
index 05c66f6..8353231 100644
--- a/doc/user_guide.texi
+++ b/doc/user_guide.texi
@@ -740,7 +740,7 @@ A list of @samp{-l} options specifying libraries used by the program
 @item MLOBJS and EXTRA_MLOBJS
 @vindex MLOBJS
 @vindex EXTRA_MLOBJS
-A list of extra object files to link into the program (or library)
+A list of extra object files or archives to link into the program or library
 that you are building.
 
 @item C2INITFLAGS and EXTRA_C2INITFLAGS
@@ -9560,10 +9560,10 @@ path is obtained from the shared library and not via the
 Link with the specified library.
 
 @sp 1
- at item --link-object @var{object}
+ at item --link-object @var{file}
 @findex --link-object
 @cindex Object files, linking with
-Link with the specified object file.
+Link with the specified object file or archive of object files.
 
 @sp 1
 @item --search-lib-files-dir @var{directory}
-- 
1.8.4