fix(linker): say how to fix a missing bridge archive, and document the search

[Guikingone]

Closes #517.

Copying the elephc binary out of its build tree makes every --web/bridge build fail at link time, with nothing to go on:

Linker error: required Elephc bridge `elephc_web` could not be found

The archives are separate files — they have to travel with the compiler. The issue asked for either documentation or an install-layout fallback, and both already half-existed while neither was discoverable: find_archive has always checked the binary's own directory and its sibling lib/, and every bridge has had an ELEPHC_<NAME>_LIB_DIR override, but the only place either was written down was one clause inside the --print-capabilities table row.

The diagnostic

LinkError::MissingBridge now carries the archive, the override variable and the directories actually consulted, so the message names the way out:

Linker error: required Elephc bridge `elephc_web` could not be found
  needs: libelephc_web.a
  looked in:
    /opt/tools/bin
    /opt/tools/lib
    target/debug
    target/release

Set ELEPHC_WEB_LIB_DIR to a directory containing libelephc_web.a, or keep the
bridge archives next to the elephc binary (or in a sibling lib/).
`elephc --print-capabilities` lists every archive this binary can need.

The searched list is not a second copy of the candidate list. find_archive, find_named_archive and the error all read one archive_search_dirs, so a candidate added to discovery cannot go unreported — which also removed the duplicated candidate-building each of those two functions carried.

A LinkOrigin::Bridge item the table does not describe has no archive, override or candidate list, so it renders the bare first line rather than inventing any of the three.

The documentation

A "Where bridge archives are found" section in docs/compiling/linking-and-conditional-compilation.md: the two supported layouts, the five-step resolution order, why it never comes up in a source checkout (the archive is built on demand there), and the message above. The --print-capabilities row now points at it instead of carrying a one-clause summary.

Measured

All three paths, with a debug binary copied out of the tree:

binary alone, nothing beside it	the message above
<dir>/bin/elephc + <dir>/lib/libelephc_*.a	compiles
ELEPHC_WEB_LIB_DIR etc. pointing at a directory of archives	compiles

Two new unit tests: one asserts the message names the archive, the override and every directory archive_search_dirs reports; one pins the bare rendering for a bridge outside the table.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KSAAWPyNBq6dP2b5puN3wr

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previous diagnostic and regression-coverage concerns are fully addressed with no new actionable failures identified.

Summary

The PR makes missing bridge-archive failures actionable and documents the archive resolution model.

• Extends MissingBridge with the required archive, environment override, and directories actually searched.
• Distinguishes override failures from ordinary fallback-search failures.
• Centralizes bridge archive search-directory construction.
• Documents supported archive layouts and resolution precedence.
• Adds unit and end-to-end regression coverage for ordinary, override, and unknown-bridge diagnostics.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Bridge archive required] --> B{Override set and non-empty?}
  B -->|Yes| C[Validate archive in override directory]
  C -->|Valid| D[Use override archive]
  C -->|Invalid or absent| E[Report override directory and explain fallback was skipped]
  B -->|No| F[Build ordered archive_search_dirs list]
  F --> G{Archive found?}
  G -->|Yes| H[Use first matching archive]
  G -->|No| I{Source workspace available?}
  I -->|Yes| J[Build bridge archive on demand]
  I -->|No| K[Report archive, override variable, and searched directories]

Loading

_{Reviews (5) · Last reviewed commit: "test(cli): exercise the override diagnos..."}