From 387dd77738619d7e898f063bbeb1b8b6faf6cad5 Mon Sep 17 00:00:00 2001 From: Dilyan Palauzov Date: Fri, 27 Jan 2017 13:20:24 +0000 Subject: [PATCH] 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. --- 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 90e876773fe..a7344337291 100644 --- a/binutils/ChangeLog +++ b/binutils/ChangeLog @@ -1,3 +1,12 @@ +2017-01-27 Dilyan Palauzov + Nick Clifton + + 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 * MAINTAINERS: Add Bernd to Past Maintainers section. diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi index 0a2c4c6ab40..534560a4953 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 b3ca9169257..5501e2f5265 100644 --- a/ld/ChangeLog +++ b/ld/ChangeLog @@ -1,3 +1,11 @@ +2017-01-27 Dilyan Palauzov + Nick Clifton + + 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 * po/sr.po: New Serbian translation. diff --git a/ld/ld.texinfo b/ld/ld.texinfo index 29c2131a2b1..2ce7560f229 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 -- 2.30.2