aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDilyan Palauzov <dilyan.palauzov@aegee.org>2017-01-27 13:20:24 +0000
committerNick Clifton <nickc@redhat.com>2017-01-27 13:20:24 +0000
commit387dd77738619d7e898f063bbeb1b8b6faf6cad5 (patch)
treec48c1c8cf655e2705560a6c45e543b107b773385
parent8ec5cf65a8213988a9f861e6a94d12311e9b04c3 (diff)
downloadgdb-387dd77738619d7e898f063bbeb1b8b6faf6cad5.zip
gdb-387dd77738619d7e898f063bbeb1b8b6faf6cad5.tar.gz
gdb-387dd77738619d7e898f063bbeb1b8b6faf6cad5.tar.bz2
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.
-rw-r--r--binutils/ChangeLog9
-rw-r--r--binutils/doc/binutils.texi75
-rw-r--r--ld/ChangeLog8
-rw-r--r--ld/ld.texinfo16
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