Commit | Line | Data |
---|---|---|
0acfc451 | 1 | .\" Copyright (c) 1991, 1992 Free Software Foundation |
8fbb7351 RP |
2 | .\" See section COPYING for conditions for redistribution |
3 | .\" $Id$ | |
0acfc451 | 4 | .TH gld 1 "23 January 1992" "cygnus support" "GNU Development Tools" |
8fbb7351 RP |
5 | .de BP |
6 | .sp | |
7 | .ti \-.2i | |
8 | \(** | |
9 | .. | |
10 | ||
11 | .SH NAME | |
12 | gld \- the GNU linker | |
13 | ||
14 | .SH SYNOPSIS | |
15 | .hy 0 | |
16 | .na | |
17 | .TP | |
18 | .B gld | |
19 | .RB "[\|" \-o " | |
20 | .I output\c | |
21 | \&\|] \c | |
22 | .I objfiles\c | |
23 | \&.\|.\|. | |
24 | .br | |
25 | .RB "[\|" \-A\c | |
26 | .I architecture\c | |
27 | \&\|] | |
28 | .RB "[\|" "\-b\ "\c | |
29 | .I input-format\c | |
30 | \&\|] | |
31 | .RB "[\|" \-Bstatic "\|]" | |
32 | .RB "[\|" "\-c\ "\c | |
33 | .I commandfile\c | |
34 | \&\|] | |
35 | .RB "[\|" \-d | \-dc | \-dp\c | |
36 | \|] | |
37 | .br | |
38 | .RB "[\|" "\-defsym\ "\c | |
39 | .I symbol\c | |
40 | \& = \c | |
41 | .I expression\c | |
42 | \&\|] | |
43 | .RB "[\|" "\-e\ "\c | |
44 | .I entry\c | |
45 | \&\|] | |
46 | .RB "[\|" \-F "\|]" | |
47 | .RB "[\|" "\-F\ "\c | |
48 | .I format\c | |
49 | \&\|] | |
50 | .RB "[\|" "\-format\ "\c | |
51 | .I input-format\c | |
52 | \&\|] | |
53 | .RB "[\|" \-g "\|]" | |
54 | .RB "[\|" \-i "\|]" | |
55 | .RB "[\|" \-l\c | |
56 | .I ar\c | |
57 | \&\|] | |
58 | .RB "[\|" \-L\c | |
59 | .I searchdir\c | |
60 | \&\|] | |
61 | .RB "[\|" \-M | \-m "\|]" | |
62 | .RB "[\|" \-n "\|]" | |
63 | .RB "[\|" \-noinhibit-exec "\|]" | |
64 | .RB "[\|" "\-R\ "\c | |
65 | .I filename\c | |
66 | \&\|] | |
0acfc451 | 67 | .RB "[\|" \-relax "\|]" |
8fbb7351 RP |
68 | .RB "[\|" \-r | \-Ur "\|]" |
69 | .RB "[\|" \-S "\|]" | |
70 | .RB "[\|" \-s "\|]" | |
71 | .RB "[\|" "\-T\ "\c | |
72 | .I commandfile\c | |
73 | \&\|] | |
74 | .RB "[\|" "\-Ttext\ "\c | |
75 | .I textorg\c | |
76 | \&\|] | |
77 | .RB "[\|" "\-Tdata\ "\c | |
78 | .I dataorg\c | |
79 | \&\|] | |
80 | .RB "[\|" "\-Tbss\ "\c | |
81 | .I bssorg\c | |
82 | \&\|] | |
83 | .RB "[\|" \-t "\|]" | |
84 | .RB "[\|" "\-u\ "\c | |
85 | .I sym\c | |
86 | \&] | |
87 | .RB "[\|" \-v "\|]" | |
88 | .RB "[\|" \-X "\|]" | |
89 | .RB "[\|" \-x "\|]" | |
90 | .RB "[\|" { \c | |
91 | .I script\c | |
92 | .BR } "\|]" | |
93 | .ad b | |
94 | .hy 1 | |
95 | .SH DESCRIPTION | |
96 | \c | |
97 | .B gld\c | |
98 | \& combines a number of object and archive files, relocates | |
99 | their data and ties up symbol references. Often the last step in | |
100 | building a new compiled program to run is a call to \c | |
101 | .B gld\c | |
102 | \&. | |
103 | ||
104 | \c | |
105 | .B gld\c | |
106 | \& accepts Linker Command Language files | |
107 | to provide explicit and total control over the linking process. | |
108 | This man page does not describe the command language; see the `\|\c | |
109 | .B ld\c | |
110 | \|' entry in `\|\c | |
111 | .B info\c | |
112 | \|', or the manual | |
113 | .I | |
114 | gld: the GNU linker | |
115 | \&, for full details on the command language and on other aspects of | |
116 | the GNU linker. | |
117 | ||
118 | This version of \c | |
119 | .B gld\c | |
120 | \& uses the general purpose BFD libraries | |
121 | to operate on object files. This allows \c | |
122 | .B gld\c | |
123 | \& to read, combine, and | |
124 | write object files in many different formats\(em\&for example, COFF or | |
125 | \c | |
126 | .B a.out\c | |
127 | \&. Different formats may be linked together to produce any | |
128 | available kind of object file. You can use `\|\c | |
129 | .B objdump \-i\c | |
130 | \|' to get a list of formats supported on various architectures; see | |
131 | .BR objdump ( 1 ). | |
132 | ||
133 | Aside from its flexibility, the GNU linker is more helpful than other | |
134 | linkers in providing diagnostic information. Many linkers abandon | |
135 | execution immediately upon encountering an error; whenever possible, | |
136 | \c | |
137 | .B gld\c | |
138 | \& continues executing, allowing you to identify other errors | |
139 | (or, in some cases, to get an output file in spite of the error). | |
140 | ||
141 | The GNU linker \c | |
142 | .B gld\c | |
143 | \& is meant to cover a broad range of situations, | |
144 | and to be as compatible as possible with other linkers. As a result, | |
145 | you have many choices to control its behavior through the command line, | |
146 | and through environment variables. | |
147 | ||
148 | .SH OPTIONS | |
149 | The plethora of command-line options may seem intimidating, but in | |
150 | actual practice few of them are used in any particular context. | |
151 | For instance, a frequent use of \c | |
152 | .B gld\c | |
153 | \& is to link standard Unix | |
154 | object files on a standard, supported Unix system. On such a system, to | |
155 | link a file \c | |
156 | .B hello.o\c | |
157 | \&: | |
158 | .sp | |
159 | .br | |
160 | $\ gld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc | |
161 | .br | |
162 | .sp | |
163 | This tells \c | |
164 | .B gld\c | |
165 | \& to produce a file called \c | |
166 | .B output\c | |
167 | \& as the | |
168 | result of linking the file \c | |
169 | .B /lib/crt0.o\c | |
170 | \& with \c | |
171 | .B hello.o\c | |
172 | \& and | |
173 | the library \c | |
174 | .B libc.a\c | |
175 | \& which will come from the standard search | |
176 | directories. | |
177 | ||
178 | The command-line options to \c | |
179 | .B gld\c | |
180 | \& may be specified in any order, and | |
181 | may be repeated at will. For the most part, repeating an option with a | |
182 | different argument will either have no further effect, or override prior | |
183 | occurrences (those further to the left on the command line) of an | |
184 | option. | |
185 | ||
186 | The exceptions\(em\&which may meaningfully be used more than once\(em\&are | |
187 | \c | |
188 | .B \-A\c | |
189 | \&, \c | |
190 | .B \-b\c | |
191 | \& (or its synonym \c | |
192 | .B \-format\c | |
193 | \&), \c | |
194 | .B \-defsym\c | |
195 | \&, | |
196 | \c | |
197 | .B \-L\c | |
198 | \&, \c | |
199 | .B \-l\c | |
200 | \&, \c | |
201 | .B \-R\c | |
202 | \&, and \c | |
203 | .B \-u\c | |
204 | \&. | |
205 | ||
206 | The list of object files to be linked together, shown as \c | |
207 | .I objfiles\c | |
208 | \&, | |
209 | may follow, precede, or be mixed in with command-line options; save that | |
210 | an \c | |
211 | .I objfiles\c | |
212 | \& argument may not be placed between an option flag and | |
213 | its argument. | |
214 | ||
215 | Usually the linker is invoked with at least one object file, but other | |
216 | forms of binary input files can also be specified with \c | |
217 | .B \-l\c | |
218 | \&, | |
219 | \c | |
220 | .B \-R\c | |
221 | \&, and the script command language. If \c | |
222 | .I no\c | |
223 | \& binary input | |
224 | files at all are specified, the linker does not produce any output, and | |
225 | issues the message `\|\c | |
226 | .B No input files\c | |
227 | \|'. | |
228 | ||
229 | Option arguments must either follow the option letter without intervening | |
230 | whitespace, or be given as separate arguments immediately following the | |
231 | option that requires them. | |
232 | ||
233 | .TP | |
234 | .IR "objfiles" .\|.\|. | |
235 | The object files \c | |
236 | .I objfiles\c | |
237 | \& to be linked. | |
238 | ||
239 | .TP | |
240 | .BI "-A" "architecture"\c | |
241 | \& | |
242 | In the current release of \c | |
243 | .B gld\c | |
244 | \&, this option is useful only for the | |
245 | Intel 960 family of architectures. In that \c | |
246 | .B gld\c | |
247 | \& configuration, the | |
248 | \c | |
249 | .I architecture\c | |
250 | \& argument is one of the two-letter names identifying | |
251 | members of the 960 family; the option specifies the desired output | |
252 | target, and warns of any incompatible instructions in the input files. | |
253 | It also modifies the linker's search strategy for archive libraries, to | |
254 | support the use of libraries specific to each particular | |
255 | architecture, by including in the search loop names suffixed with the | |
256 | string identifying the architecture. | |
257 | ||
258 | For example, if your \c | |
259 | .B gld\c | |
260 | \& command line included `\|\c | |
261 | .B \-ACA\c | |
262 | \|' as | |
263 | well as `\|\c | |
264 | .B \-ltry\c | |
265 | \|', the linker would look (in its built-in search | |
266 | paths, and in any paths you specify with \c | |
267 | .B \-L\c | |
268 | \&) for a library with | |
269 | the names | |
270 | .sp | |
271 | .br | |
272 | try | |
273 | .br | |
274 | libtry.a | |
275 | .br | |
276 | tryca | |
277 | .br | |
278 | libtryca.a | |
279 | .br | |
280 | .sp | |
281 | ||
282 | The first two possibilities would be considered in any event; the last | |
283 | two are due to the use of `\|\c | |
284 | .B \-ACA\c | |
285 | \|'. | |
286 | ||
287 | Future releases of \c | |
288 | .B gld\c | |
289 | \& may support similar functionality for | |
290 | other architecture families. | |
291 | ||
292 | You can meaningfully use \c | |
293 | .B \-A\c | |
294 | \& more than once on a command line, if | |
295 | an architecture family allows combination of target architectures; each | |
296 | use will add another pair of name variants to search for when \c | |
297 | .B \-l\c | |
298 | \& | |
299 | specifies a library. | |
300 | ||
301 | .TP | |
302 | .BI "-b " "input-format"\c | |
303 | \& | |
304 | Specify the binary format for input object files that follow this option | |
305 | on the command line. You don't usually need to specify this, as | |
306 | \c | |
307 | .B gld\c | |
308 | \& is configured to expect as a default input format the most | |
309 | usual format on each machine. \c | |
310 | .I input-format\c | |
311 | \& is a text string, the | |
312 | name of a particular format supported by the BFD libraries. | |
313 | \c | |
314 | .B \-format \c | |
315 | .I input-format\c | |
316 | \&\c | |
317 | \& has the same effect. | |
318 | ||
319 | You may want to use this option if you are linking files with an unusual | |
320 | binary format. You can also use \c | |
321 | .B \-b\c | |
322 | \& to switch formats explicitly (when | |
323 | linking object files of different formats), by including | |
324 | \c | |
325 | .B \-b \c | |
326 | .I input-format\c | |
327 | \&\c | |
328 | \& before each group of object files in a | |
329 | particular format. | |
330 | ||
331 | The default format is taken from the environment variable | |
332 | .B GNUTARGET\c | |
333 | \&. You can also define the input | |
334 | format from a script, using the command \c | |
335 | .B TARGET\c | |
336 | \&. | |
337 | ||
338 | .TP | |
339 | .B \-Bstatic | |
340 | This flag is accepted for command-line compatibility with the SunOS linker, | |
341 | but has no effect on \c | |
342 | .B gld\c | |
343 | \&. | |
344 | ||
345 | .TP | |
346 | .BI "-c " "commandfile"\c | |
347 | \& | |
348 | Directs \c | |
349 | .B gld\c | |
350 | \& to read link commands from the file | |
351 | \c | |
352 | .I commandfile\c | |
353 | \&. These commands will completely override \c | |
354 | .B gld\c | |
355 | \&'s | |
356 | default link format (rather than adding to it); \c | |
357 | .I commandfile\c | |
358 | \& must | |
359 | specify everything necessary to describe the target format. | |
360 | ||
361 | ||
362 | You may also include a script of link commands directly in the command | |
363 | line by bracketing it between `\|\c | |
364 | .B {\c | |
365 | \|' and `\|\c | |
366 | .B }\c | |
367 | \|' characters. | |
368 | ||
369 | .TP | |
370 | .B \-d | |
371 | .TP | |
372 | .B \-dc | |
373 | .TP | |
374 | .B \-dp | |
375 | These three options are equivalent; multiple forms are supported for | |
376 | compatibility with other linkers. Use any of them to make \c | |
377 | .B ld\c | |
378 | \& | |
379 | assign space to common symbols even if a relocatable output file is | |
380 | specified (\c | |
381 | .B \-r\c | |
382 | \&). The script command | |
383 | \c | |
384 | .B FORCE_COMMON_ALLOCATION\c | |
385 | \& has the same effect. | |
386 | ||
387 | .TP | |
388 | .BI "-defsym " "symbol"\c | |
389 | \& = \c | |
390 | .I expression\c | |
391 | \& | |
392 | Create a global symbol in the output file, containing the absolute | |
393 | address given by \c | |
394 | .I expression\c | |
395 | \&. You may use this option as many | |
396 | times as necessary to define multiple symbols in the command line. A | |
397 | limited form of arithmetic is supported for the \c | |
398 | .I expression\c | |
399 | \& in this | |
400 | context: you may give a hexadecimal constant or the name of an existing | |
401 | symbol, or use \c | |
402 | .B +\c | |
403 | \& and \c | |
404 | .B \-\c | |
405 | \& to add or subtract hexadecimal | |
406 | constants or symbols. If you need more elaborate expressions, consider | |
407 | using the linker command language from a script. | |
408 | ||
409 | .TP | |
410 | .BI "-e " "entry"\c | |
411 | \& | |
412 | Use \c | |
413 | .I entry\c | |
414 | \& as the explicit symbol for beginning execution of your | |
415 | program, rather than the default entry point. for a | |
416 | discussion of defaults and other ways of specifying the | |
417 | entry point. | |
418 | ||
419 | .TP | |
420 | .B \-F | |
421 | .TP | |
422 | .BI "-F" "format"\c | |
423 | \& | |
424 | Some older linkers used this option throughout a compilation toolchain | |
425 | for specifying object-file format for both input and output object | |
426 | files. \c | |
427 | .B gld\c | |
428 | \&'s mechanisms (the \c | |
429 | .B \-b\c | |
430 | \& or \c | |
431 | .B \-format\c | |
432 | \& options | |
433 | for input files, the \c | |
434 | .B TARGET\c | |
435 | \& command in linker scripts for output | |
436 | files, the \c | |
437 | .B GNUTARGET\c | |
438 | \& environment variable) are more flexible, but | |
439 | but it accepts (and ignores) the \c | |
440 | .B \-F\c | |
441 | \& option flag for compatibility | |
442 | with scripts written to call the old linker. | |
443 | ||
444 | .TP | |
445 | .BI "-format " "input-format"\c | |
446 | \& | |
447 | Synonym for \c | |
448 | .B \-b\c | |
449 | \& \c | |
450 | .I input-format\c | |
451 | \&. | |
452 | ||
453 | .TP | |
454 | .B \-g | |
455 | Accepted, but ignored; provided for compatibility with other tools. | |
456 | ||
457 | .TP | |
458 | .B \-i | |
459 | Perform an incremental link (same as option \c | |
460 | .B \-r\c | |
461 | \&). | |
462 | ||
463 | .TP | |
464 | .BI "-l" "ar"\c | |
465 | \& | |
466 | Add an archive file \c | |
467 | .I ar\c | |
468 | \& to the list of files to link. This | |
469 | option may be used any number of times. \c | |
470 | .B ld\c | |
471 | \& will search its | |
472 | path-list for occurrences of \c | |
473 | .B lib\c | |
474 | .I ar\c | |
475 | \&.a\c | |
476 | \& for every \c | |
477 | .I ar\c | |
478 | \& | |
479 | specified. | |
480 | ||
481 | .TP | |
482 | .BI "-L" "searchdir"\c | |
483 | \& | |
484 | This command adds path \c | |
485 | .I searchdir\c | |
486 | \& to the list of paths that | |
487 | \c | |
488 | .B gld\c | |
489 | \& will search for archive libraries. You may use this option | |
490 | any number of times. | |
491 | ||
492 | The default set of paths searched (without being specified with | |
493 | \c | |
494 | .B \-L\c | |
495 | \&) depends on what emulation mode \c | |
496 | .B gld\c | |
497 | \& is using, and in | |
498 | some cases also on how it was configured. The | |
499 | paths can also be specified in a link script with the \c | |
500 | .B SEARCH_DIR\c | |
501 | \& | |
502 | command. | |
503 | ||
504 | .TP | |
505 | .B \-M | |
506 | .TP | |
507 | .B \-m | |
508 | Print (to the standard output file) a link map\(em\&diagnostic information | |
509 | about where symbols are mapped by \c | |
510 | .B ld\c | |
511 | \&, and information on global | |
512 | common storage allocation. | |
513 | ||
514 | .TP | |
515 | .B \-n | |
516 | sets the text segment to be read only, and \c | |
517 | .B NMAGIC\c | |
518 | \& is written | |
519 | if possible. | |
520 | ||
521 | .TP | |
522 | .B \-noinhibit-exec | |
523 | Normally, the linker will not produce an output file if it encounters | |
524 | errors during the link process. With this flag, you can specify that | |
525 | you wish the output file retained even after non-fatal errors. | |
526 | ||
527 | .TP | |
528 | .BI "-o " "output"\c | |
529 | \& | |
530 | .I output\c | |
531 | \& | |
532 | \c | |
533 | .I output\c | |
534 | \& is a name for the program produced by \c | |
535 | .B ld\c | |
536 | \&; if this | |
537 | option is not specified, the name `\|\c | |
538 | .B a.out\c | |
539 | \|' is used by default. The | |
540 | script command \c | |
541 | .B OUTPUT\c | |
542 | \& can also specify the output file name. | |
543 | ||
544 | .TP | |
545 | .BI "-R " "filename"\c | |
546 | \& | |
547 | .I file\c | |
548 | \& | |
549 | Read symbol names and their addresses from \c | |
550 | .I filename\c | |
551 | \&, but do not | |
552 | relocate it or include it in the output. This allows your output file | |
553 | to refer symbolically to absolute locations of memory defined in other | |
554 | programs. | |
555 | ||
0acfc451 RP |
556 | .TP |
557 | .B \-relax | |
558 | An option with machine dependent effects. Currently this option is only | |
559 | supported on the H8/300. | |
560 | ||
561 | On some platforms, use this option to perform global optimizations that | |
562 | become possible when the linker resolves addressing in your program, such | |
563 | as relaxing address modes and synthesizing new instructions in the | |
564 | output object file. | |
565 | ||
566 | On platforms where this is not supported, `\|\c | |
567 | .B \-relax\c | |
568 | \&\|' is accepted, but has no effect. | |
569 | ||
8fbb7351 RP |
570 | .TP |
571 | .B \-r | |
572 | Generates relocatable output\(em\&i.e., generate an output file that can in | |
573 | turn serve as input to \c | |
574 | .B gld\c | |
575 | \&. This is often called \c | |
576 | .I partial | |
577 | linking\c | |
578 | \&. As a side effect, in environments that support standard Unix | |
579 | magic numbers, this option also sets the output file's magic number to | |
580 | \c | |
581 | .B OMAGIC\c | |
582 | \&. | |
583 | If this option is not specified, an absolute file is produced. When | |
584 | linking C++ programs, this option \c | |
585 | .I will not\c | |
586 | \& resolve references to | |
587 | constructors; \c | |
588 | .B \-Ur\c | |
589 | \& is an alternative. | |
590 | ||
591 | This option does the same as \c | |
592 | .B \-i\c | |
593 | \&. | |
594 | ||
595 | .TP | |
596 | .B \-S | |
597 | Omits debugger symbol information (but not all symbols) from the output file. | |
598 | ||
599 | .TP | |
600 | .B \-s | |
601 | Omits all symbol information from the output file. | |
602 | ||
603 | .TP | |
604 | .BI "{ " "script" " }" | |
605 | You can, if you wish, include a script of linker commands directly in | |
606 | the command line instead of referring to it via an input file. When the | |
607 | character `\|\c | |
608 | .B {\c | |
609 | \|' occurs on the command line, the linker switches to | |
610 | interpreting the command language until the end of the list of commands | |
611 | is reached\(em\&flagged with a closing brace `\|\c | |
612 | .B }\c | |
613 | \|'. Other command-line | |
614 | options will not be recognized while parsing the script. | |
615 | for a description of the command language. | |
616 | ||
617 | .TP | |
618 | .BI "-Tbss " "org"\c | |
619 | .TP | |
620 | .BI "-Tdata " "org"\c | |
621 | .TP | |
622 | .BI "-Ttext " "org"\c | |
623 | Use \c | |
624 | .I org\c | |
625 | \& as the starting address for\(em\&respectively\(em\&the | |
626 | \c | |
627 | .B bss\c | |
628 | \&, \c | |
629 | .B data\c | |
630 | \&, or the \c | |
631 | .B text\c | |
632 | \& segment of the output file. | |
633 | \c | |
634 | .I textorg\c | |
635 | \& must be a hexadecimal integer. | |
636 | ||
637 | .TP | |
638 | .BI "-T " "commandfile"\c | |
639 | \& | |
640 | .TP | |
641 | .BI "-T" "commandfile"\c | |
642 | Equivalent to \c | |
643 | .B \-c \c | |
644 | .I commandfile\c | |
645 | \&\c | |
646 | \&; supported for compatibility with | |
647 | other tools. | |
648 | ||
649 | .TP | |
650 | .B \-t | |
651 | Prints names of input files as \c | |
652 | .B ld\c | |
653 | \& processes them. | |
654 | ||
655 | .TP | |
656 | .BI "-u " "sym"\c | |
657 | \& | |
658 | .I sym\c | |
659 | \& | |
660 | Forces \c | |
661 | .I sym\c | |
662 | \& to be entered in the output file as an undefined symbol. | |
663 | This may, for example, trigger linking of additional modules from | |
664 | standard libraries. \c | |
665 | .B \-u\c | |
666 | \& may be repeated with different option | |
667 | arguments to enter additional undefined symbols. | |
668 | ||
669 | .TP | |
670 | .B \-Ur | |
671 | For anything other than C++ programs, this option is equivalent to | |
672 | \c | |
673 | .B \-r\c | |
674 | \&: it generates relocatable output\(em\&i.e., an output file that can in | |
675 | turn serve as input to \c | |
676 | .B gld\c | |
677 | \&. When linking C++ programs, \c | |
678 | .B \-Ur\c | |
679 | \& | |
680 | \c | |
681 | .I will\c | |
682 | \& resolve references to constructors, unlike \c | |
683 | .B \-r\c | |
684 | \&. | |
685 | ||
686 | .TP | |
687 | .B \-v | |
688 | Display the version number for \c | |
689 | .B gld\c | |
690 | \&. | |
691 | ||
692 | .TP | |
693 | .B \-X | |
694 | If \c | |
695 | .B \-s\c | |
696 | \& or \c | |
697 | .B \-S\c | |
698 | \& is also specified, delete only local symbols | |
699 | beginning with `\|\c | |
700 | .B L\c | |
701 | \|'. | |
702 | ||
703 | .TP | |
704 | .B \-x | |
705 | If \c | |
706 | .B \-s\c | |
707 | \& or \c | |
708 | .B \-S\c | |
709 | \& is also specified, delete all local symbols, | |
710 | not just those beginning with `\|\c | |
711 | .B L\c | |
712 | \|'. | |
713 | ||
714 | .PP | |
715 | ||
716 | .SH ENVIRONMENT | |
717 | \c | |
718 | .B gld\c | |
719 | \& always consults two environment variables: \c | |
720 | .B GNUTARGET\c | |
721 | \& | |
722 | and \c | |
723 | .B LDEMULATION\c | |
724 | \&. Depending on the setting of the latter, other | |
725 | environment variables may be used as well. | |
726 | ||
727 | \c | |
728 | .B GNUTARGET\c | |
729 | \& determines the input-file object format if you don't | |
730 | use \c | |
731 | .B \-b\c | |
732 | \& (or its synonym \c | |
733 | .B \-format\c | |
734 | \&). Its value should be one | |
735 | of the BFD names for an input format. If there is no | |
736 | \c | |
737 | .B GNUTARGET\c | |
738 | \& in the environment, \c | |
739 | .B gld\c | |
740 | \& uses the natural format | |
741 | of the host. If \c | |
742 | .B GNUTARGET\c | |
743 | \& is set to \c | |
744 | .B default\c | |
745 | \& then BFD attempts to discover the | |
746 | input format by examining binary input files; this method often | |
747 | succeeds, but there are potential ambiguities, since there is no method | |
748 | of ensuring that the magic number used to flag object-file formats is | |
749 | unique. However, the configuration procedure for BFD on each system | |
750 | places the conventional format for that system first in the search-list, | |
751 | so ambiguities are resolved in favor of convention. | |
752 | ||
753 | \c | |
754 | .B LDEMULATION\c | |
755 | \& controls some aspects of \c | |
756 | .B gld\c | |
757 | \&'s dominant | |
758 | personality. Although \c | |
759 | .B gld\c | |
760 | \& is flexible enough to permit its use | |
761 | in many contexts regardless of configuration, you can use this variable | |
762 | to make it act more like one or another older linker by default. | |
763 | ||
764 | In particular, the value of \c | |
765 | .B LDEMULATION\c | |
766 | \& controls what default | |
767 | linker script is used (thereby controlling the default input and output | |
768 | formats; ; what default paths are searched for | |
769 | archive libraries; and in some cases whether additional linker script | |
770 | commands are available. | |
771 | ||
772 | Here is the current set of emulations available: | |
773 | ||
774 | .TP | |
775 | .B LDEMULATION=gld | |
776 | Emulate the older GNU linker. When this emulation is selected, the | |
777 | default library search paths are | |
778 | .sp | |
779 | .br | |
780 | /lib | |
781 | .br | |
782 | /usr/lib | |
783 | .br | |
784 | /usr/local/lib/lib | |
785 | .br | |
786 | .sp | |
787 | ||
788 | The default output format is set to \c | |
789 | .B a.out-generic-big\c | |
790 | \&, and the | |
791 | default machine is the system's configured BFD default. | |
792 | ||
793 | .TP | |
794 | .B LDEMULATION=gld68k | |
795 | A variant of the \c | |
796 | .B gld\c | |
797 | \& emulation; only differs in specifically | |
798 | setting the default BFD machine as \c | |
799 | .B m68k\c | |
800 | \&. | |
801 | ||
802 | .TP | |
803 | .B LDEMULATION=gld960 | |
804 | Emulate the Intel port of the older \c | |
805 | .B gld\c | |
806 | \& for the i960 | |
807 | architectures. The default library search paths are taken from two | |
808 | other environment variables, \c | |
809 | .B G960LIB\c | |
810 | \& and \c | |
811 | .B G960BASE\c | |
812 | \&. The | |
813 | default architecture is \c | |
814 | .B i960\c | |
815 | \&. The default output format is set | |
816 | to \c | |
817 | .B b.out.big\c | |
818 | \&, and in fact the default output file name (if | |
819 | \c | |
820 | .B \-o\c | |
821 | \& is not specified) is \c | |
822 | .B b.out\c | |
823 | \&, to reflect this variant | |
824 | format, for this emulation. | |
825 | ||
826 | This emulation can behave slightly differently depending on the setting | |
827 | of the \c | |
828 | .B gld\c | |
829 | \& compile-time switch \c | |
830 | .B GNU960\c | |
831 | \&. If \c | |
832 | .B gld\c | |
833 | \& is | |
834 | compiled with \c | |
835 | .B GNU960\c | |
836 | \& defined, then an additional environment | |
837 | variable\(em\&\c | |
838 | .B GNUTARGET\c | |
839 | \&\(em\&is available; its value, if available, | |
840 | specifies some other default output format than \c | |
841 | .B b.out.big\c | |
842 | \&. | |
843 | ||
844 | .TP | |
845 | .B LDEMULATION=gldm88kbcs | |
846 | Sets the output format to \c | |
847 | .B m88kbcs\c | |
848 | \& and the architecture to | |
849 | \c | |
850 | .B m88k\c | |
851 | \&. Default library search paths are | |
852 | .sp | |
853 | .br | |
854 | /lib | |
855 | .br | |
856 | /usr/lib | |
857 | .br | |
858 | /usr/local/lib | |
859 | .br | |
860 | .sp | |
861 | ||
862 | .TP | |
863 | .B LDEMULATION=lnk960 | |
864 | Emulate the Intel linker \c | |
865 | .B lnk960\c | |
866 | \&. The default output format is | |
867 | \c | |
868 | .B coff-Intel-big\c | |
869 | \&. With this emulation, \c | |
870 | .B gld\c | |
871 | \& | |
872 | supports the additional script commands \c | |
873 | .B HLL\c | |
874 | \& and \c | |
875 | .B SYSLIB\c | |
876 | \& for | |
877 | specification of library archives. This is the only emulation with | |
878 | extensive support for the \c | |
879 | .B \-A\c | |
880 | \& (architecture) command-line option. | |
881 | By default, the architecture \c | |
882 | .B CORE\c | |
883 | \& is assumed, but you can choose | |
884 | additional features from the i960 architecture family by using one of | |
885 | the following with \c | |
886 | .B \-A\c | |
887 | \& (or by using the \c | |
888 | .B OUTPUT_ARCH\c | |
889 | \& command | |
890 | from a script): | |
891 | .sp | |
892 | .br | |
893 | CORE | |
894 | .br | |
895 | KB | |
896 | .br | |
897 | SB | |
898 | .br | |
899 | MC | |
900 | .br | |
901 | XA | |
902 | .br | |
903 | CA | |
904 | .br | |
905 | KA | |
906 | .br | |
907 | SA | |
908 | .br | |
909 | .sp | |
910 | ||
911 | The default libraries are chosen with some attention to the architecture | |
912 | selected; the core library `\|\c | |
913 | .B cg\c | |
914 | \|' is always included, but the library | |
915 | \c | |
916 | .B fpg\c | |
917 | \& is also used if you've specified any of the architectures | |
918 | \c | |
919 | .B KA\c | |
920 | \&, \c | |
921 | .B SA\c | |
922 | \&, or \c | |
923 | .B CA\c | |
924 | \&. | |
925 | ||
926 | Like \c | |
927 | .B gld960\c | |
928 | \&, this emulation uses additional environment variables | |
929 | to set the default library search paths. Also like \c | |
930 | .B gld960\c | |
931 | \&, the | |
932 | behavior of this emulation is slightly different depending on whether | |
933 | \c | |
934 | .B gld\c | |
935 | \& itself was compiled with \c | |
936 | .B GNU960\c | |
937 | \& defined. | |
938 | ||
939 | If your \c | |
940 | .B gld\c | |
941 | \& was compiled with \c | |
942 | .B GNU960\c | |
943 | \& defined, the default | |
944 | paths are taken from all three of \c | |
945 | .B G960LIB\c | |
946 | \&, \c | |
947 | .B G960BASE\c | |
948 | \&, and | |
949 | \c | |
950 | .B I960BASE\c | |
951 | \&. For the first two, paths you supply are automatically | |
952 | suffixed with `\|\c | |
953 | .B /lib/libcoff\c | |
954 | \|'; for the last, your path is | |
955 | automatically suffixed with `\|\c | |
956 | .B /lib\c | |
957 | \|'. | |
958 | ||
959 | If your \c | |
960 | .B gld\c | |
961 | \& was \c | |
962 | .I not\c | |
963 | \& compiled with \c | |
964 | .B GNU960\c | |
965 | \& defined, | |
966 | the default paths are taken from \c | |
967 | .B I960BASE\c | |
968 | \&, and \c | |
969 | .B G960BASE\c | |
970 | \& is | |
971 | only consulted if \c | |
972 | .B I960BASE\c | |
973 | \& is undefined. In this case | |
974 | \c | |
975 | .B G960LIB\c | |
976 | \& is not used at all. | |
977 | ||
978 | .TP | |
979 | .B LDEMULATION=vanilla | |
980 | This is the least specific setting for \c | |
981 | .B gld\c | |
982 | \&. You can set | |
983 | \c | |
984 | .B LDEMULATION=vanilla\c | |
985 | \& to disable emulation of other linkers. This | |
986 | setting makes \c | |
987 | .B gld\c | |
988 | \& take the default machine from the BFD | |
989 | configuration on your system; \c | |
990 | .B a.out-generic-big\c | |
991 | \& is the default | |
992 | target. No other defaults are specified. | |
993 | ||
994 | .PP | |
995 | ||
996 | .SH "SEE ALSO" | |
997 | ||
998 | .BR objdump ( 1 ) | |
999 | .br | |
1000 | .br | |
1001 | .RB "`\|" ld "\|' and `\|" binutils "\|'" | |
1002 | entries in | |
1003 | .B info\c | |
1004 | .br | |
1005 | .I | |
1006 | gld: the GNU linker\c | |
1007 | , Steve Chamberlain and Roland Pesch; | |
1008 | .I | |
1009 | The GNU Binary Utilities\c | |
1010 | , Roland H. Pesch. | |
1011 | ||
1012 | .SH COPYING | |
0acfc451 | 1013 | Copyright (c) 1991, 1992 Free Software Foundation, Inc. |
8fbb7351 RP |
1014 | .PP |
1015 | Permission is granted to make and distribute verbatim copies of | |
1016 | this manual provided the copyright notice and this permission notice | |
1017 | are preserved on all copies. | |
1018 | .PP | |
1019 | Permission is granted to copy and distribute modified versions of this | |
1020 | manual under the conditions for verbatim copying, provided that the | |
1021 | entire resulting derived work is distributed under the terms of a | |
1022 | permission notice identical to this one. | |
1023 | .PP | |
1024 | Permission is granted to copy and distribute translations of this | |
1025 | manual into another language, under the above conditions for modified | |
1026 | versions, except that this permission notice may be included in | |
1027 | translations approved by the Free Software Foundation instead of in | |
1028 | the original English. |