This is the mail archive of the
binutils@sourceware.org
mailing list for the binutils project.
PATCH: tidy documentation of ld command-line option syntax
- From: Sandra Loosemore <sandra at codesourcery dot com>
- To: binutils at sourceware dot org
- Date: Sun, 22 Feb 2009 22:15:25 -0500
- Subject: PATCH: tidy documentation of ld command-line option syntax
We've noticed that users have a hard time figuring out how to pass linker
options that take arguments on the gcc command line, using -Xlinker or -Wl.
When options are documented in the ld manual as "--option value", from gcc you
have to do "-Xlinker --option -Xlinker value" or "-Wl,--option,value" to get
that effect, and that seems to really confuse people.
OTOH, ld already defines that "--option=value" is equivalent to "--option value"
for all long options, and from the gcc command line, this is much less
user-error-prone; you can just say the obvious "-Xlinker --option=value" or
"-Wl,--option=value". While the "--option=value" syntax is already discussed
generally in the ld manual, and many ld command-line options are already
documented that way, several others are not. This patch fixes the documentation
of those remaining long options to consistently use the "--option=value" syntax.
To come up with this patch, I went through the entire ld_options array in
lexsup.c.
OK to commit?
-Sandra
2009-02-22 Sandra Loosemore <sandra@codesourcery.com>
ld/
* ld.texinfo (-f/--auxiliary): Use consistent syntax for
documenting option arguments. Clean up indexing and markup.
(-F/--filter): Likewise.
(-fini): Likewise.
(-G/--gpsize): Likewise.
(-init): Likewise.
(-defsym): Likewise.
(-I/--dynamic-linker): Likewise.
(-Map): Likewise.
(--oformat): Likewise.
(--retain-symbols-file): Likewise.
(-rpath): Likewise.
(-rpath-link): Likewise.
(--sort-common): Likewise.
(--sort-section): Likewise.
(--split-by-file): Likewise.
(--split-by-reloc): Likewise.
(--sysroot): Likewise.
(--section-start): Likewise.
(-Tbss, -Tdata, -Ttext): Likewise.
(-Ttext-segment): Likewise.
(--version-script): Likewise.
(--wrap): Likewise.
Index: ld/ld.texinfo
===================================================================
--- ld/ld.texinfo (revision 237361)
+++ ld/ld.texinfo (working copy)
@@ -514,10 +514,10 @@ Link big-endian objects. This affects t
Link little-endian objects. This affects the default output format.
@end ifclear
-@kindex -f
-@kindex --auxiliary
-@item -f
-@itemx --auxiliary @var{name}
+@kindex -f@var{name}
+@kindex --auxiliary=@var{name}
+@item -f@var{name}
+@itemx --auxiliary=@var{name}
When creating an ELF shared object, set the internal DT_AUXILIARY field
to the specified name. This tells the dynamic linker that the symbol
table of the shared object should be used as an auxiliary filter on the
@@ -536,10 +536,10 @@ machine specific performance.
This option may be specified more than once. The DT_AUXILIARY entries
will be created in the order in which they appear on the command line.
-@kindex -F
-@kindex --filter
-@item -F @var{name}
-@itemx --filter @var{name}
+@kindex -F@var{name}
+@kindex --filter=@var{name}
+@item -F@var{name}
+@itemx --filter=@var{name}
When creating an ELF shared object, set the internal DT_FILTER field to
the specified name. This tells the dynamic linker that the symbol table
of the shared object which is being created should be used as a filter
@@ -566,8 +566,8 @@ The @sc{gnu} linker will ignore the @opt
creating an ELF shared object.
@cindex finalization function
-@kindex -fini
-@item -fini @var{name}
+@kindex -fini=@var{name}
+@item -fini=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is unloaded, by setting DT_FINI to the
address of the function. By default, the linker uses @code{_fini} as
@@ -577,8 +577,8 @@ the function to call.
@item -g
Ignored. Provided for compatibility with other tools.
-@kindex -G
-@kindex --gpsize
+@kindex -G@var{value}
+@kindex --gpsize=@var{value}
@cindex object size
@item -G@var{value}
@itemx --gpsize=@var{value}
@@ -604,8 +604,8 @@ field rather than the using the file nam
Perform an incremental link (same as option @samp{-r}).
@cindex initialization function
-@kindex -init
-@item -init @var{name}
+@kindex -init=@var{name}
+@item -init=@var{name}
When creating an ELF executable or shared object, call NAME when the
executable or shared object is loaded, by setting DT_INIT to the address
of the function. By default, the linker uses @code{_init} as the
@@ -1244,8 +1244,8 @@ duplicate when there are many dynamic mo
paths for runtime symbol resolution.
@cindex symbols, from command line
-@kindex --defsym @var{symbol}=@var{exp}
-@item --defsym @var{symbol}=@var{expression}
+@kindex --defsym=@var{symbol}=@var{exp}
+@item --defsym=@var{symbol}=@var{expression}
Create a global symbol in the output file, containing the absolute
address given by @var{expression}. You may use this option as many
times as necessary to define multiple symbols in the command line. A
@@ -1275,8 +1275,9 @@ is set. These options may be used to ov
@cindex dynamic linker, from command line
@kindex -I@var{file}
-@kindex --dynamic-linker @var{file}
-@item --dynamic-linker @var{file}
+@kindex --dynamic-linker=@var{file}
+@item -I@var{file}
+@itemx --dynamic-linker=@var{file}
Set the name of the dynamic linker. This is only meaningful when
generating dynamically linked ELF executables. The default dynamic
linker is normally correct; don't use this unless you know what you are
@@ -1347,8 +1348,8 @@ Print a summary of the command-line opti
@item --target-help
Print a summary of all target specific options on the standard output and exit.
-@kindex -Map
-@item -Map @var{mapfile}
+@kindex -Map=@var{mapfile}
+@item -Map=@var{mapfile}
Print a link map to the file @var{mapfile}. See the description of the
@option{-M} option, above.
@@ -1463,8 +1464,8 @@ command line. Library directories speci
(including linker scripts specified on the command line) are ignored.
@ifclear SingleFormat
-@kindex --oformat
-@item --oformat @var{output-format}
+@kindex --oformat=@var{output-format}
+@item --oformat=@var{output-format}
@command{ld} may be configured to support more than one kind of object
file. If your @command{ld} is configured this way, you can use the
@samp{--oformat} option to specify the binary format for the output
@@ -1542,7 +1543,8 @@ but ignored.
@cindex retaining specified symbols
@cindex stripping all but some symbols
@cindex symbols, retaining selectively
-@item --retain-symbols-file @var{filename}
+@kindex --retain-symbols-file=@var{filename}
+@item --retain-symbols-file=@var{filename}
Retain @emph{only} the symbols listed in the file @var{filename},
discarding all others. @var{filename} is simply a flat file, with one
symbol name per line. This option is especially useful in environments
@@ -1559,9 +1561,9 @@ You may only specify @samp{--retain-symb
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
-@item -rpath @var{dir}
+@item -rpath=@var{dir}
@cindex runtime library search path
-@kindex -rpath
+@kindex -rpath=@var{dir}
Add a directory to the runtime library search path. This is used when
linking an ELF executable with shared objects. All @option{-rpath}
arguments are concatenated and passed to the runtime linker, which uses
@@ -1587,8 +1589,8 @@ the @option{-rpath} option.
@ifset GENERIC
@cindex link-time runtime library search path
-@kindex -rpath-link
-@item -rpath-link @var{DIR}
+@kindex -rpath-link=@var{dir}
+@item -rpath-link=@var{dir}
When using ELF or SunOS, one shared library may require another. This
happens when an @code{ld -shared} link includes a shared library as one
of the input files.
@@ -1656,8 +1658,10 @@ and SunOS platforms. On SunOS, the link
shared library if the @option{-e} option is not used and there are
undefined symbols in the link.
-@item --sort-common [= ascending | descending]
@kindex --sort-common
+@item --sort-common
+@itemx --sort-common=ascending
+@itemx --sort-common=descending
This option tells @command{ld} to sort the common symbols by alignment in
ascending or descending order when it places them in the appropriate output
sections. The symbol alignments considered are sixteen-byte or larger,
@@ -1665,24 +1669,24 @@ eight-byte, four-byte, two-byte, and one
between symbols due to alignment constraints. If no sorting order is
specified, then descending order is assumed.
-@kindex --sort-section name
-@item --sort-section name
+@kindex --sort-section=name
+@item --sort-section=name
This option will apply @code{SORT_BY_NAME} to all wildcard section
patterns in the linker script.
-@kindex --sort-section alignment
-@item --sort-section alignment
+@kindex --sort-section=alignment
+@item --sort-section=alignment
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
patterns in the linker script.
@kindex --split-by-file
-@item --split-by-file [@var{size}]
+@item --split-by-file[=@var{size}]
Similar to @option{--split-by-reloc} but creates a new output section for
each input file when @var{size} is reached. @var{size} defaults to a
size of 1 if not given.
@kindex --split-by-reloc
-@item --split-by-reloc [@var{count}]
+@item --split-by-reloc[=@var{count}]
Tries to creates extra sections in the output file so that no single
output section in the file contains more than @var{count} relocations.
This is useful when generating huge relocatable files for downloading into
@@ -1699,7 +1703,7 @@ many relocations. @var{count} defaults
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
-@kindex --sysroot
+@kindex --sysroot=@var{directory}
@item --sysroot=@var{directory}
Use @var{directory} as the location of the sysroot, overriding the
configure-time default. This option is only supported by linkers
@@ -1720,8 +1724,8 @@ full debugging information by over 30 pe
trouble). The @samp{--traditional-format} switch tells @command{ld} to not
combine duplicate entries.
-@kindex --section-start @var{sectionname}=@var{org}
-@item --section-start @var{sectionname}=@var{org}
+@kindex --section-start=@var{sectionname}=@var{org}
+@item --section-start=@var{sectionname}=@var{org}
Locate a section in the output file at the absolute
address given by @var{org}. You may use this option as many
times as necessary to locate multiple sections in the command
@@ -1732,18 +1736,18 @@ for compatibility with other linkers, yo
should be no white space between @var{sectionname}, the equals
sign (``@key{=}''), and @var{org}.
-@kindex -Tbss @var{org}
-@kindex -Tdata @var{org}
-@kindex -Ttext @var{org}
+@kindex -Tbss=@var{org}
+@kindex -Tdata=@var{org}
+@kindex -Ttext=@var{org}
@cindex segment origins, cmd line
-@item -Tbss @var{org}
-@itemx -Tdata @var{org}
-@itemx -Ttext @var{org}
-Same as --section-start, with @code{.bss}, @code{.data} or
+@item -Tbss=@var{org}
+@itemx -Tdata=@var{org}
+@itemx -Ttext=@var{org}
+Same as @option{--section-start}, with @code{.bss}, @code{.data} or
@code{.text} as the @var{sectionname}.
-@kindex -Ttext-segment @var{org}
-@itemx -Ttext-segment @var{org}
+@kindex -Ttext-segment=@var{org}
+@item -Ttext-segment=@var{org}
@cindex text segment origin, cmd line
When creating an ELF executable or shared object, it will set the address
of the first byte of the text segment.
@@ -1789,7 +1793,7 @@ the linker script being used by the link
@kindex --version-script=@var{version-scriptfile}
@cindex version script, symbol versions
-@itemx --version-script=@var{version-scriptfile}
+@item --version-script=@var{version-scriptfile}
Specify the name of a version script to the linker. This is typically
used when creating shared libraries to specify additional information
about the version hierarchy for the library being created. This option
@@ -1949,8 +1953,8 @@ Second, don't forget to use @option{-Wl,
list of archives, because gcc will add its own list of archives to
your link and you may not want this flag to affect those as well.
-@kindex --wrap
-@item --wrap @var{symbol}
+@kindex --wrap=@var{symbol}
+@item --wrap=@var{symbol}
Use a wrapper function for @var{symbol}. Any undefined reference to
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
undefined reference to @code{__real_@var{symbol}} will be resolved to