Xcode 3.0 had a new linker ld(1) that supports all four architectures (ppc, ppc64, i386, and x86_64). In general it is a drop in replacement for the previous linker. See the man page for detailed command line option information.
Xcode 3.1 introduces a new file system layout for tools. There may be multiple copies of the linker. When gcc invokes the linker, it runs the linker that is file system relative to the compiler (e.g. /Developer/usr/bin/gcc-4.2 invokes /Developer/usr/bin/ld).
New Features (Xcode 3.1)
Bugs Fixed in Xcode 3.1
New Features (Xcode 3.0)
Known Issues
Support for LLVM bitcode object files
The Xcode 3.1 linker can process LLVM bitcode files along with mach-o object files. When bitcode files are used, libLTO.dylib is loaded and used to perform “Link Time Optimizations”. See gcc-llvm release notes for more information.
Support for lazily loaded dylibs
The Xcode 3.1 linker has new options -lazy_library and -lazy_framework which allow you to link against a dylib but have the dylib loaded lazily at runtime. This option can only be used if the only references to the dylib are all function calls, because special call site stubs are inserted by the linker to trap the first access to the dylib and load it.
Note: unlike weak linking, you do not take the address of a function to see if the dylib was loaded. All you can do is call a function. If for some reason the dylib, cannot be loaded, the called function returns zero. Therefore the first call into a lazily loaded function should be a function that can return zero, and that means there was an error.
Support for ARM (iPhone OS) architecture
No warning about tentative definitions overriding a dylib definition
If a global variable in a framework header is missing the extern keyword on its declaration, the C compiler will consider it a tentative definition. At link time, the linker will turn that into a real zero-fill definition, even though that symbol is exported from a linked dylib.
NS/CFStrings are not dead code eliminated
All NS/CFString literals from a .o file are lumped together and -dead_strip either keeps them all or ignores them all.
operator new fails if no weak symbols
If a program overrides operator new (or delete) but has no weak symbols, libstdc++.dylib will not use the program’s operator new. The work around is to add some weak symbol (e.g. int __attribute__((weak)) my_weak=0; )
No support for text relocs
Assembly code that uses instructions that require dyld to update the instructions at runtime are currently unsupported. The previous linker allow them with the option -read_only_relocs suppress
Need better warning about mixed visibilities
For proper C++ semantics, there should only be one copy of any function in use at runtime. There are many case where the only definition of a function is an inline definition in a header file which may be included by many source files. In some cases (classes that have a "key method") the compiler can figure out a way to emit only one copy of a function. In other cases is cannot figure out a way, so it falls back to emitting a copy of the function in every translation unit that uses the header, but marks the copy as "weak", which tells the linker it is OK if there are multiple copies and to just pick one of them.
The linker issues a warning if it sees more than one copy, but they have different visibility. Visibility means whether the symbol is available at runtime (for dyld lookups). So, depending on which one the linker picks, the availability of the symbol at runtime will change. This makes the build unpredictable.
The most common way this happens is if -fvisibility-inlines-hidden is used when compiling some sources, but not others.
See also: http://developer.apple.com/documentation/DeveloperTools/Conceptual/CppRuntimeEnv/Articles/SymbolVisibility.html
Spurious warning with non-inlined template functions
If you have templated C++ code and some where some functions are not inlined in a header, you may get spurious warnings about mixed visibility. There is no work around.
ppc64 branch islands broken
When linking a ppc64 main executable with >16MB of code and a 4GB page zero, branch islands are not generated and you get a branch out of range error. This work around is to use the linker option “-pagezero_size 0x1000” to reduce the default 4GB page zero down to a 4KB page zero size.
Re-export cycle detection causes many X11 programs to fail to link
There are two libGL.dylib files. One in /usr/X11/lib and one in /System/Library/Frameworks/OpenGL.framework/Libraries and the former re-exports the latter. The Mac OS X 10.5 linker uses -L paths to search for indirect libraries. The combination of these two causes a re-export cycle which will make the linker error out. The work around is to add: -dylib_file /System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib:/System/Library/Frameworks/OpenGL.framework/Versions/A/Libraries/libGL.dylib to the link line. The -dylib_file option takes a colon separate pair of paths and instructs the linker where to look for a particular indirect dylib.
Implicit weak libraries does not happen
In the previous linker, if all symbols used from a particular dylib were weak_import, then the entire dylib was automatically marked to be loaded weakly. That is, since the code was compiled with it to be OK if all symbols used from a dylib are not found at runtime, then the load command should be changed to LD_LOAD_WEAK_DYLIB which allows the entire dylib to be missing at runtime. The work around (if you need the library to be weak) is to explicitly link it weak using the -weak-l, -weak_library, or -weak_framework options.
Exports wildcards and dead code stripping don’t work together
Using wildcards (e.g. _XYZ*) in -exported_symbols_list does not work with -dead_strip
Prefer architecture-specific variant
In the Xcode 3.0 linker if a universal object file contained multiple slices for an architecture each with a different subtype, the linker always used the first slice with a matching architecture. Now, the linker checks if the command line argument was used with a subtype (e.g. -arch ppc970 instead of -arch ppc), and if so it will first check each universal object file for a matching subtype, before falling back to use the first matching architecture.
-stack_size failure when large __bss is used
Fixed a case for x86_64 where the use of large static variables and a custom stack size could not be used together.
-bundle_loader does not work if loader is a bundle
Restore pre-Xcode 3.0 behavior so that -bundle_loader can be used by bundles
Fixed “unknown scattered relocation type 4” bug when linking ppc architecture
Position Independent Executables
The -pie option can be used to build main executables that load at a random address. To work, all .o files must have been compiled without -mdynamic-no-pic, preferable with -fpie. Note gcc-4.0 does not recognize the -pie option. You need to use -Wl,-pie when invoking the linker through gcc.
RPATH
The -rpath option allows you to embed a path in an executable with dyld will use on 10.5 and later to locate @rpath based dependent dylibs
Exported symbol wild cards
The symbols in the file passed to -exported_symbols_list can now contain simple wildcards (* and ?)
Dead code dependencies
The -why_live option can be used with -dead_strip to list why a particular function was not dead stripped. It will print out the dependency chain of what is referencing the specified symbol
-F and -L are now used to find indirect dylibs
If you link your program against libfoo.dylib and libfoo.dylib itself was linked against libbar.dylib, then when linking your program libfoo.dylib is a direct dylib and libbar.dylib is an indirect dylib. In previous linker releases, the linker found indirect dylibs using the load path in the direct dylib. This was problematic when doing a complex builds because a newly build indirect libraries would not be installed yet, so the linker would not find it or would find an old version. The old workaround was to use the -dylib_file option to specify a replacement indirect dylib. The Mac OS X 10.5 linker now uses the search paths specified by the -F and -L options to find both direct and indirect dylibs.
Map file
The -map option will generate a text file which details all functions and data and where they were laid out in the output file
Better two-level namespace
For your convenience a Cocoa application can link with just -framework Cocoa and not have to also list AppKit, Foundation, and libobjc, even though symbols from those dylibs are needed. This works because Cocoa “re-exports” AppKit, and AppKit re-exports Foundation which in turn re-exports libobjc. This makes building easier, but it causes all symbols to be encoded in the two-level namespace as coming from Cocoa.framework, so at runtime dyld has to do much more searching. The linker in Mac OS X 10.5 now automatically recognizes public re-exported dylibs and implicitly links with them. The result is that the two-level namespace encodings are better (e.g _objc_msgSend is now encoded as coming from libobjc instead of from Cocoa.framework) which result in less work for dyld and better launch times.
-mlong-calls no longer needed
The ppc and ppc64 architectures can only branch +/- 16MB. If your linkage unit has more that 16MB of code you might get link failures. In previous tools releases, the fix was to compile with -mlong-calls (aka -mlong-branch) which used a multi-instruction sequence to branch +/- 4GB. The downside is that this made all code bigger. In Mac OS X 10.5, you no longer need the -mlong-calls option. Instead the linker detects out of range branches and inserts “jump islands”. If your project uses the -mlong-calls option, you should remove it to shrink your code size.
The linker is RAM intensive. Linking a large project can cause the linker’s working set to grow larger than the available RAM, resulting in significant thrashing and very slow link times.
The linker defers to ld_classic when linking -static. Thus all kexts are built with ld_classic.
You can’t create static libraries (archives) of llvm bitcode object files. Therefore, if a large project builds using an intermediate static library, you cannot switch the project to build with llvm-gcc -O4 and get Link Time Optimizations (LTO).
LTO will fail if an llvm bitcode file needs a (mach-o) module from a static library and that module uses a symbol from a dylib that nothing else uses. One work around is to use -all_load which force the linker to load all modules from static libraries.
If an object file contains a tentative definition (common), the linker does not search static libraries (archives) for true definitions to override the tentative one.
Last updated: 2008-05-29
