Link Order, Link Groups & Whole Archive

When multiple static libraries depend on each other, order matters to the linker. Xmake gives you three knobs to fix order-related link errors without hand-crafting -Wl,... flags:

• add_linkorders — declare that library A must come before library B on the command line.
• add_linkgroups — wrap a set of libraries in --start-group/--end-group (Linux) or the equivalent so the linker resolves circular references.
• whole_archive = true option on add_linkgroups — force-include every object, even ones that look unreferenced (plugin registration, static initializers).

1. The underlying problem

A static library is a collection of object files. The GNU linker (and most others) resolves symbols in a single left-to-right pass: when it sees -lfoo, it picks up objects that satisfy currently-undefined symbols. Anything not needed yet is discarded.

That causes two common bugs:

1. Wrong order. -lbar -lfoo where bar depends on foo → undefined symbols from bar, because foo was consumed before bar needed it.
2. Circular dependency. foo calls into bar and bar calls into foo → impossible with one-pass linking.
3. Missing static registration. Plugin/factory patterns where a global constructor registers itself, but no other code directly references it → linker strips the object.

2. add_linkorders — fix order