[ELF] Clarify help wording for --symbol-ordering-file

[smeenai]

Summary

The input file for this option should contain a list of symbols, not a
list of sections, so it seems clearer to talk about laying out symbols
instead of sections. Referring to the file itself as the "symbol
ordering file" is consistent with --warn-symbol-ordering and less
ambiguous than "symbol file" (albeit slightly redundant).

[pcc]

One could also read "Lay out symbols" as meaning the order of symbols in the symbol table, so I'm not sure if this is better. No strong opinions though.

[ruiu]

It is arguable which is more accurate, "layout sections" or "layout symbols", because you can't layout symbols alone. But I agree that your new message is more intuitive and easier to understand.

LGTM but please wait for a while in case other people have different opinion.

[smeenai]

In D46099#1078997, @pcc wrote:

One could also read "Lay out symbols" as meaning the order of symbols in the symbol table, so I'm not sure if this is better. No strong opinions though.

That's fair. I'm not sure how to make that unambiguous without being super wordy.

In D46099#1078999, @ruiu wrote:

It is arguable which is more accurate, "layout sections" or "layout symbols", because you can't layout symbols alone. But I agree that your new message is more intuitive and easier to understand.

LGTM but please wait for a while in case other people have different opinion.

Yeah, that's also true. Slightly unrelated to this change, but --warn-symbol-ordering is silent right now in case you forget -ffunction-sections (but of course the ordering doesn't work). Would it be reasonable to extend the warnings to cover that case? I'm thinking, for each symbol specified in the symbol ordering file, warn if that symbol's section also contains other symbols, though I don't know if that would lead to false positives and/or be reasonable cost-wise.

Also, if we're willing to go with a longer help text, I think it might be helpful to note that you must compile with -ffunction-sections -fdata-sections in order for symbol ordering to be able to work in the help text itself.

[ruiu]

Yeah, that's also true. Slightly unrelated to this change, but --warn-symbol-ordering is silent right now in case you forget -ffunction-sections (but of course the ordering doesn't work). Would it be reasonable to extend the warnings to cover that case? I'm thinking, for each symbol specified in the symbol ordering file, warn if that symbol's section also contains other symbols, though I don't know if that would lead to false positives and/or be reasonable cost-wise.

Maybe we can warn if two or more symbols specified by a symbol ordering file belong to one section? I'm not sure if that would cause false positives, but it might be worth to try.

[grimar]

The new message is IMO slightly better, so I am OK with that patch.

But I am actually thinking about something like:
"Layout sections to place symbols in the order specified by symbol ordering file"

[jhenderson]

In D46099#1079007, @ruiu wrote:

Yeah, that's also true. Slightly unrelated to this change, but --warn-symbol-ordering is silent right now in case you forget -ffunction-sections (but of course the ordering doesn't work). Would it be reasonable to extend the warnings to cover that case? I'm thinking, for each symbol specified in the symbol ordering file, warn if that symbol's section also contains other symbols, though I don't know if that would lead to false positives and/or be reasonable cost-wise.

Maybe we can warn if two or more symbols specified by a symbol ordering file belong to one section? I'm not sure if that would cause false positives, but it might be worth to try.

I agree that an additional warning here might be nice. We would probably only want to warn once (or possibly some other low limit) per section, not per symbol, as otherwise if you forget -ffunction-sections, you will get far too many warnings.

[• espindola]

In D46099#1079153, @jhenderson wrote:

In D46099#1079007, @ruiu wrote:

Yeah, that's also true. Slightly unrelated to this change, but --warn-symbol-ordering is silent right now in case you forget -ffunction-sections (but of course the ordering doesn't work). Would it be reasonable to extend the warnings to cover that case? I'm thinking, for each symbol specified in the symbol ordering file, warn if that symbol's section also contains other symbols, though I don't know if that would lead to false positives and/or be reasonable cost-wise.

Maybe we can warn if two or more symbols specified by a symbol ordering file belong to one section? I'm not sure if that would cause false positives, but it might be worth to try.

I agree that an additional warning here might be nice. We would probably only want to warn once (or possibly some other low limit) per section, not per symbol, as otherwise if you forget -ffunction-sections, you will get far too many warnings.

I agree. For whatever reason many system libraries (.a) are built without -ffunction-sections. A single warning per file (or even library) is probably OK.

[• espindola]

In D46099#1079143, @grimar wrote:

The new message is IMO slightly better, so I am OK with that patch.

But I am actually thinking about something like:
"Layout sections to place symbols in the order specified by symbol ordering file"

I agree. "Layout symbols" sounds a bit odd, but maybe just because I have been working on a linker.

[smeenai]

In D46099#1079143, @grimar wrote:

The new message is IMO slightly better, so I am OK with that patch.

But I am actually thinking about something like:
"Layout sections to place symbols in the order specified by symbol ordering file"

I really like this. I'll switch to it; thanks.

I'll look into the other warning as a follow-up.

[smeenai]

Update with @grimar's suggestion

lld/trunk/ELF/Options.td

 def start_lib: F<"start-lib">,
   HelpText<"Start a grouping of objects that should be treated as if they were together in an archive">;
 
 def strip_all: F<"strip-all">, HelpText<"Strip all symbols">;
 
 def strip_debug: F<"strip-debug">, HelpText<"Strip debugging information">;
 
 defm symbol_ordering_file: Eq<"symbol-ordering-file">,
-  HelpText<"Layout sections in the order specified by symbol file">;
+  HelpText<"Layout sections to place symbols in the order specified by symbol ordering file">;
 
 defm sysroot: Eq<"sysroot">, HelpText<"Set the system root">;
 
 def target1_rel: F<"target1-rel">, HelpText<"Interpret R_ARM_TARGET1 as R_ARM_REL32">;
 
 def target1_abs: F<"target1-abs">, HelpText<"Interpret R_ARM_TARGET1 as R_ARM_ABS32">;
 
 defm target2: Eq<"target2">,