docs/llvm-mcld.pod

=pod

=head1 NAME

llvm-mcld - LLVM linker for mobile computing

=head1 SYNOPSIS

llvm-mcld [B<options>] I<objfile> ...

=head1 DESCRIPTION

B<llvm-mcld> is a link editor as GNU linker ld or Google gold linker.

B<llvm-mcld> combines several object files and libraries, ties up their symbol
references, relocates their data, and produces an output file (executable,
dylib or another object file).

B<llvm-mcld> is desinged for supporting multiple formats on multiple target
platforms.  This allows B<llvm-mcld> to read, combine, and produce object files
in many different formats for different platforms

Furthermore, B<llvm-mcld> leverages B<LLVM> and has the same ability as B<llc>.
It can read not only object files ('.o') and libraries ('.so'), but also
I<LLVM bitcode> ('bc'). It can produces not only shared objects ('.so'), but
also assembly file ('.s') and relocatable objects ('.o').

So far, B<llvm-mcld> supports B<Android> on multiple kinds of processors -
combines B<ELF> objects for B<i386>, B<ARM> and B<Mips> platforms, and produces
shared objects for JNI (Jave Native Interface) application. Executable files
and incremental linking are not supported in this version.

=head1 OPTIONS

A frequent use of B<llvm-mcld> is to link standard Unix object files on a
standard, supported Unix system. On such a system, to link a file "hello.o":

	llvm-mcld -filetype=dso -o <output> /lib/crt0.o ./hello.o -lc

This tells B<llvm-mcld> to produce an output file called I<output> as the
result of linking the file F</lib/crt0.o>, F<./hello.o> and the library
F<libc.so>, which comes from the standard searching directories. (See the
detail of the B<-l> option below.)

The other frequent use of B<llvm-mcld> is to generate standard Unix object
file from LLVM bitcode, such as B<llc>:

	llvm-mcld -filetype=obj -o <output> -dB ./hello.bc

B<-dB> option specify the input LLVM bitcode. B<llvm-mcld> compiles
F<./hello.bc>, and produce a relocatable object called I<output> as the result
of compilation.

Other B<llvm-mcld> options are as follows:

=head2 Options that control the kind of output

=over

=item B<-filetype>=I<filetype>

Control the file type of outputs. I<filetype> can be one of the list:

=over 2

=item I<dso>

Emit a shared object ('.so', as known as I<dynamic shared library>).

=item I<exe>

Emit a executable file ('.exe').

=item I<asm>

Emit an assembly file ('.s').

=item I<obj>

