Skip to content

Commit 387dd77

Browse files
Dilyan Palauzovnickclifton
Dilyan Palauzov
authored and
nickclifton
committed
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.
1 parent 8ec5cf6 commit 387dd77

4 files changed

Lines changed: 90 additions & 18 deletions

File tree

‎binutils/ChangeLog‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
2017-01-27 Dilyan Palauzov <dilyan.palauzov@aegee.org>
2+
Nick Clifton <nickc@redhat.com>
3+
4+
PR 20343
5+
* doc/binutils.texi (ar): Extend documentation of the --plugin
6+
option. Include a description of where the plugins should be
7+
located.
8+
(nm): Likewise.
9+
110
2017-01-23 Nick Clifton <nickc@redhat.com>
211

312
* MAINTAINERS: Add Bernd to Past Maintainers section.

‎binutils/doc/binutils.texi‎

Lines changed: 57 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -392,14 +392,6 @@ If you do not specify a @var{member}, all files in the archive
392392
are extracted.
393393

394394
Files cannot be extracted from a thin archive.
395-
396-
@item --help
397-
Displays the list of command line options supported by @command{ar}
398-
and then exits.
399-
400-
@item --version
401-
Displays the version information of @command{ar} and then exits.
402-
403395
@end table
404396

405397
A number of modifiers (@var{mod}) may immediately follow the @var{p}
@@ -527,22 +519,55 @@ when the modifier @samp{v} is appended.
527519
This modifier shows the version number of @command{ar}.
528520
@end table
529521

522+
The @command{ar} program also supports some command line options which
523+
are neither modifiers nor actions, but which do change its behaviour
524+
in specific ways:
525+
526+
@table @samp
527+
@item --help
528+
Displays the list of command line options supported by @command{ar}
529+
and then exits.
530+
531+
@item --version
532+
Displays the version information of @command{ar} and then exits.
533+
534+
@item -X32_64
530535
@command{ar} ignores an initial option spelt @samp{-X32_64}, for
531536
compatibility with AIX. The behaviour produced by this option is the
532-
default for @sc{gnu} @command{ar}. @command{ar} does not support any of the other
533-
@samp{-X} options; in particular, it does not support @option{-X32}
534-
which is the default for AIX @command{ar}.
537+
default for @sc{gnu} @command{ar}. @command{ar} does not support any
538+
of the other @samp{-X} options; in particular, it does not support
539+
@option{-X32} which is the default for AIX @command{ar}.
535540

536-
The optional command line switch @option{--plugin} @var{name} causes
541+
@item --plugin @var{name}
542+
@cindex plugins
543+
The optional command line switch @option{--plugin @var{name}} causes
537544
@command{ar} to load the plugin called @var{name} which adds support
538-
for more file formats. This option is only available if the toolchain
539-
has been built with plugin support enabled.
540-
541-
The optional command line switch @option{--target} @var{bfdname}
545+
for more file formats, including object files with link-time
546+
optimization information.
547+
548+
This option is only available if the toolchain has been built with
549+
plugin support enabled.
550+
551+
If @option{--plugin} is not provided, but plugin support has been
552+
enabled then @command{ar} iterates over the files in
553+
@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
554+
plugin that claims the object in question is used.
555+
556+
Please note that this plugin search directory is @emph{not} the one
557+
used by @command{ld}'s @option{-plugin} option. In order to make
558+
@command{ar} use the linker plugin it must be copied into the
559+
@file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations
560+
the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang
561+
based compilations it is called @file{LLVMgold.so}. The GCC plugin
562+
is always backwards compatible with earlier versions, so it is
563+
sufficient to just copy the newest one.
564+
565+
@item --target @var{target}
566+
The optional command line switch @option{--target @var{bfdname}}
542567
specifies that the archive members are in an object code format
543568
different from your system's default format. See
544569
@xref{Target Selection}, for more information.
545-
570+
@end table
546571
@c man end
547572

548573
@ignore
@@ -1006,11 +1031,25 @@ to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
10061031
Display only defined symbols for each object file.
10071032

10081033
@item --plugin @var{name}
1009-
@cindex load plugin
1034+
@cindex plugins
10101035
Load the plugin called @var{name} to add support for extra target
10111036
types. This option is only available if the toolchain has been built
10121037
with plugin support enabled.
10131038

1039+
If @option{--plugin} is not provided, but plugin support has been
1040+
enabled then @command{nm} iterates over the files in
1041+
@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
1042+
plugin that claims the object in question is used.
1043+
1044+
Please note that this plugin search directory is @emph{not} the one
1045+
used by @command{ld}'s @option{-plugin} option. In order to make
1046+
@command{nm} use the linker plugin it must be copied into the
1047+
@file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations
1048+
the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang
1049+
based compilations it is called @file{LLVMgold.so}. The GCC plugin
1050+
is always backwards compatible with earlier versions, so it is
1051+
sufficient to just copy the newest one.
1052+
10141053
@item --size-sort
10151054
Sort symbols by size. For ELF objects symbol sizes are read from the
10161055
ELF, for other object types the symbol sizes are computed as the

‎ld/ChangeLog‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
2017-01-27 Dilyan Palauzov <dilyan.palauzov@aegee.org>
2+
Nick Clifton <nickc@redhat.com>
3+
4+
PR 20343
5+
* ld.texinfo (Options): Extend documentation of the --plugin
6+
option. Include a description of where the plugins should be
7+
located.
8+
19
2017-01-27 Nick Clifton <nickc@redhat.com>
210

311
* po/sr.po: New Serbian translation.

‎ld/ld.texinfo‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -828,6 +828,22 @@ the linker may make more use of this option. Also currently there is
828828
no difference in the linker's behaviour for different non-zero values
829829
of this option. Again this may change with future releases.
830830

831+
@kindex -plugin @var{name}
832+
@item -plugin @var{name}
833+
Involve a plugin in the linking process. The @var{name} parameter is
834+
the absolute filename of the plugin. Usually this parameter is
835+
automatically added by the complier, when using link time
836+
optimization, but users can also add their own plugins if they so
837+
wish.
838+
839+
Note that the location of the compiler originated plugins is different
840+
from the place where the @command{ar}, @command{nm} and
841+
@command{ranlib} programs search for their plugins. In order for
842+
those commands to make use of a compiler based plugin it must first be
843+
copied into the @file{$@{libdir@}/bfd-plugins} directory. All gcc
844+
based linker plugins are backward compatible, so it is sufficient to
845+
just copy in the newest one.
846+
831847
@kindex --push-state
832848
@cindex push state governing input file handling
833849
@item --push-state

0 commit comments

Comments
 (0)