[binutils-gdb] PR28902, -T script with INSERT ordering

[binutils-gdb] PR28902, -T script with INSERT ordering

[Alan Modra]

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

commit 31f149015865401c760e9d76157734996fbab770
Author: Alan Modra <amodra@gmail.com>
Date:   Sat May 13 14:50:23 2023 +0930

    PR28902, -T script with INSERT ordering
    
    The answer to PR28902 may be deduced from the existing INSERT
    documentation that says the default script is parsed after the -T
    INSERT script, if you assume (correctly) that nothing special is done
    when inserting into -T scripts overriding the default script.  In both
    cases INSERT handling looks for the specified output section later on
    the internal list of parsed script commands.  This isn't obvious
    though, so make the ordering explicit, and mention that section
    assignments are the same too.
    
            PR 28902
            * ld.texi (INSERT): Specify ordering when -T is used both to
            override the default script and to augment.

Diff:
---
 ld/ld.texi | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/ld/ld.texi b/ld/ld.texi
index 012eec2e809..8038de39106 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -1085,7 +1085,8 @@ a linker bug report.
 @item -T @var{scriptfile}
 @itemx --script=@var{scriptfile}
 Use @var{scriptfile} as the linker script.  This script replaces
-@command{ld}'s default linker script (rather than adding to it), so
+@command{ld}'s default linker script (rather than adding to it),
+unless the script contains @code{INSERT}, so
 @var{commandfile} must specify everything necessary to describe the
 output file.  @xref{Scripts}.  If @var{scriptfile} does not exist in
 the current directory, @code{ld} looks for it in the directories
@@ -4442,6 +4443,12 @@ SECTIONS
 INSERT AFTER .text;
 @end smallexample
 
+Note that when @samp{-T} is used twice, once to override the default
+script and once to augment that script using @code{INSERT} the order
+of parsing and section assignments apply as for the default script.
+The script with @code{INSERT} should be specified @emph{first} on the
+command line.
+
 @item NOCROSSREFS(@var{section} @var{section} @dots{})
 @kindex NOCROSSREFS(@var{sections})
 @cindex cross references