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

What ``-Wall`` and ``-Werror`` Mean for ELD
==============================================================

``-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.

``-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.

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.

Example Usage
-------------

.. code-block:: bash

   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``)

ELD Linker Warning Flags
========================

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

General Warning Flags
----------------------

.. list-table::
   :header-rows: 1

   * - 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.

Suppression Flags
------------------

.. list-table::
   :header-rows: 1

   * - 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.

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"]
       }
     ]
   }

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.