What is it?

backgorund:

an archive file (.a) is similar as .lib compared to Winodws. it simply contains object files. Creating an archive file is not "linking", thus no symbol missing/confilct will be checked.

but an. so/.dll is somehow more like a executable/runnable image of system process, which will not allow undefined symbol or reduplicated symbol.

at linking time, linker will look into each archive file(.a) provide by command line for un-resolved symbols. once it finds the first one, it will stop and look for the next. if there're more symbols with the same signaure defined in other ojbect files whithin the same archive, linker just igonre them.

if the archive contains an object file whose symbols are totally never referenced, the object file will not be linked in.

That's why when you write an "plugin style" file which only calls foundation functions but not get called directly (no symbol referenced by others), it will not be linked in, if its object file is in an archive. and static object surely won't init too.

that's why "--whole-archive" is needed, if you wanna force link all object files within the archive file.

Howto?

--whole-archive will affect the subsequence archive files in command line, if you wanna link whole archive for libA, other archives not whole linked in, then use [-Wl,]--whole-archive -lA [-Wl,]--no-whole-arhive -lB lC ...  Use -Wl, if you're passing it via compiler, not directly to LD.

but if an archive contains reduplicated symbol and you're using "--whole-archive", you will get a symbol conflict error because all symbols will be linked in.