[binutils-gdb] Update description of the -plugin option used by the linker, ar and nm.

[Nick Clifton <nickc at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=387dd77738619d7e898f063bbeb1b8b6faf6cad5

commit 387dd77738619d7e898f063bbeb1b8b6faf6cad5
Author: Dilyan Palauzov <dilyan.palauzov@aegee.org>
Date:   Fri Jan 27 13:20:24 2017 +0000

    Update description of the -plugin option used by the linker, ar and nm.
    
    	PR 20343
    ld	* ld.texinfo (Options): Extend documentation of the --plugin
    	option.  Include a description of where the plugins should be
    	located.
    
    binutils* doc/binutils.texi (ar): Extend documentation of the --plugin
    	option.  Include a description of where the plugins should be
    	located.
    	(nm): Likewise.

Diff:
---
 binutils/ChangeLog         |  9 ++++++
 binutils/doc/binutils.texi | 75 +++++++++++++++++++++++++++++++++++-----------
 ld/ChangeLog               |  8 +++++
 ld/ld.texinfo              | 16 ++++++++++
 4 files changed, 90 insertions(+), 18 deletions(-)

diff --git a/binutils/ChangeLog b/binutils/ChangeLog
index 90e8767..a734433 100644
--- a/binutils/ChangeLog
+++ b/binutils/ChangeLog
@@ -1,3 +1,12 @@
+2017-01-27  Dilyan Palauzov  <dilyan.palauzov@aegee.org>
+	    Nick Clifton  <nickc@redhat.com>
+
+	PR 20343
+	* doc/binutils.texi (ar): Extend documentation of the --plugin
+	option.  Include a description of where the plugins should be
+	located.
+	(nm): Likewise.
+
 2017-01-23  Nick Clifton  <nickc@redhat.com>
 
 	* MAINTAINERS: Add Bernd to Past Maintainers section.
diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
index 0a2c4c6..534560a 100644
--- a/binutils/doc/binutils.texi
+++ b/binutils/doc/binutils.texi
@@ -392,14 +392,6 @@ If you do not specify a @var{member}, all files in the archive
 are extracted.
 
 Files cannot be extracted from a thin archive.
-
-@item --help
-Displays the list of command line options supported by @command{ar}
-and then exits.
-
-@item --version
-Displays the version information of @command{ar} and then exits.
-
 @end table
 
 A number of modifiers (@var{mod}) may immediately follow the @var{p}
@@ -527,22 +519,55 @@ when the modifier @samp{v} is appended.
 This modifier shows the version number of @command{ar}.
 @end table
 
+The @command{ar} program also supports some command line options which
+are neither modifiers nor actions, but which do change its behaviour
+in specific ways:
+
+@table @samp
+@item --help
+Displays the list of command line options supported by @command{ar}
+and then exits.
+
+@item --version
+Displays the version information of @command{ar} and then exits.
+
+@item -X32_64
 @command{ar} ignores an initial option spelt @samp{-X32_64}, for
 compatibility with AIX.  The behaviour produced by this option is the
-default for @sc{gnu} @command{ar}.  @command{ar} does not support any of the other
-@samp{-X} options; in particular, it does not support @option{-X32}
-which is the default for AIX @command{ar}.
+default for @sc{gnu} @command{ar}.  @command{ar} does not support any
+of the other @samp{-X} options; in particular, it does not support
+@option{-X32} which is the default for AIX @command{ar}.
 
-The optional command line switch @option{--plugin} @var{name} causes
+@item --plugin @var{name}
+@cindex plugins
+The optional command line switch @option{--plugin @var{name}} causes 
 @command{ar} to load the plugin called @var{name} which adds support
-for more file formats.  This option is only available if the toolchain
-has been built with plugin support enabled.
-
-The optional command line switch @option{--target} @var{bfdname}
+for more file formats, including object files with link-time
+optimization information.
+
+This option is only available if the toolchain has been built with
+plugin support enabled.
+
+If @option{--plugin} is not provided, but plugin support has been
+enabled then @command{ar} iterates over the files in
+@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
+plugin that claims the object in question is used.
+
+Please note that this plugin search directory is @emph{not} the one
+used by @command{ld}'s @option{-plugin} option.  In order to make
+@command{ar} use the  linker plugin it must be copied into the
+@file{$@{libdir@}/bfd-plugins} directory.  For GCC based compilations
+the linker plugin is called @file{liblto_plugin.so.0.0.0}.  For Clang
+based compilations it is called @file{LLVMgold.so}.  The GCC plugin
+is always backwards compatible with earlier versions, so it is
+sufficient to just copy the newest one.
+
+@item --target @var{target}
+The optional command line switch @option{--target @var{bfdname}}
 specifies that the archive members are in an object code format
 different from your system's default format.  See
 @xref{Target Selection}, for more information.
-
+@end table
 @c man end
 
 @ignore
@@ -1006,11 +1031,25 @@ to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
 Display only defined symbols for each object file.
 
 @item --plugin @var{name}
-@cindex load plugin
+@cindex plugins
 Load the plugin called @var{name} to add support for extra target
 types.  This option is only available if the toolchain has been built
 with plugin support enabled.
 
+If @option{--plugin} is not provided, but plugin support has been
+enabled then @command{nm} iterates over the files in
+@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
+plugin that claims the object in question is used.
+
+Please note that this plugin search directory is @emph{not} the one
+used by @command{ld}'s @option{-plugin} option.  In order to make
+@command{nm} use the  linker plugin it must be copied into the
+@file{$@{libdir@}/bfd-plugins} directory.  For GCC based compilations
+the linker plugin is called @file{liblto_plugin.so.0.0.0}.  For Clang
+based compilations it is called @file{LLVMgold.so}.  The GCC plugin
+is always backwards compatible with earlier versions, so it is
+sufficient to just copy the newest one.
+
 @item --size-sort
 Sort symbols by size.  For ELF objects symbol sizes are read from the
 ELF, for other object types the symbol sizes are computed as the
diff --git a/ld/ChangeLog b/ld/ChangeLog
index b3ca916..5501e2f 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,11 @@
+2017-01-27  Dilyan Palauzov  <dilyan.palauzov@aegee.org>
+	    Nick Clifton  <nickc@redhat.com>
+
+	PR 20343
+	* ld.texinfo (Options): Extend documentation of the --plugin
+	option.  Include a description of where the plugins should be
+	located.
+
 2017-01-27  Nick Clifton  <nickc@redhat.com>
 
 	* po/sr.po: New Serbian translation.
diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 29c2131..2ce7560 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -828,6 +828,22 @@ the linker may make more use of this option.  Also currently there is
 no difference in the linker's behaviour for different non-zero values
 of this option.  Again this may change with future releases.
 
+@kindex -plugin @var{name}
+@item -plugin @var{name}
+Involve a plugin in the linking process.  The @var{name} parameter is
+the absolute filename of the plugin.  Usually this parameter is
+automatically added by the complier, when using link time
+optimization, but users can also add their own plugins if they so
+wish.
+
+Note that the location of the compiler originated plugins is different
+from the place where the @command{ar}, @command{nm} and
+@command{ranlib} programs search for their plugins.  In order for
+those commands to make use of a compiler based plugin it must first be
+copied into the @file{$@{libdir@}/bfd-plugins} directory.  All gcc
+based linker plugins are backward compatible, so it is sufficient to
+just copy in the newest one. 
+
 @kindex --push-state
 @cindex push state governing input file handling
 @item --push-state