5.1. Diagnostic Reports

Linker diagnostics refer to the messages and reports generated by a linker to help developers identify and resolve issues during the linking phase of compilation. These diagnostics can include:

• Warnings and errors about malformed or unsupported linker scripts

• Misplaced or overlapping sections

• Unresolved symbols

• Alignment issues

• Plugin-related inconsistencies

5.1.1. What -Wall and -Werror Mean for ELD

5.1.1.1. -Wall: Enable All Warnings

In the eld linker, -Wall enables a broad set of diagnostic warnings during the linking process. These warnings help developers catch:

• Misuse of linker script commands

• Compatibility issues during linking

• Linker script forward references

• Suspicious section overlaps or misalignments

• Deprecated or unsupported syntax

• Potentially undefined behavior in symbol resolution

• Command line usage

This flag is particularly useful in embedded development, where layout precision and deterministic behavior are critical.

5.1.1.2. -Werror: Treat Warnings as Errors

When -Werror is used, any warning promoted by -Wall (or other -W flags) is treated as a fatal error, halting the linking process. This ensures:

• No warnings are ignored during CI/CD builds

• Developers are forced to resolve all issues before producing a final binary

• Consistency across builds, especially when linker behavior may vary across toolchain versions

This is especially important in embedded workflows, where eld is used to build critical components like firmware and device drivers.

5.1.1.3. Why It Matters in ELD

• Embedded Safety: In embedded systems, even minor layout issues can lead to runtime faults. -Wall -Werror ensures these are caught early.

• Plugin Infrastructure: ELD supports linker plugins. These can emit custom diagnostics, and -Wall ensures they’re surfaced; -Werror enforces them.

• Script Compatibility: ELD aims for GNU linker script compatibility. These flags help validate script correctness during migration from GNU ld.

5.1.1.4. Example Usage

eld -T script.ld -o firmware.elf main.o -Wall -Werror

This command will:

• Use script.ld for layout

• Link main.o into firmware.elf

• Emit all warnings (-Wall)

• Fail the build if any warning is encountered (-Werror)

5.1.2. ELD Linker Warning Flags

This document provides a categorized list of warning flags supported by the ELD linker.

5.1.2.1. General Warning Flags

Flag	Description
-Wall	Enables all standard warnings supported by ELD. Useful for catching script and layout issues early.
-Warchive-file	Warns about issues related to archive (.a) when they contain duplicate members.
-Wattribute-mix	Flags inconsistent or conflicting section attributes across input files.
-Wbad-dot-assignments	Warns when the . (location counter) is used in a way that may cause layout issues or undefined behavior.
-Wcommand-line	Enables warnings for malformed or conflicting command-line options.
-Werror	Treats all warnings as errors, halting the link process.
-Wlinker-script	Enables warnings specific to linker script issues, such as malformed directives, deprecated syntax, or unsupported constructs.
-Wlinker-script-memory	Focuses on memory region definitions in linker scripts, such as overlaps or undefined regions.
-Wwhole-archive	Warns when --whole-archive is used inappropriately or causes symbol bloat.
-Wzero-sized-sections	Flags sections that are defined but have zero size, which may indicate a script or input error.
-Wosabi	Generates a warning when an input file’s OS/ABI value differs from those encountered in previously processed files.

5.1.2.2. Suppression Flags

Flag	Description
-Wno-archive-file	Suppresses archive file-related warnings.
-Wno-attribute-mix	Suppresses attribute mismatch warnings.
-Wno-error	Allows warnings to be emitted without halting the link process.
-Wno-linker-script	Disables linker script-related warnings.
-Wno-osabi	Disables OS/ABI warnings.

5.1.3. Archive Member Reports

In addition to map-file text output, --archive-member-report emits a JSON report with one record per archive-member inclusion event. This report is generated even when -Map is not requested.

Example linker invocation:

clang hw.o -Wl,--archive-member-report,report.json --ld-path=ld.eld

Schema (per ArchiveMembers entry):

• MemberPath: Decorated member path such as libc.a(malloc.o).

• Archive / Member: Archive and member split fields for archive members.

• ReferrerObjectFile: Requester when an object file caused the pull-in.

• ReferrerArchive / ReferrerMember: Requester when another archive member caused the pull-in.

• Symbol: Symbol that triggered inclusion for non-whole-archive pulls.

• WholeArchive and Reason: Present when -whole-archive caused inclusion (for example Reason: -whole-archive).

• MemberReferencedSymbols: Symbols referenced by the included member; this enables tracing symbol chains such as sys_init_tls -> malloc.

• MemberSymbols: Symbols defined by the included member.

• MemberIsArchiveMember / ReferrerIsArchiveMember: Explicit booleans describing whether each side of the edge is an archive member.

• MemberIsBitcode / ReferrerIsBitcode: Bitcode markers for mixed native/bitcode links.

Behavior notes:

• The report is emitted even when map files are not requested.

• Both regular archives and thin archives are supported.

• For -whole-archive inclusion, WholeArchive is true and Reason is emitted as -whole-archive.

Example JSON snippet:

{
  "ArchiveMembers": [
    {
      "MemberPath": "libc.a(malloc.o)",
      "Archive": "libc.a",
      "Member": "malloc.o",
      "ReferrerArchive": "libstandalone.a",
      "ReferrerMember": "sys_init_tls.o",
      "Symbol": "malloc",
      "MemberReferencedSymbols": ["sbrk", "errno"]
    }
  ]
}

5.1.3.1. Tracing behavior with examples

Use utils/archive_member_report/archive_member_trace.py to understand why members were included and to follow chains through archive members.

Examples:

# Why was malloc needed?
python3 utils/archive_member_report/archive_member_trace.py report.json --symbol malloc --why-needed

# Trace all members matching a glob.
python3 utils/archive_member_report/archive_member_trace.py report.json --pattern "*libc.a(*malloc*.o)"

# Show referenced symbols for matching archives.
python3 utils/archive_member_report/archive_member_trace.py report.json --referenced-symbols-archive "*libc.a"

# Show defined symbols for matching members.
python3 utils/archive_member_report/archive_member_trace.py report.json --defined-symbols-member "*tls*.o"

# Thin archive works the same way.
clang main.o -Wl,--archive-member-report,report.json thinlib.a
python3 utils/archive_member_report/archive_member_trace.py report.json --symbol foo

The --symbol and --pattern options are mutually exclusive. For --why-needed, the output highlights the requesting file/member and prints a readable chain so each pull-in reason is visible as a separate trace.