Analysis and introspection options in linkers

--trace-symbol=<sym>

Alias: -y sym

Print files which define or reference the specified non-local symbol. There are three types of definitions: definition in a relocatable object file, definition in a shared object, definition in a lazy object file/archive.

1
2
3
4
5
% ld.lld -y foo a1.a a.o a2.so
a1.a(a1.o): lazy definition of foo
a.o: reference to foo
a1.a(a1.o): definition of foo
a2.so: shared definition of foo

--trace

Alias: -t

Print processed files: relocatable object files, shared objects, and extracted lazy object files/archive members. Note that unextracted lazy object files/archive members are not printed.

The GNU ld behavior is a bit strange. You need to specify -t twice to get both the archive name and the member name.

1
2
3
4
5
6
7
8
9
10
11
12
% ld.lld -t a.o b.so c.a
a.o
b.so
c.a(1.o)
% ld.bfd -t a.o b.so c.a
a.o
b.so
c.a
% ld.bfd -t -t a.o b.so c.a
a.o
b.so
(c.a)1.o

gold introduced --print-symbol-counts=<file> in 2008-06. The output includes the member count and extracted member count for each archive. I added --print-archive-stats=<file> to ld.lld to dump the archive information, but in a tab-separated format.

1
2
3
4
5
% ld.lld a.o aweak.a a1.a a1.a --print-archive-stats=-
members extracted       archive
1       0       aweak.a
3       2       a1.a
3       0       a1.a

--why-extract=<file>

Print why each archive member/lazy object file is extracted. I added the option to ld.lld 14. The output is in a tab-separated format.

1
2
3
4
5
% ld.lld main.o a_b.a b_c.a c.a -o /dev/null --why-extract=- | tee stdout
reference       extracted       symbol
main.o  a_b.a(a_b.o)    a
a_b.a(a_b.o)    b_c.a(b_c.o)    b()
b_c.a(b_c.o)    c.a(c.o)        c()

It is easy to track a chain of references to one archive member: 

1
2
3
4
% ruby -ane 'BEGIN{p={}}; p[$F[1]]=[$F[0],$F[2]] if $.>1; END{x="c.a(c.o)"; while y=p[x]; puts "#{y[0]} extracts #{x} to resolve #{y[1]}"; x=y[0] end}' stdout
b_c.a(b_c.o) extracts c.a(c.o) to resolve c()
a_b.a(a_b.o) extracts b_c.a(b_c.o) to resolve b()
main.o extracts a_b.a(a_b.o) to resolve a

ld64 has a similar option named -why_load.

-Map=<file>

Print a link map to the file. To print to stdout, use -M.

The output includes output sections addresses, file offsets, input section to output section mapping, and symbol assignments.

GNU ld prints additional information: Archive member included to satisfy reference by file (symbol), Discarded input sections (similar to --print-gc-sections), Allocating common symbols, Memory Configuration (related to memory regions), and Linker script and memory map (similar to -t).

If the option value is a directory or a name with %, the map filename will be constructed from the output filename. 

1
2
3
4
5
6
7
8
9
10
-o foo.exe -Map=bar                  [Creates ./bar]
-o ../dir/foo.exe -Map=bar           [Creates ./bar]
-o foo.exe -Map=../dir               [Creates ../dir/foo.exe.map]
-o ../dir2/foo.exe -Map=../dir       [Creates ../dir/foo.exe.map]
-o foo.exe -Map=%                    [Creates ./foo.exe.map]
-o ../dir/foo.exe -Map=%             [Creates ../dir/foo.exe.map]
-o foo.exe -Map=%.bar                [Creates ./foo.exe.bar]
-o ../dir/foo.exe -Map=%.bar         [Creates ../dir/foo.exe.bar]
-o ../dir2/foo.exe -Map=../dir/%     [Creates ../dir/../dir2/foo.exe.map]
-o ../dir2/foo.exe -Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar]

Some folks want a JSON output format with some stability guarantee.

Cross references

--cref

Print a cross reference table. For each non-local defined or shared symbol, print the defined file on the first line and and referencing files in subsequent lines. The format is a bit wasteful because there are 50 bytes before the File column.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
% ld.lld --cref a1.so a2.o a3.o a.a

Cross Reference Table

Symbol                                            File
foo                                               a1.so
                                                  a2.o
                                                  a3.o
bar                                               a2.o
                                                  a3.o
_start                                            a3.o
baz                                               a3.o
zed                                               a.a(aa.o)
                                                  a3.o

If -Map is specified, print along with the link map to the file. I find this behavior a bit unfortunate, because:

  • the information is independent from other pieces of -Map
  • both pieces of information has large amount of output. Merging them makes the link action slower if the user just needs one piece of information

mold recently added the option in an alternative format to --cref.

1
2
3
4
5
6
7
8
9
10
11
12
# This is an output of the mold linker's --print-dependencies=full option.
#
# Each line consists of 4 fields, <input-section>, <output-section>,
# <symbol-type> and <symbol>, separated by tab characters. It indicates that
# <input-section> depends on <output-section> to use <symbol>. <symbol-type>
# is either "u" or "w" for regular or weak undefined, respectively.
#
# If you want to obtain dependency information per function granularity,
# compile source files with the -ffunction-sections compiler flag.
a3.o:(.text)    a1.so   u       foo
a3.o:(.text)    a2.o:(.text)    u       bar
a3.o:(.text)    a.a(aa.o):(.text)       u       zed

-why_live sym

ld64 manpage says: Logs a chain of references to symbol_name. Only applicable with -dead_strip . It can help debug why something that you think should be dead strip removed is not removed.

This can usually be approximated by ld.lld --why-extract=-.

1
2
3
4
5
6
7
8
9
10
% ld.lld main.o a_b.a b_c.a c.a -o /dev/null --why-extract=- | tee stdout
reference       extracted       symbol
main.o  a_b.a(a_b.o)    a
a_b.a(a_b.o)    b_c.a(b_c.o)    b()
b_c.a(b_c.o)    c.a(c.o)        c()

% ruby -ane 'BEGIN{p={}}; p[$F[1]]=[$F[0],$F[2]] if $.>1; END{x="c.a(c.o)"; while y=p[x]; puts "#{y[0]} extracts #{x} to resolve #{y[1]}"; x=y[0] end}' stdout
b_c.a(b_c.o) extracts c.a(c.o) to resolve c()
a_b.a(a_b.o) extracts b_c.a(b_c.o) to resolve b()
main.o extracts a_b.a(a_b.o) to resolve a

Statistics

--stats

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
% ld.bfd @response.txt --stats
ld.bfd: total time in link: 9.879890
% mold @response.txt --stats
   total_input_bytes=1161772844
         reloc_alloc=3983368
            all_syms=1185762
        defined_syms=747420
      input_sections=692453
      undefined_syms=397776
    regular_sections=319069
      merged_strings=214750
            num_fdes=169858
  removed_comdat_mem=140402
             comdats=131977
            dso_syms=10875
         parsed_objs=3099
            num_objs=2677
            num_cies=2665
       output_chunks=36
            num_dsos=10
     num_unique_cies=2
    string_fragments=0
      reloc_nonalloc=0
.rodata.cst estimation=5425 actual=4689
.rodata.str estimation=240124 actual=210057
.comment estimation=1628 actual=4

--time-trace

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
% ld.lld @response.txt --time-trace -o clang
% jq -r '.traceEvents[] | select(.name|contains("Total")) | "\(.dur/1000000) \(.name)"' < clang.time-trace
1.099133 Total ExecuteLinker
1.064616 Total Link
0.303137 Total Write output file
0.295151 Total Write sections
0.220898 Total Scan relocations
0.183298 Total Parse input files
0.06039 Total Merge/finalize input sections
0.0377 Total Add local symbols
...
% jq -r '.traceEvents[] | select(.name|contains("Write")) | "\(.dur/1000000) \(.name) \(.args)"' < clang.time-trace
0.130966 Write sections {"detail":".rela.dyn"}
0.001995 Write sections {"detail":".rela.plt"}
0.007248 Write sections {"detail":".dynsym"}
0.000967 Write sections {"detail":".gnu.hash"}
0.01489 Write sections {"detail":".hash"}
0.003147 Write sections {"detail":".dynstr"}
0.034617 Write sections {"detail":".rodata"}
0.030412 Write sections {"detail":".eh_frame"}
0.02487 Write sections {"detail":".text"}
...

mold --perf

1
2
3
4
5
6
7
8
9
10
11
12
13
% mold @response.txt --perf
     User   System     Real  Name
    4.161    0.533    0.254  all
    2.077    0.302    0.139    read_input_files
    2.100    0.235    0.114    total
    1.537    0.129    0.071      before_copy
    0.000    0.000    0.000        apply_exclude_libs
    0.142    0.051    0.007        do_resolve_symbols
    0.142    0.051    0.007          do_resolve_symbols
    0.245    0.012    0.013        register_section_pieces
    0.002    0.000    0.001        eliminate_comdats
    0.002    0.000    0.000        convert_common_symbols
...