xmake-link-order

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

target("app")
    set_kind("binary")
    add_files("src/main.cpp")
    add_deps("foo", "bar", "baz")
    add_linkorders("bar", "foo")       -- bar depends on foo → bar first, then foo
    add_linkorders("baz", "foo", "bar")

add_linkorders(A, B) means A must appear before B on the linker command line (-lA ... -lB). List the dependents before their dependencies. Multiple calls accumulate.

Xmake performs a topo-sort over the declared orders and emits the final link line. If you declare a cycle, xmake raises at configure time.

Order applies to add_links too