ld: Extend documentation for EXCLUDE_FILE

There was a gap in the documentation of EXCLUDE_FILE that could cause
confusion to a user.  When writing an input section specifier like this:

    *(EXCLUDE_FILE (somefile.o) .text .text.*)

this could mean one of the following:

   1. All '.text' and '.text.*' from all files except for 'somefile.o',
   or
   2. All '.text' from all files except 'somefile.o', and all '.text.*'
   sections from all files.

It turns out that the second interpretation is correct, but the manual
does not make this clear (to me at least).  Hopefully this patch makes
things clearer.

ld/ChangeLog:

	* ld/ld.texinfo (Input Section Basics): Expand the description of
	EXCLUDE_FILE.

diff --git a/ld/ChangeLog b/ld/ChangeLog
index 4bae998e6a6459025d9cb8fe8ac458d273a28103..7c24d657f82069a393affca074761e2c641d05bf 100644 (file)
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,8 @@
+2016-09-20  Andrew Burgess  <andrew.burgess@embecosm.com>
+
+       * ld/ld.texinfo (Input Section Basics): Expand the description of
+       EXCLUDE_FILE.
+

 2016-09-14  Thomas Preud'homme  <thomas.preudhomme@arm.com>
 
        * testsuite/ld-arm/cmse-veneers.s: Add a test for ARMv8-M Security
 2016-09-14  Thomas Preud'homme  <thomas.preudhomme@arm.com>
 
        * testsuite/ld-arm/cmse-veneers.s: Add a test for ARMv8-M Security

diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 5944b129b8fcb5b9d847c81d84c4a2f2ab7a32f9..1303a0e5361d65bef57da6fa5ce73cd1575bf410 100644 (file)
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -4214,6 +4214,21 @@ they are found in the linker input.  In the second example, all
 @samp{.text} input sections will appear first, followed by all
 @samp{.rdata} input sections.
 
 @samp{.text} input sections will appear first, followed by all
 @samp{.rdata} input sections.
 

+When using EXCLUDE_FILE with more than one section, the exclusion only
+applies to the section immediately following, for example:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text .rdata)
+@end smallexample
+@noindent
+will cause all @samp{.text} sections from all files except
+@file{somefile.o} to be included, while all @samp{.rdata} sections
+from all files, including @file{somefile.o}, will be included.  To
+exclude the @samp{.rdata} sections from @file{somefile.o} the example
+should be modified to:
+@smallexample
+*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
+@end smallexample
+

 You can specify a file name to include sections from a particular file.
 You would do this if one or more of your files contain special data that
 needs to be at a particular location in memory.  For example:
 You can specify a file name to include sections from a particular file.
 You would do this if one or more of your files contain special data that
 needs to be at a particular location in memory.  For example: