Static-library link order: trace who introduces an unresolved symbol

What it is

GCC's link-options documentation states that the linker processes libraries and object files in their specified order. Its example shows a library being searched before a later object introduces a reference, leaving that reference unresolved. An existing archive on disk therefore does not establish that the relevant member was selected at the right point. GCC link options

Why it matters

When an agent sees an undefined symbol, adding another library path is only one possible response. The symbol may be absent, differently named, or requested after its archive was considered. Keeping these explanations separate avoids growing an opaque link command through repeated guesses.

How to apply

• Capture the complete failing link command, including response-file contents where the build makes them available. Distinguish object inputs, archives, shared libraries and search paths.
• Choose one unresolved symbol and identify the object that references it. Inspect the candidate archive to confirm a matching definition exists; retain the exact symbol spelling in the diagnostic note.
• For a simple acyclic case, arrange dependent inputs before the archive supplying their unresolved references. Express that relationship in the build system rather than patching a generated command.
• Reduce a complicated failure to a small caller and its required library. Compare the successful reduced command with the real command to locate additional dependencies.
• Propose validation from a clean build tree and on each supported linker family. Keep the minimal fixture only if it protects an actual supported packaging scenario.

Pitfalls

Ordering rules vary with linker behavior and options; do not turn this diagnosis into a universal rule for every shared-library platform. Cyclic archive dependencies may need a documented linker-specific grouping strategy or architectural correction. A broader whole-archive option can conceal the original dependency problem and changes what is included. This procedure claims no particular link-time or binary-size improvement.