This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]