[binutils-gdb] ld: More documentation for --defsym

[Andrew Burgess]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=54874444da47cab42de1d0b22e7009e7ca3eb6f2

commit 54874444da47cab42de1d0b22e7009e7ca3eb6f2
Author: Andrew Burgess <andrew.burgess@embecosm.com>
Date:   Tue Oct 6 15:30:15 2020 +0100

    ld: More documentation for --defsym
    
    The ordering of command line options --defsym and -T is important,
    however, the description of --defsym in the manual doesn't mention
    this.
    
    This commit adds more text to the description of --defsym to try and
    explain this ordering requirement.
    
    ld/ChangeLog:
    
            * ld.texi (Options): Extend the description of --defsym.

Diff:
---
 ld/ChangeLog | 4 ++++
 ld/ld.texi   | 9 +++++++++
 2 files changed, 13 insertions(+)

diff --git a/ld/ChangeLog b/ld/ChangeLog
index 18dc37bdd86..74e5b4fe4f2 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,7 @@
+2020-10-16  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+	* ld.texi (Options): Extend the description of --defsym.
+
 2020-10-16  Nick Clifton  <nickc@redhat.com>
 
 	PR 26626
diff --git a/ld/ld.texi b/ld/ld.texi
index 95f31ea530b..763f07e1ae3 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1705,6 +1705,15 @@ using the linker command language from a script (@pxref{Assignments}).
 @emph{Note:} there should be no white space between @var{symbol}, the
 equals sign (``@key{=}''), and @var{expression}.
 
+The linker processes @samp{--defsym} arguments and @samp{-T} arguments
+in order, placing @samp{--defsym} before @samp{-T} will define the
+symbol before the linker script from @samp{-T} is processed, while
+placing @samp{--defsym} after @samp{-T} will define the symbol after
+the linker script has been processed.  This difference has
+consequences for expressions within the linker script that use the
+@samp{--defsym} symbols, which order is correct will depend on what
+you are trying to achieve.
+
 @cindex demangling, from command line
 @kindex --demangle[=@var{style}]
 @kindex --no-demangle