Blame - docs/CommandGuide/gccld.html - platform/external/llvm

blob: 6eef165db6975971b27b1ac3b3be05ad7913ae6e [file] [log] [blame]

John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	1	<html>
				2	<title>
Chris Lattner	ee43b69	2003-09-25 19:50:05 +0000	[diff] [blame]	3	LLVM: gccld tool
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	4	</title>
				5
				6	<body>
				7
				8	<center>
Chris Lattner	ee43b69	2003-09-25 19:50:05 +0000	[diff] [blame]	9	<h1>LLVM: gccld tool</h1>
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	10	</center>
				11	<HR>
				12
				13	<h3>
				14	NAME
				15	</h3>
				16
				17	gccld
				18
				19	<h3>
				20	SYNOPSIS
				21	</h3>
				22
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	23	gccld [options] < filename> [ filename ...]
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	24	<h3>
				25	DESCRIPTION
				26	</h3>
				27
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	28	The gccld utility takes a set of LLVM bytecode files and links them together
				29	into a single LLVM bytecode file. The output bytecode file can be another
				30	bytecode library or an executable bytecode program. Using additional options,
				31	gccld is able to produce native code executables.
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	32	<p>
				33	The gccld utility is primarily used by the GCC front end, and as such, attempts
				34	to mimic the interface provided by the default system linker so that it can act
				35	as a "drop-in" replacement.
				36
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	37	<h4>
				38	Search Order
				39	</h4>
				40	When looking for objects specified on the command line, gccld will search for
				41	the object first in the current directory and then in the directory specified
				42	by LLVM_LIB_SEARCH_PATH. If it cannot find the object, it fails.
				43	<p>
				44	When looking for a library specified with the -l option, gccld first attempts
				45	to load a file with that name from the current directory. If that fails, it
				46	looks for lib<library>.bc, lib<library>.a, or
				47	lib<library>.so, in that order, in each directory added to the library
				48	search path with the -L option. These directories are searched in order they
				49	were specified. If the library cannot be located, then gccld looks in the
				50	directory specified by the LLVM_LIB_SEARCH_PATH environment variable. If it
				51	does not find lib<library>.[bc \| a \| so] there, it fails.
				52
				53	The -L option is global. It does not matter where it is specified in the list
				54	of command line arguments; the directory is simply added to the search path and
				55	is applied to all libraries, preceding or succeeding, in the command line.
				56
				57	<h4>
				58	Link order
				59	</h4>
				60	All object files are linked first in the order they were specified on the
				61	command line. All library files are linked next. Some libraries may not be
				62	linked into the object program; see below.
				63
				64	<h4>
				65	Library Linkage
				66	</h4>
				67	Object files and static bytecode objects are always linked into the output
				68	file. Library archives (.a files) load only the objects within the archive
				69	that define symbols needed by the output file. Hence, libraries should be
				70	listed after the object files and libraries which need them; otherwise, the
				71	library may not be linked in, and the dependent library will not have its
				72	undefined symbols defined.
				73
				74	<h4>
				75	Native code generation
				76	</h4>
				77	The gccld program has limited support for native code generation.
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	78	<h3>
				79	OPTIONS
				80	</h3>
				81
				82	<ul>
				83	<li> -help
				84	<br>
				85	Print a summary of command line options.
				86	<p>
				87
				88	<li> -o <filename>
				89	<br>
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	90	Specify the output filename which will hold the linked bytecode.
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	91	<p>
				92
				93	<li> -stats
				94	<br>
				95	Print statistics.
				96	<p>
				97
				98	<li> -time-passes
				99	<br>
				100	Record the amount of time needed for each pass and print it to standard
				101	error.
				102	<p>
				103
				104	<li> -verify
				105	<br>
				106	Verify each pass result.
				107	<p>
				108
				109	<li> -L=<directory>
				110	<br>
				111	Add directory to the list of directories to search when looking for
				112	libraries.
				113	<p>
				114
				115	<li> -disable-internalize
				116	<br>
				117	Do not mark all symbols as internal.
				118	<p>
				119
				120	<li> -internalize-public-api-file <filename>
				121	<br>
				122	Preserve the list of symbol names in the file filename.
				123	<p>
				124
				125	<li> -internalize-public-api-list <list>
				126	<br>
				127	Preserve the symbol names in list.
				128	<p>
				129
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	130	<li> -l=<library>
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	131	<br>
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	132	Specify libraries to include when linking the output file. When linking,
				133	gccld will first attempt to load a file with the pathname library. If that
				134	fails, it will then attempt to load lib<library>.bc,
				135	lib<library>.a, and lib<library>.so, in that order.
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	136	<p>
				137
				138	<li> -link-as-library
				139	<br>
				140	Link the .bc files together as a library, not an executable.
				141	<p>
				142
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	143	<li> -native
				144	<br>
				145	Generate a native, machine code executable.
John Criswell	b7fcd30	2003-09-25 19:14:51 +0000	[diff] [blame]	146	<p>
				147	When generating native executables, gccld first checks for a bytecode version
				148	of the library and links it in, if necessary. If the library is missing,
				149	gccld skips it. Then, gccld links in the same libraries as native code.
				150	<p>
				151	In this way, gccld should be able to link in optimized bytecode subsets of
				152	common libraries and then link in any part of the library that hasn't been
				153	converted to bytecode.
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	154	<p>
				155
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	156	<li> -s
				157	<br>
				158	Strip symbol information from the generated executable.
				159	<p>
				160
				161	<li> -v
				162	<br>
				163	Print information about actions taken.
				164	</ul>
				165
				166	<h3>
				167	EXIT STATUS
				168	</h3>
				169
				170	If gccld succeeds, it will exit with 0. Otherwise, if an error occurs, it
				171	will exit with a non-zero value.
				172
				173	<h3>
				174	SEE ALSO
				175	</h3>
John Criswell	52f68b8	2003-09-25 19:10:25 +0000	[diff] [blame]	176	gccas
				177
				178	<h3>
				179	BUGS
				180	</h3>
				181	The -L option cannot be used for find native code libraries when using the
				182	-native option.
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	183
				184	<HR>
John Criswell	3200330	2003-09-11 20:23:52 +0000	[diff] [blame]	185	<a href="http://llvm.cs.uiuc.edu">LLVM Team</a>
John Criswell	ecf32e5	2003-09-11 19:58:03 +0000	[diff] [blame]	186	</body>
				187	</html>
				188