Emit a relocatable object file ('.o). If B<-r> option is not on the command
line, B<llvm-mcld> does not link incrementally. Instead, B<llvm-mcld> behaves
like B<llc>, compiles LLVM bitcode and produce correponding relocatable object.

=back

=item B<-o> I<output>

=item B<--output=>I<output>

Use I<output> as the name of the result produced by B<llvm-mcld>. If this
option is not specified, the name B<a.out> is used by default.

=item B<-shared>

=item B<--Bshareable>

Create a shared library. This is currently only supported on ELF.

=back

=head2 Options that control the searching of inputs

=over

=item B<--sysroot=>I<directory>

Use directory as the location of the sysroot, overriding the configure-time
default.

=item B<-L> I<searchdir>

=item B<--library-path=>I<searchdir>

Add the path I<searchdir> to the list of paths that B<llvm-mcld> will search
for archives, shared libraries and link scripts.  You may use this option many
times.

The directories are searched in the order in which they are specified on the
command line.  Directories specified on the command line are searched before
the default directories.  All -L options apply to all -l options, regardless of
the order in which the options appear.  -L options do not affect how B<llvm-mcld>
searches for a linker script unless -T option is specified.

If searchdir begins with "B<=>", then the "B<=>" will be replaced by the sysroot
prefix, a path specified by B<--sysroot>.

=item B<-l>I<namespec>

=item B<--library=>I<namespec>

Add the archive or shared library whose file name is specified by namespec to
the list of files to link. This option may be used many times. B<llvm-mcld>
will search the library path for a file called I<libnamespec.a> by default.

On systems which support shared libraries, B<llvm-mcld> may also search for
files called I<libnamespec.so> before searching I<libnamespec.a>. The searching
priority is dependent on system's configuration. For example, on ARM Android
system, B<llvm-mcld> will search I<libnamespec.so> before searching
I<libnamespec.a>.

=back

=head2 Machine Dependent Options

=over

=item B<-mtriple=>I<target triple>

Specify the environment for which to generate output file.
For example:

	llvm-mcld -mtriple=arm-none-linux-gnueabi

=item B<-march=>I<arch>

Specify the architecture for which to generate output file. Currently supported
architecture are:

I<arm> I<x86>  I<mipsel>

=item B<-mcpu=>I<cpuname>

Specify a specific processor chip in the current architecture to generate code
for. By default, this is refered from the target triple and auto-detected to
the current architecture.

Get the list of available CPUs, try:

	llvm-mcld -marhc=XXX -mcpu=help

=back

=head2 Options that control LLVM

If you use B<llvm-mcld> as B<llc>, here are some important options in B<llc>.

=over

=item B<relocation-model>=I<model>


Choose the relocation model for output file.

=over

=item I<default>

Use target default relocation model. This is default option.

=item I<static>

generate non-relocatable code.

=item I<pic>

Emit position independent code (PIC) suitable for use in a shared library.

=item I<dynamic-no-pic>

Relocatable external references, non-relocatable code.

=back

=item B<-fPIC>

This option is the same as I<-relocation-model=pic>. Use for convenience.

=back

=head2 Options for GNU ld compatibility

=over

=item B<-z> keyword

The recognized keywords are:

=over

=item I<combreloc>

Sort dynamic relocations to optimize dynamic linker. Relocations those refer to
the same symbol are put together in dynamic relocation section.

=item I<defs>

Report undefined symbols in object files.

=item I<execstack>

Mark output as requiring executable stack.

=item I<initfirst>

Mark DSO to be initialized first at runtime. Set Dynamic section DT_FLAGS:
DF_1_INITFIRST.

=item I<interpose>

Mark object to interpose all DSOs but executable. Set Dynamic section DT_FLAGS:
DF_1_INTERPOSE.

=item I<lazy>

Mark object lazy runtime binding (default).

=item I<loadfltr>

Mark object requiring immediate process. Set Dynamic section DT_FLAGS:
DF_1_LOADFLTR.

=item I<muldefs>

Allow multiple definitions when symbol resolution.

=item I<nocombreloc>

Do not preform relocs combining.

=item I<nocopyreloc>

Do not create copy relocs.

=item I<nodefaultlib>

Mark object not to use default search paths. Set Dynamic section DT_FLAGS:
DF_1_NODEFLIB.

=item I<nodelete>

Mark DSO non-deletable at runtime. Set Dynamic section DT_FLAGS: DF_1_NODELETE.

=item I<nodlopen>

Mark DSO not available to dlopen. Set Dynamic section DT_FLAGS: DF_1_NOOPEN.

=item I<nodump>

Mark DSO not available to dldump. Set Dynamic section DT_FLAGS: DF_1_NODUMP.

=item I<noexecstack>

Mark output as not requiring executable stack.

=item I<norelro>

Do not create an ELF "PT_GNU_RELRO" segment in the output object.

=item I<now>

Mark object non-lazy runtime binding. Set DT_BIND_NOW and DT_FLAGS: DF_1_NOW in
dynamic section; treat .got.plt as a relro section.

=item I<origin>

Mark DSO to indicate that needs immediate $ORIGIN processing at runtime. Set
Dynamic section DT_FLAGS: DF_ORIGIN and DF_1_ORIGIN.

=item I<relro>

Create an ELF "PT_GNU_RELRO" segment in the output object.

=item I<max-page-size=SIZE>

set the maximum page size to SIZE.

=item I<common-page-size=SIZE>

set the common page size to SIZE.

=back

=back

=head2 Options for developers

=over

=item B<-unittest>

Examine MCLinker by unit-test cases.

=back

=head1 SEE ALSO

I<llc>(1), I<ld>(1), I<ar>(1) and the Info entries for I<binutils> and I<ld>.

=cut