ld64-136.tar.gz

[apple/ld64.git] / doc / man / man1 / ld.1

.Dd March 7, 2011
.Dt ld 1
.Os Darwin
.Sh NAME
.Nm ld
.Nd "linker"
.Sh SYNOPSIS
.Nm
files... 
.Op options 
.Op Fl o Ar outputfile 
.Sh DESCRIPTION
The
.Nm ld
command combines several object files and libraries, resolves references, and
produces an ouput file. 
.Nm ld
can produce a final linked image (executable, dylib, or bundle), or with the -r
option, produce another object file.  If the -o option is not used, the output
file produced is named "a.out".
.Ss Universal
The linker accepts universal (multiple-architecture) input files, but
always creates a "thin" (single-architecture), standard Mach-O output file.
The architecture for the output file is specified using the -arch option.  
If this option is not used,
.Nm ld
attempts to determine the output architecture by examining the object
files in command line order.  The first "thin"
architecture determines that of the output file.  If no input
object file is a "thin" file, the native 32-bit architecture for the host is used.
.Pp
Usually, 
.Nm ld
is not used directly.  Instead the 
.Xr gcc(1)
compiler driver invokes
.Nm ld.
The compiler driver can be passed multiple -arch options and it will create a 
universal final linked image by invoking 
.Nm ld
multiple times and then running
.Xr lipo(1)
merge the outputs into a universal file.
.Ss Layout
The object files are loaded in the order in which they are specified on the
command line.  The segments and the sections in those segments will appear in 
the output file in the order they are encountered in the object files being linked. 
All zero fill sections will appear after all non-zero fill sections in their segments.
Sections created from files with the -sectcreate option will be laid out at after 
sections from .o files. The use of the -order_file option will alter the layout 
rules above, and move the symbols specified to start of their section.
.Ss Libraries
A static library (aka static archive) is a collection of .o files with a table of contents
that lists the global symbols in the .o files. 
.Nm ld
will only pull .o files out of a static library if needed to resolve some symbol reference.
Unlike traditional linkers, 
.Nm ld
will continually search a static library while linking. There is no need to specify a static
library multiple times on the command line.  
.Pp
A dynamic library (aka dylib or framework) is a final linked image.  Putting a dynamic
library on the command line causes two things: 1) The generated final linked image 
will have encoded that it depends on that dynamic library. 2) Exported symbols from the
dynamic library are used to resolve references.  
.Pp
Both dynamic and static libraries are searched as they appear on the command line.  
.Ss Search paths
.Nm ld
maintains a list of directories to search for a library or framework to use.  The default
library search path is /usr/lib then /usr/local/lib.  The -L option will add a new library search
path.  The default framework search path is /Library/Frameworks then /System/Library/Frameworks.
(Note: previously, /Network/Library/Frameworks was at the end of the default path.  If you need
that functionality, you need to explicitly add -F/Network/Library/Frameworks). 
The -F option will add a new framework search path.  The -Z option will remove
the standard search paths.  The -syslibroot option will prepend a prefix to all search
paths.
.Ss Two-level namespace
By default all references resolved to a dynamic library record the library to which 
they were resolved. At runtime, dyld uses that information to directly resolve
symbols.  The alternative is to use the -flat_namespace option.  With flat namespace,
the library is not recorded.  At runtime, dyld will search each dynamic library in load
order when resolving symbols. This is slower, but more like how other operating systems 
resolve symbols. 
.Ss Indirect dynamic libraries
If the command line specifies to link against dylib A, and when dylib A was built it linked
against dylib B, then B is considered an indirect dylib.  
When linking for two-level namespace, ld does not look at indirect dylibs, except when 
re-exported by a direct dylibs.  On the other hand when linking for flat namespace, 
ld does load all indirect dylibs and uses them to resolve references.
Even though indirect dylibs are specified via a full path, 
.Nm ld
first uses the specified search paths to locate each indirect dylib.  If one cannot
be found using the search paths, the full path is used.
.Ss Dynamic libraries undefines
When linking for two-level namespace, 
.Nm ld 
does not verify that undefines in dylibs actually
exist.  But when linking for flat namespace, 
.Nm ld
does check that all undefines from all loaded dylibs have a matching definition.  
This is sometimes used to force selected functions to be loaded from a static library.
.Sh OPTIONS
.Ss Options that control the kind of output
.Bl -tag
.It Fl execute
The default.  Produce a mach-o main executable that has file type MH_EXECUTE.
.It Fl dylib
Produce a mach-o shared library that has file type MH_DYLIB.
.It Fl bundle
Produce a mach-o bundle that has file type MH_BUNDLE.
.It Fl r
Merges object files to produce another mach-o object file with file type MH_OBJECT.  
.It Fl dylinker
Produce a mach-o dylinker that has file type MH_DYLINKER.  Only used when building dyld.
.It Fl dynamic
The default.  Implied by -dylib, -bundle, or -execute
.It Fl static
Produces a mach-o file that does not use the dyld.  Only used building the kernel. 
.It Fl arch Ar arch_name
Specifies which architecture (e.g. ppc, ppc64, i386, x86_64) the output file should be.
.It Fl o Ar path
Specifies the name and location of the output file.  If not specified, `a.out' is used.
.El
.Ss Options that control libraries
.Bl -tag
.It Fl l Ns x
This option tells the linker to search for libx.dylib or libx.a in the library search path.
If string x is of the form y.o, then that file is searched for in the same places, but without
prepending `lib' or appending `.a' or `.dylib' to the filename.
.It Fl weak-l Ns Ar x
This is the same as the -lx but forces the library and all references to it to be marked as weak imports.
That is, the library is allowed to be missing at runtime.
.It Fl weak_library Ar path_to_library
This is the same as listing a file name path to a library on the link line except that it forces the
library and all references to it to be marked as weak imports. 
.It Fl reexport-l Ns Ar x
This is the same as the -lx but specifies that the all symbols in library x should be available to 
clients linking to the library being created.  This was previously done with a separate -sub_library option.
.It Fl reexport_library Ar path_to_library
This is the same as listing a file name path to a library on the link line and it specifies that the 
all symbols in library path should be available to clients linking to the library being created.
This was previously done with a separate -sub_library option.
.It Fl lazy-l Ns Ar x
This is the same as the -lx but it is only for shared libraries and the linker
will construct glue code so that the shared library is not loaded until 
the first function in it is called.
.It Fl lazy_library Ar path_to_library
This is the same as listing a file name path to a shared library on the link line
except that the linker will construct glue code so that the shared library is not 
loaded until the first function in it is called.
.It Fl upward-l Ns Ar x
This is the same as the -lx but specifies that the dylib is an upward dependency. 
.It Fl upward_library Ar path_to_library
This is the same as listing a file name path to a library on the link line but also marks 
the dylib as an upward dependency.
.It Fl L Ns dir
Add 
.Ar dir 
to the list of directories in which to search for libraries. 
Directories specified with -L are searched in the order they appear on the command line
and before the default search path. In Xcode4 and later, there can be a space between
the -L and directory.
.It Fl Z
Do not search the standard directories when searching for libraries and frameworks.
.It Fl syslibroot Ar rootdir
Prepend 
.Ar rootdir 
to all search paths when searching for libraries or frameworks.
.It Fl search_paths_first
This is now the default (in Xcode4 tools).  When processing -lx the linker now searches each directory 
in its library search paths for `libx.dylib' then `libx.a' before the moving on to the next path 
in the library search path.  
.It Fl search_dylibs_first
Changes the searching behavior for libraries.  The default is that when processing -lx the linker
searches each directory in its library search paths for `libx.dylib' then `libx.a'.
This option changes the behavior to first search for a file of the form `libx.dylib' in each directory
in the library search path, then a file of the form `libx.a' is searched for in the library search paths.
This option restores the search behavior of the linker prior to Xcode4.
.It Fl framework Ar name[,suffix]
This option tells the linker to search for `name.framework/name' the framework search path.
If the optional suffix is specified the framework is first searched for the name with the suffix and then without
(e.g. look for `name.framework/name_suffix' first, if not there try `name.framework/name').
.It Fl weak_framework Ar name[,suffix]
This is the same as the -framework name[,suffix] but forces the framework and all 
references to it to be marked as weak imports. 
.It Fl reexport_framework Ar name[,suffix]
This is the same as the -framework name[,suffix] but also specifies that the 
all symbols in that framework should be available to clients linking to the library being created.
This was previously done with a separate -sub_umbrella option.
.It Fl lazy_framework Ar name[,suffix]
This is the same as the -framework name[,suffix] except that the linker will 
construct glue code so that the framework is not 
loaded until the first function in it is called.  You cannot directly access
data or Objective-C classes in a framework linked this way.
.It Fl upward_framework Ar name[,suffix]
This is the same as the -framework name[,suffix] but also specifies that the 
framework is an upward dependency.  
.It Fl F Ns dir
Add 
.Ar dir
to the list of directories in which to search for frameworks. 
Directories specified with -F are searched in the order they appear on the command line
and before the default search path. In Xcode4 and later, there can be a space between
the -F and directory.
.It Fl all_load
Loads all members of static archive libraries.
.It Fl ObjC
Loads all members of static archive libraries that implement an Objective-C class or category.
.It Fl force_load Ar path_to_archive
Loads all members of the specified static archive library.  Note: -all_load forces all members of all
archives to be loaded.  This option allows you to target a specific archive.
.El
.Ss Options that control additional content
.Bl -tag
.It Fl sectcreate Ar segname sectname file
The section 
.Ar sectname 
in the segment 
.Ar segname 
is created from the contents of file 
.Ar file.