=================
Diagnostics
=================

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

What are the various categories that are grouped in

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.