Commit | Line | Data |
---|---|---|
252b5132 RH |
1 | \input texinfo |
2 | @setfilename ldint.info | |
0e9517a9 NC |
3 | @c Copyright 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, |
4 | @c 2003, 2007 | |
a2b64bed | 5 | @c Free Software Foundation, Inc. |
252b5132 RH |
6 | |
7 | @ifinfo | |
8 | @format | |
9 | START-INFO-DIR-ENTRY | |
10 | * Ld-Internals: (ldint). The GNU linker internals. | |
11 | END-INFO-DIR-ENTRY | |
12 | @end format | |
13 | @end ifinfo | |
14 | ||
0e9517a9 | 15 | @copying |
252b5132 RH |
16 | This file documents the internals of the GNU linker ld. |
17 | ||
0e9517a9 | 18 | Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2007 |
a2b64bed | 19 | Free Software Foundation, Inc. |
252b5132 RH |
20 | Contributed by Cygnus Support. |
21 | ||
0e9517a9 NC |
22 | Permission is granted to copy, distribute and/or modify this document |
23 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
24 | any later version published by the Free Software Foundation; with the | |
25 | Invariant Sections being ``GNU General Public License'' and ``Funding | |
26 | Free Software'', the Front-Cover texts being (a) (see below), and with | |
27 | the Back-Cover Texts being (b) (see below). A copy of the license is | |
28 | included in the section entitled ``GNU Free Documentation License''. | |
252b5132 | 29 | |
0e9517a9 | 30 | (a) The FSF's Front-Cover Text is: |
252b5132 | 31 | |
0e9517a9 NC |
32 | A GNU Manual |
33 | ||
34 | (b) The FSF's Back-Cover Text is: | |
35 | ||
36 | You have freedom to copy and modify this GNU Manual, like GNU | |
37 | software. Copies published by the Free Software Foundation raise | |
38 | funds for GNU development. | |
39 | @end copying | |
252b5132 RH |
40 | |
41 | @iftex | |
42 | @finalout | |
43 | @setchapternewpage off | |
44 | @settitle GNU Linker Internals | |
45 | @titlepage | |
46 | @title{A guide to the internals of the GNU linker} | |
47 | @author Per Bothner, Steve Chamberlain, Ian Lance Taylor, DJ Delorie | |
48 | @author Cygnus Support | |
49 | @page | |
50 | ||
51 | @tex | |
52 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
5b343f5a | 53 | \xdef\manvers{2.10.91} % For use in headers, footers too |
252b5132 RH |
54 | {\parskip=0pt |
55 | \hfill Cygnus Support\par | |
56 | \hfill \manvers\par | |
57 | \hfill \TeX{}info \texinfoversion\par | |
58 | } | |
59 | @end tex | |
60 | ||
61 | @vskip 0pt plus 1filll | |
704c465c | 62 | Copyright @copyright{} 1992, 93, 94, 95, 96, 97, 1998, 2000 |
252b5132 RH |
63 | Free Software Foundation, Inc. |
64 | ||
704c465c NC |
65 | Permission is granted to copy, distribute and/or modify this document |
66 | under the terms of the GNU Free Documentation License, Version 1.1 | |
67 | or any later version published by the Free Software Foundation; | |
68 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
69 | Back-Cover Texts. A copy of the license is included in the | |
70 | section entitled "GNU Free Documentation License". | |
252b5132 RH |
71 | |
72 | @end titlepage | |
73 | @end iftex | |
74 | ||
75 | @node Top | |
76 | @top | |
77 | ||
78 | This file documents the internals of the GNU linker @code{ld}. It is a | |
79 | collection of miscellaneous information with little form at this point. | |
80 | Mostly, it is a repository into which you can put information about | |
81 | GNU @code{ld} as you discover it (or as you design changes to @code{ld}). | |
82 | ||
cf055d54 NC |
83 | This document is distributed under the terms of the GNU Free |
84 | Documentation License. A copy of the license is included in the | |
85 | section entitled "GNU Free Documentation License". | |
86 | ||
252b5132 RH |
87 | @menu |
88 | * README:: The README File | |
89 | * Emulations:: How linker emulations are generated | |
90 | * Emulation Walkthrough:: A Walkthrough of a Typical Emulation | |
b044cda1 | 91 | * Architecture Specific:: Some Architecture Specific Notes |
704c465c | 92 | * GNU Free Documentation License:: GNU Free Documentation License |
252b5132 RH |
93 | @end menu |
94 | ||
95 | @node README | |
96 | @chapter The @file{README} File | |
97 | ||
98 | Check the @file{README} file; it often has useful information that does not | |
99 | appear anywhere else in the directory. | |
100 | ||
101 | @node Emulations | |
102 | @chapter How linker emulations are generated | |
103 | ||
104 | Each linker target has an @dfn{emulation}. The emulation includes the | |
105 | default linker script, and certain emulations also modify certain types | |
106 | of linker behaviour. | |
107 | ||
108 | Emulations are created during the build process by the shell script | |
109 | @file{genscripts.sh}. | |
110 | ||
111 | The @file{genscripts.sh} script starts by reading a file in the | |
112 | @file{emulparams} directory. This is a shell script which sets various | |
113 | shell variables used by @file{genscripts.sh} and the other shell scripts | |
114 | it invokes. | |
115 | ||
116 | The @file{genscripts.sh} script will invoke a shell script in the | |
117 | @file{scripttempl} directory in order to create default linker scripts | |
118 | written in the linker command language. The @file{scripttempl} script | |
119 | will be invoked 5 (or, in some cases, 6) times, with different | |
120 | assignments to shell variables, to create different default scripts. | |
121 | The choice of script is made based on the command line options. | |
122 | ||
123 | After creating the scripts, @file{genscripts.sh} will invoke yet another | |
124 | shell script, this time in the @file{emultempl} directory. That shell | |
125 | script will create the emulation source file, which contains C code. | |
126 | This C code permits the linker emulation to override various linker | |
127 | behaviours. Most targets use the generic emulation code, which is in | |
128 | @file{emultempl/generic.em}. | |
129 | ||
130 | To summarize, @file{genscripts.sh} reads three shell scripts: an | |
131 | emulation parameters script in the @file{emulparams} directory, a linker | |
132 | script generation script in the @file{scripttempl} directory, and an | |
133 | emulation source file generation script in the @file{emultempl} | |
134 | directory. | |
135 | ||
136 | For example, the Sun 4 linker sets up variables in | |
137 | @file{emulparams/sun4.sh}, creates linker scripts using | |
138 | @file{scripttempl/aout.sc}, and creates the emulation code using | |
139 | @file{emultempl/sunos.em}. | |
140 | ||
141 | Note that the linker can support several emulations simultaneously, | |
142 | depending upon how it is configured. An emulation can be selected with | |
143 | the @code{-m} option. The @code{-V} option will list all supported | |
144 | emulations. | |
145 | ||
146 | @menu | |
147 | * emulation parameters:: @file{emulparams} scripts | |
148 | * linker scripts:: @file{scripttempl} scripts | |
149 | * linker emulations:: @file{emultempl} scripts | |
150 | @end menu | |
151 | ||
152 | @node emulation parameters | |
153 | @section @file{emulparams} scripts | |
154 | ||
155 | Each target selects a particular file in the @file{emulparams} directory | |
156 | by setting the shell variable @code{targ_emul} in @file{configure.tgt}. | |
157 | This shell variable is used by the @file{configure} script to control | |
158 | building an emulation source file. | |
159 | ||
160 | Certain conventions are enforced. Suppose the @code{targ_emul} variable | |
161 | is set to @var{emul} in @file{configure.tgt}. The name of the emulation | |
162 | shell script will be @file{emulparams/@var{emul}.sh}. The | |
163 | @file{Makefile} must have a target named @file{e@var{emul}.c}; this | |
164 | target must depend upon @file{emulparams/@var{emul}.sh}, as well as the | |
165 | appropriate scripts in the @file{scripttempl} and @file{emultempl} | |
166 | directories. The @file{Makefile} target must invoke @code{GENSCRIPTS} | |
167 | with two arguments: @var{emul}, and the value of the make variable | |
168 | @code{tdir_@var{emul}}. The value of the latter variable will be set by | |
169 | the @file{configure} script, and is used to set the default target | |
170 | directory to search. | |
171 | ||
172 | By convention, the @file{emulparams/@var{emul}.sh} shell script should | |
173 | only set shell variables. It may set shell variables which are to be | |
174 | interpreted by the @file{scripttempl} and the @file{emultempl} scripts. | |
175 | Certain shell variables are interpreted directly by the | |
176 | @file{genscripts.sh} script. | |
177 | ||
178 | Here is a list of shell variables interpreted by @file{genscripts.sh}, | |
179 | as well as some conventional shell variables interpreted by the | |
180 | @file{scripttempl} and @file{emultempl} scripts. | |
181 | ||
182 | @table @code | |
183 | @item SCRIPT_NAME | |
184 | This is the name of the @file{scripttempl} script to use. If | |
185 | @code{SCRIPT_NAME} is set to @var{script}, @file{genscripts.sh} will use | |
b45619c0 | 186 | the script @file{scripttempl/@var{script}.sc}. |
252b5132 RH |
187 | |
188 | @item TEMPLATE_NAME | |
b45619c0 | 189 | This is the name of the @file{emultempl} script to use. If |
252b5132 RH |
190 | @code{TEMPLATE_NAME} is set to @var{template}, @file{genscripts.sh} will |
191 | use the script @file{emultempl/@var{template}.em}. If this variable is | |
192 | not set, the default value is @samp{generic}. | |
193 | ||
194 | @item GENERATE_SHLIB_SCRIPT | |
195 | If this is set to a nonempty string, @file{genscripts.sh} will invoke | |
196 | the @file{scripttempl} script an extra time to create a shared library | |
197 | script. @ref{linker scripts}. | |
198 | ||
199 | @item OUTPUT_FORMAT | |
200 | This is normally set to indicate the BFD output format use (e.g., | |
201 | @samp{"a.out-sunos-big"}. The @file{scripttempl} script will normally | |
202 | use it in an @code{OUTPUT_FORMAT} expression in the linker script. | |
203 | ||
204 | @item ARCH | |
205 | This is normally set to indicate the architecture to use (e.g., | |
206 | @samp{sparc}). The @file{scripttempl} script will normally use it in an | |
207 | @code{OUTPUT_ARCH} expression in the linker script. | |
208 | ||
209 | @item ENTRY | |
210 | Some @file{scripttempl} scripts use this to set the entry address, in an | |
211 | @code{ENTRY} expression in the linker script. | |
212 | ||
213 | @item TEXT_START_ADDR | |
214 | Some @file{scripttempl} scripts use this to set the start address of the | |
215 | @samp{.text} section. | |
216 | ||
252b5132 RH |
217 | @item SEGMENT_SIZE |
218 | The @file{genscripts.sh} script uses this to set the default value of | |
219 | @code{DATA_ALIGNMENT} when running the @file{scripttempl} script. | |
220 | ||
221 | @item TARGET_PAGE_SIZE | |
222 | If @code{SEGMENT_SIZE} is not defined, the @file{genscripts.sh} script | |
223 | uses this to define it. | |
224 | ||
225 | @item ALIGNMENT | |
226 | Some @file{scripttempl} scripts set this to a number to pass to | |
227 | @code{ALIGN} to set the required alignment for the @code{end} symbol. | |
228 | @end table | |
229 | ||
230 | @node linker scripts | |
231 | @section @file{scripttempl} scripts | |
232 | ||
233 | Each linker target uses a @file{scripttempl} script to generate the | |
234 | default linker scripts. The name of the @file{scripttempl} script is | |
235 | set by the @code{SCRIPT_NAME} variable in the @file{emulparams} script. | |
236 | If @code{SCRIPT_NAME} is set to @var{script}, @code{genscripts.sh} will | |
237 | invoke @file{scripttempl/@var{script}.sc}. | |
238 | ||
239 | The @file{genscripts.sh} script will invoke the @file{scripttempl} | |
e2a83dd0 | 240 | script 5 to 9 times. Each time it will set the shell variable |
252b5132 RH |
241 | @code{LD_FLAG} to a different value. When the linker is run, the |
242 | options used will direct it to select a particular script. (Script | |
243 | selection is controlled by the @code{get_script} emulation entry point; | |
244 | this describes the conventional behaviour). | |
245 | ||
246 | The @file{scripttempl} script should just write a linker script, written | |
247 | in the linker command language, to standard output. If the emulation | |
248 | name--the name of the @file{emulparams} file without the @file{.sc} | |
249 | extension--is @var{emul}, then the output will be directed to | |
250 | @file{ldscripts/@var{emul}.@var{extension}} in the build directory, | |
251 | where @var{extension} changes each time the @file{scripttempl} script is | |
252 | invoked. | |
253 | ||
254 | Here is the list of values assigned to @code{LD_FLAG}. | |
255 | ||
256 | @table @code | |
257 | @item (empty) | |
258 | The script generated is used by default (when none of the following | |
259 | cases apply). The output has an extension of @file{.x}. | |
260 | @item n | |
261 | The script generated is used when the linker is invoked with the | |
262 | @code{-n} option. The output has an extension of @file{.xn}. | |
263 | @item N | |
264 | The script generated is used when the linker is invoked with the | |
265 | @code{-N} option. The output has an extension of @file{.xbn}. | |
266 | @item r | |
267 | The script generated is used when the linker is invoked with the | |
268 | @code{-r} option. The output has an extension of @file{.xr}. | |
269 | @item u | |
270 | The script generated is used when the linker is invoked with the | |
271 | @code{-Ur} option. The output has an extension of @file{.xu}. | |
272 | @item shared | |
273 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
274 | this value if @code{GENERATE_SHLIB_SCRIPT} is defined in the | |
275 | @file{emulparams} file. The @file{emultempl} script must arrange to use | |
276 | this script at the appropriate time, normally when the linker is invoked | |
277 | with the @code{-shared} option. The output has an extension of | |
278 | @file{.xs}. | |
db6751f2 JJ |
279 | @item c |
280 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
281 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the | |
282 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf}. The | |
283 | @file{emultempl} script must arrange to use this script at the appropriate | |
284 | time, normally when the linker is invoked with the @code{-z combreloc} | |
285 | option. The output has an extension of | |
286 | @file{.xc}. | |
287 | @item cshared | |
288 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
289 | this value if @code{GENERATE_COMBRELOC_SCRIPT} is defined in the | |
290 | @file{emulparams} file or if @code{SCRIPT_NAME} is @code{elf} and | |
b45619c0 | 291 | @code{GENERATE_SHLIB_SCRIPT} is defined in the @file{emulparams} file. |
db6751f2 JJ |
292 | The @file{emultempl} script must arrange to use this script at the |
293 | appropriate time, normally when the linker is invoked with the @code{-shared | |
294 | -z combreloc} option. The output has an extension of @file{.xsc}. | |
e2a83dd0 NC |
295 | @item auto_import |
296 | The @file{scripttempl} script is only invoked with @code{LD_FLAG} set to | |
297 | this value if @code{GENERATE_AUTO_IMPORT_SCRIPT} is defined in the | |
298 | @file{emulparams} file. The @file{emultempl} script must arrange to | |
299 | use this script at the appropriate time, normally when the linker is | |
300 | invoked with the @code{--enable-auto-import} option. The output has | |
301 | an extension of @file{.xa}. | |
252b5132 RH |
302 | @end table |
303 | ||
304 | Besides the shell variables set by the @file{emulparams} script, and the | |
305 | @code{LD_FLAG} variable, the @file{genscripts.sh} script will set | |
306 | certain variables for each run of the @file{scripttempl} script. | |
307 | ||
308 | @table @code | |
309 | @item RELOCATING | |
310 | This will be set to a non-empty string when the linker is doing a final | |
311 | relocation (e.g., all scripts other than @code{-r} and @code{-Ur}). | |
312 | ||
313 | @item CONSTRUCTING | |
314 | This will be set to a non-empty string when the linker is building | |
315 | global constructor and destructor tables (e.g., all scripts other than | |
316 | @code{-r}). | |
317 | ||
318 | @item DATA_ALIGNMENT | |
319 | This will be set to an @code{ALIGN} expression when the output should be | |
320 | page aligned, or to @samp{.} when generating the @code{-N} script. | |
321 | ||
322 | @item CREATE_SHLIB | |
323 | This will be set to a non-empty string when generating a @code{-shared} | |
324 | script. | |
db6751f2 JJ |
325 | |
326 | @item COMBRELOC | |
327 | This will be set to a non-empty string when generating @code{-z combreloc} | |
328 | scripts to a temporary file name which can be used during script generation. | |
252b5132 RH |
329 | @end table |
330 | ||
331 | The conventional way to write a @file{scripttempl} script is to first | |
332 | set a few shell variables, and then write out a linker script using | |
333 | @code{cat} with a here document. The linker script will use variable | |
334 | substitutions, based on the above variables and those set in the | |
335 | @file{emulparams} script, to control its behaviour. | |
336 | ||
337 | When there are parts of the @file{scripttempl} script which should only | |
338 | be run when doing a final relocation, they should be enclosed within a | |
339 | variable substitution based on @code{RELOCATING}. For example, on many | |
340 | targets special symbols such as @code{_end} should be defined when doing | |
341 | a final link. Naturally, those symbols should not be defined when doing | |
1049f94e | 342 | a relocatable link using @code{-r}. The @file{scripttempl} script |
252b5132 RH |
343 | could use a construct like this to define those symbols: |
344 | @smallexample | |
345 | $@{RELOCATING+ _end = .;@} | |
346 | @end smallexample | |
347 | This will do the symbol assignment only if the @code{RELOCATING} | |
348 | variable is defined. | |
349 | ||
350 | The basic job of the linker script is to put the sections in the correct | |
351 | order, and at the correct memory addresses. For some targets, the | |
352 | linker script may have to do some other operations. | |
353 | ||
354 | For example, on most MIPS platforms, the linker is responsible for | |
355 | defining the special symbol @code{_gp}, used to initialize the | |
356 | @code{$gp} register. It must be set to the start of the small data | |
357 | section plus @code{0x8000}. Naturally, it should only be defined when | |
358 | doing a final relocation. This will typically be done like this: | |
359 | @smallexample | |
360 | $@{RELOCATING+ _gp = ALIGN(16) + 0x8000;@} | |
361 | @end smallexample | |
362 | This line would appear just before the sections which compose the small | |
363 | data section (@samp{.sdata}, @samp{.sbss}). All those sections would be | |
364 | contiguous in memory. | |
365 | ||
366 | Many COFF systems build constructor tables in the linker script. The | |
367 | compiler will arrange to output the address of each global constructor | |
368 | in a @samp{.ctor} section, and the address of each global destructor in | |
369 | a @samp{.dtor} section (this is done by defining | |
370 | @code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR} in the | |
371 | @code{gcc} configuration files). The @code{gcc} runtime support | |
372 | routines expect the constructor table to be named @code{__CTOR_LIST__}. | |
373 | They expect it to be a list of words, with the first word being the | |
374 | count of the number of entries. There should be a trailing zero word. | |
375 | (Actually, the count may be -1 if the trailing word is present, and the | |
376 | trailing word may be omitted if the count is correct, but, as the | |
377 | @code{gcc} behaviour has changed slightly over the years, it is safest | |
378 | to provide both). Here is a typical way that might be handled in a | |
379 | @file{scripttempl} file. | |
380 | @smallexample | |
381 | $@{CONSTRUCTING+ __CTOR_LIST__ = .;@} | |
382 | $@{CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)@} | |
383 | $@{CONSTRUCTING+ *(.ctors)@} | |
384 | $@{CONSTRUCTING+ LONG(0)@} | |
385 | $@{CONSTRUCTING+ __CTOR_END__ = .;@} | |
386 | $@{CONSTRUCTING+ __DTOR_LIST__ = .;@} | |
387 | $@{CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)@} | |
388 | $@{CONSTRUCTING+ *(.dtors)@} | |
389 | $@{CONSTRUCTING+ LONG(0)@} | |
390 | $@{CONSTRUCTING+ __DTOR_END__ = .;@} | |
391 | @end smallexample | |
392 | The use of @code{CONSTRUCTING} ensures that these linker script commands | |
393 | will only appear when the linker is supposed to be building the | |
394 | constructor and destructor tables. This example is written for a target | |
395 | which uses 4 byte pointers. | |
396 | ||
397 | Embedded systems often need to set a stack address. This is normally | |
398 | best done by using the @code{PROVIDE} construct with a default stack | |
399 | address. This permits the user to easily override the stack address | |
400 | using the @code{--defsym} option. Here is an example: | |
401 | @smallexample | |
402 | $@{RELOCATING+ PROVIDE (__stack = 0x80000000);@} | |
403 | @end smallexample | |
404 | The value of the symbol @code{__stack} would then be used in the startup | |
405 | code to initialize the stack pointer. | |
406 | ||
407 | @node linker emulations | |
408 | @section @file{emultempl} scripts | |
409 | ||
410 | Each linker target uses an @file{emultempl} script to generate the | |
411 | emulation code. The name of the @file{emultempl} script is set by the | |
412 | @code{TEMPLATE_NAME} variable in the @file{emulparams} script. If the | |
413 | @code{TEMPLATE_NAME} variable is not set, the default is | |
414 | @samp{generic}. If the value of @code{TEMPLATE_NAME} is @var{template}, | |
415 | @file{genscripts.sh} will use @file{emultempl/@var{template}.em}. | |
416 | ||
417 | Most targets use the generic @file{emultempl} script, | |
418 | @file{emultempl/generic.em}. A different @file{emultempl} script is | |
419 | only needed if the linker must support unusual actions, such as linking | |
420 | against shared libraries. | |
421 | ||
422 | The @file{emultempl} script is normally written as a simple invocation | |
423 | of @code{cat} with a here document. The document will use a few | |
424 | variable substitutions. Typically each function names uses a | |
425 | substitution involving @code{EMULATION_NAME}, for ease of debugging when | |
426 | the linker supports multiple emulations. | |
427 | ||
428 | Every function and variable in the emitted file should be static. The | |
429 | only globally visible object must be named | |
430 | @code{ld_@var{EMULATION_NAME}_emulation}, where @var{EMULATION_NAME} is | |
431 | the name of the emulation set in @file{configure.tgt} (this is also the | |
432 | name of the @file{emulparams} file without the @file{.sh} extension). | |
433 | The @file{genscripts.sh} script will set the shell variable | |
434 | @code{EMULATION_NAME} before invoking the @file{emultempl} script. | |
435 | ||
436 | The @code{ld_@var{EMULATION_NAME}_emulation} variable must be a | |
437 | @code{struct ld_emulation_xfer_struct}, as defined in @file{ldemul.h}. | |
438 | It defines a set of function pointers which are invoked by the linker, | |
439 | as well as strings for the emulation name (normally set from the shell | |
440 | variable @code{EMULATION_NAME} and the default BFD target name (normally | |
441 | set from the shell variable @code{OUTPUT_FORMAT} which is normally set | |
442 | by the @file{emulparams} file). | |
443 | ||
444 | The @file{genscripts.sh} script will set the shell variable | |
445 | @code{COMPILE_IN} when it invokes the @file{emultempl} script for the | |
446 | default emulation. In this case, the @file{emultempl} script should | |
447 | include the linker scripts directly, and return them from the | |
448 | @code{get_scripts} entry point. When the emulation is not the default, | |
449 | the @code{get_scripts} entry point should just return a file name. See | |
450 | @file{emultempl/generic.em} for an example of how this is done. | |
451 | ||
452 | At some point, the linker emulation entry points should be documented. | |
453 | ||
454 | @node Emulation Walkthrough | |
455 | @chapter A Walkthrough of a Typical Emulation | |
456 | ||
457 | This chapter is to help people who are new to the way emulations | |
458 | interact with the linker, or who are suddenly thrust into the position | |
459 | of having to work with existing emulations. It will discuss the files | |
460 | you need to be aware of. It will tell you when the given "hooks" in | |
461 | the emulation will be called. It will, hopefully, give you enough | |
462 | information about when and how things happen that you'll be able to | |
463 | get by. As always, the source is the definitive reference to this. | |
464 | ||
465 | The starting point for the linker is in @file{ldmain.c} where | |
466 | @code{main} is defined. The bulk of the code that's emulation | |
467 | specific will initially be in @code{emultempl/@var{emulation}.em} but | |
468 | will end up in @code{e@var{emulation}.c} when the build is done. | |
469 | Most of the work to select and interface with emulations is in | |
470 | @code{ldemul.h} and @code{ldemul.c}. Specifically, @code{ldemul.h} | |
471 | defines the @code{ld_emulation_xfer_struct} structure your emulation | |
472 | exports. | |
473 | ||
474 | Your emulation file exports a symbol | |
475 | @code{ld_@var{EMULATION_NAME}_emulation}. If your emulation is | |
476 | selected (it usually is, since usually there's only one), | |
477 | @code{ldemul.c} sets the variable @var{ld_emulation} to point to it. | |
478 | @code{ldemul.c} also defines a number of API functions that interface | |
479 | to your emulation, like @code{ldemul_after_parse} which simply calls | |
480 | your @code{ld_@var{EMULATION}_emulation.after_parse} function. For | |
481 | the rest of this section, the functions will be mentioned, but you | |
482 | should assume the indirect reference to your emulation also. | |
483 | ||
484 | We will also skip or gloss over parts of the link process that don't | |
485 | relate to emulations, like setting up internationalization. | |
486 | ||
487 | After initialization, @code{main} selects an emulation by pre-scanning | |
488 | the command line arguments. It calls @code{ldemul_choose_target} to | |
489 | choose a target. If you set @code{choose_target} to | |
490 | @code{ldemul_default_target}, it picks your @code{target_name} by | |
491 | default. | |
492 | ||
493 | @code{main} calls @code{ldemul_before_parse}, then @code{parse_args}. | |
494 | @code{parse_args} calls @code{ldemul_parse_args} for each arg, which | |
495 | must update the @code{getopt} globals if it recognizes the argument. | |
496 | If the emulation doesn't recognize it, then parse_args checks to see | |
497 | if it recognizes it. | |
498 | ||
499 | Now that the emulation has had access to all its command-line options, | |
500 | @code{main} calls @code{ldemul_set_symbols}. This can be used for any | |
501 | initialization that may be affected by options. It is also supposed | |
502 | to set up any variables needed by the emulation script. | |
503 | ||
504 | @code{main} now calls @code{ldemul_get_script} to get the emulation | |
505 | script to use (based on arguments, no doubt, @pxref{Emulations}) and | |
506 | runs it. While parsing, @code{ldgram.y} may call @code{ldemul_hll} or | |
507 | @code{ldemul_syslib} to handle the @code{HLL} or @code{SYSLIB} | |
508 | commands. It may call @code{ldemul_unrecognized_file} if you asked | |
509 | the linker to link a file it doesn't recognize. It will call | |
510 | @code{ldemul_recognized_file} for each file it does recognize, in case | |
511 | the emulation wants to handle some files specially. All the while, | |
512 | it's loading the files (possibly calling | |
513 | @code{ldemul_open_dynamic_archive}) and symbols and stuff. After it's | |
514 | done reading the script, @code{main} calls @code{ldemul_after_parse}. | |
515 | Use the after-parse hook to set up anything that depends on stuff the | |
516 | script might have set up, like the entry point. | |
517 | ||
518 | @code{main} next calls @code{lang_process} in @code{ldlang.c}. This | |
519 | appears to be the main core of the linking itself, as far as emulation | |
520 | hooks are concerned(*). It first opens the output file's BFD, calling | |
521 | @code{ldemul_set_output_arch}, and calls | |
522 | @code{ldemul_create_output_section_statements} in case you need to use | |
523 | other means to find or create object files (i.e. shared libraries | |
524 | found on a path, or fake stub objects). Despite the name, nobody | |
525 | creates output sections here. | |
526 | ||
527 | (*) In most cases, the BFD library does the bulk of the actual | |
528 | linking, handling symbol tables, symbol resolution, relocations, and | |
529 | building the final output file. See the BFD reference for all the | |
530 | details. Your emulation is usually concerned more with managing | |
531 | things at the file and section level, like "put this here, add this | |
532 | section", etc. | |
533 | ||
534 | Next, the objects to be linked are opened and BFDs created for them, | |
535 | and @code{ldemul_after_open} is called. At this point, you have all | |
536 | the objects and symbols loaded, but none of the data has been placed | |
537 | yet. | |
538 | ||
539 | Next comes the Big Linking Thingy (except for the parts BFD does). | |
540 | All input sections are mapped to output sections according to the | |
541 | script. If a section doesn't get mapped by default, | |
542 | @code{ldemul_place_orphan} will get called to figure out where it goes. | |
543 | Next it figures out the offsets for each section, calling | |
544 | @code{ldemul_before_allocation} before and | |
545 | @code{ldemul_after_allocation} after deciding where each input section | |
546 | ends up in the output sections. | |
547 | ||
548 | The last part of @code{lang_process} is to figure out all the symbols' | |
549 | values. After assigning final values to the symbols, | |
550 | @code{ldemul_finish} is called, and after that, any undefined symbols | |
551 | are turned into fatal errors. | |
552 | ||
553 | OK, back to @code{main}, which calls @code{ldwrite} in | |
554 | @file{ldwrite.c}. @code{ldwrite} calls BFD's final_link, which does | |
555 | all the relocation fixups and writes the output bfd to disk, and we're | |
556 | done. | |
557 | ||
558 | In summary, | |
559 | ||
560 | @itemize @bullet | |
561 | ||
562 | @item @code{main()} in @file{ldmain.c} | |
563 | @item @file{emultempl/@var{EMULATION}.em} has your code | |
564 | @item @code{ldemul_choose_target} (defaults to your @code{target_name}) | |
565 | @item @code{ldemul_before_parse} | |
566 | @item Parse argv, calls @code{ldemul_parse_args} for each | |
567 | @item @code{ldemul_set_symbols} | |
568 | @item @code{ldemul_get_script} | |
569 | @item parse script | |
570 | ||
571 | @itemize @bullet | |
572 | @item may call @code{ldemul_hll} or @code{ldemul_syslib} | |
573 | @item may call @code{ldemul_open_dynamic_archive} | |
574 | @end itemize | |
575 | ||
576 | @item @code{ldemul_after_parse} | |
577 | @item @code{lang_process()} in @file{ldlang.c} | |
578 | ||
579 | @itemize @bullet | |
580 | @item create @code{output_bfd} | |
581 | @item @code{ldemul_set_output_arch} | |
582 | @item @code{ldemul_create_output_section_statements} | |
583 | @item read objects, create input bfds - all symbols exist, but have no values | |
584 | @item may call @code{ldemul_unrecognized_file} | |
585 | @item will call @code{ldemul_recognized_file} | |
586 | @item @code{ldemul_after_open} | |
587 | @item map input sections to output sections | |
588 | @item may call @code{ldemul_place_orphan} for remaining sections | |
589 | @item @code{ldemul_before_allocation} | |
590 | @item gives input sections offsets into output sections, places output sections | |
591 | @item @code{ldemul_after_allocation} - section addresses valid | |
592 | @item assigns values to symbols | |
593 | @item @code{ldemul_finish} - symbol values valid | |
594 | @end itemize | |
595 | ||
596 | @item output bfd is written to disk | |
597 | ||
598 | @end itemize | |
599 | ||
b044cda1 CW |
600 | @node Architecture Specific |
601 | @chapter Some Architecture Specific Notes | |
602 | ||
603 | This is the place for notes on the behavior of @code{ld} on | |
604 | specific platforms. Currently, only Intel x86 is documented (and | |
605 | of that, only the auto-import behavior for DLLs). | |
606 | ||
607 | @menu | |
608 | * ix86:: Intel x86 | |
609 | @end menu | |
610 | ||
611 | @node ix86 | |
612 | @section Intel x86 | |
613 | ||
614 | @table @emph | |
615 | @code{ld} can create DLLs that operate with various runtimes available | |
616 | on a common x86 operating system. These runtimes include native (using | |
617 | the mingw "platform"), cygwin, and pw. | |
618 | ||
619 | @item auto-import from DLLs | |
620 | @enumerate | |
621 | @item | |
622 | With this feature on, DLL clients can import variables from DLL | |
623 | without any concern from their side (for example, without any source | |
624 | code modifications). Auto-import can be enabled using the | |
625 | @code{--enable-auto-import} flag, or disabled via the | |
626 | @code{--disable-auto-import} flag. Auto-import is disabled by default. | |
627 | ||
628 | @item | |
629 | This is done completely in bounds of the PE specification (to be fair, | |
630 | there's a minor violation of the spec at one point, but in practice | |
631 | auto-import works on all known variants of that common x86 operating | |
632 | system) So, the resulting DLL can be used with any other PE | |
633 | compiler/linker. | |
634 | ||
635 | @item | |
636 | Auto-import is fully compatible with standard import method, in which | |
637 | variables are decorated using attribute modifiers. Libraries of either | |
638 | type may be mixed together. | |
639 | ||
640 | @item | |
641 | Overhead (space): 8 bytes per imported symbol, plus 20 for each | |
642 | reference to it; Overhead (load time): negligible; Overhead | |
643 | (virtual/physical memory): should be less than effect of DLL | |
644 | relocation. | |
645 | @end enumerate | |
646 | ||
647 | Motivation | |
648 | ||
649 | The obvious and only way to get rid of dllimport insanity is | |
650 | to make client access variable directly in the DLL, bypassing | |
651 | the extra dereference imposed by ordinary DLL runtime linking. | |
b45619c0 | 652 | I.e., whenever client contains something like |
b044cda1 CW |
653 | |
654 | @code{mov dll_var,%eax,} | |
655 | ||
656 | address of dll_var in the command should be relocated to point | |
657 | into loaded DLL. The aim is to make OS loader do so, and than | |
658 | make ld help with that. Import section of PE made following | |
659 | way: there's a vector of structures each describing imports | |
660 | from particular DLL. Each such structure points to two other | |
b45619c0 | 661 | parallel vectors: one holding imported names, and one which |
b044cda1 CW |
662 | will hold address of corresponding imported name. So, the |
663 | solution is de-vectorize these structures, making import | |
664 | locations be sparse and pointing directly into code. | |
665 | ||
666 | Implementation | |
667 | ||
668 | For each reference of data symbol to be imported from DLL (to | |
669 | set of which belong symbols with name <sym>, if __imp_<sym> is | |
670 | found in implib), the import fixup entry is generated. That | |
671 | entry is of type IMAGE_IMPORT_DESCRIPTOR and stored in .idata$3 | |
672 | subsection. Each fixup entry contains pointer to symbol's address | |
673 | within .text section (marked with __fuN_<sym> symbol, where N is | |
674 | integer), pointer to DLL name (so, DLL name is referenced by | |
675 | multiple entries), and pointer to symbol name thunk. Symbol name | |
676 | thunk is singleton vector (__nm_th_<symbol>) pointing to | |
677 | IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing | |
678 | imported name. Here comes that "om the edge" problem mentioned above: | |
679 | PE specification rambles that name vector (OriginalFirstThunk) should | |
680 | run in parallel with addresses vector (FirstThunk), i.e. that they | |
681 | should have same number of elements and terminated with zero. We violate | |
682 | this, since FirstThunk points directly into machine code. But in | |
683 | practice, OS loader implemented the sane way: it goes thru | |
684 | OriginalFirstThunk and puts addresses to FirstThunk, not something | |
685 | else. It once again should be noted that dll and symbol name | |
686 | structures are reused across fixup entries and should be there | |
687 | anyway to support standard import stuff, so sustained overhead is | |
688 | 20 bytes per reference. Other question is whether having several | |
689 | IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. Answer is yes, | |
690 | it is done even by native compiler/linker (libth32's functions are in | |
691 | fact resident in windows9x kernel32.dll, so if you use it, you have | |
692 | two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is | |
693 | whether referencing the same PE structures several times is valid. | |
694 | The answer is why not, prohibiting that (detecting violation) would | |
695 | require more work on behalf of loader than not doing it. | |
696 | ||
697 | @end table | |
698 | ||
704c465c NC |
699 | @node GNU Free Documentation License |
700 | @chapter GNU Free Documentation License | |
701 | ||
702 | GNU Free Documentation License | |
703 | ||
704 | Version 1.1, March 2000 | |
705 | ||
706 | Copyright (C) 2000 Free Software Foundation, Inc. | |
75be928b | 707 | 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
704c465c NC |
708 | |
709 | Everyone is permitted to copy and distribute verbatim copies | |
710 | of this license document, but changing it is not allowed. | |
711 | ||
712 | ||
713 | 0. PREAMBLE | |
714 | ||
715 | The purpose of this License is to make a manual, textbook, or other | |
716 | written document "free" in the sense of freedom: to assure everyone | |
717 | the effective freedom to copy and redistribute it, with or without | |
718 | modifying it, either commercially or noncommercially. Secondarily, | |
719 | this License preserves for the author and publisher a way to get | |
720 | credit for their work, while not being considered responsible for | |
721 | modifications made by others. | |
722 | ||
723 | This License is a kind of "copyleft", which means that derivative | |
724 | works of the document must themselves be free in the same sense. It | |
725 | complements the GNU General Public License, which is a copyleft | |
726 | license designed for free software. | |
727 | ||
728 | We have designed this License in order to use it for manuals for free | |
729 | software, because free software needs free documentation: a free | |
730 | program should come with manuals providing the same freedoms that the | |
731 | software does. But this License is not limited to software manuals; | |
732 | it can be used for any textual work, regardless of subject matter or | |
733 | whether it is published as a printed book. We recommend this License | |
734 | principally for works whose purpose is instruction or reference. | |
735 | ||
736 | ||
737 | 1. APPLICABILITY AND DEFINITIONS | |
738 | ||
739 | This License applies to any manual or other work that contains a | |
740 | notice placed by the copyright holder saying it can be distributed | |
741 | under the terms of this License. The "Document", below, refers to any | |
742 | such manual or work. Any member of the public is a licensee, and is | |
743 | addressed as "you". | |
744 | ||
745 | A "Modified Version" of the Document means any work containing the | |
746 | Document or a portion of it, either copied verbatim, or with | |
747 | modifications and/or translated into another language. | |
748 | ||
749 | A "Secondary Section" is a named appendix or a front-matter section of | |
750 | the Document that deals exclusively with the relationship of the | |
751 | publishers or authors of the Document to the Document's overall subject | |
752 | (or to related matters) and contains nothing that could fall directly | |
753 | within that overall subject. (For example, if the Document is in part a | |
754 | textbook of mathematics, a Secondary Section may not explain any | |
755 | mathematics.) The relationship could be a matter of historical | |
756 | connection with the subject or with related matters, or of legal, | |
757 | commercial, philosophical, ethical or political position regarding | |
758 | them. | |
759 | ||
760 | The "Invariant Sections" are certain Secondary Sections whose titles | |
761 | are designated, as being those of Invariant Sections, in the notice | |
762 | that says that the Document is released under this License. | |
763 | ||
764 | The "Cover Texts" are certain short passages of text that are listed, | |
765 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
766 | the Document is released under this License. | |
767 | ||
768 | A "Transparent" copy of the Document means a machine-readable copy, | |
769 | represented in a format whose specification is available to the | |
770 | general public, whose contents can be viewed and edited directly and | |
771 | straightforwardly with generic text editors or (for images composed of | |
772 | pixels) generic paint programs or (for drawings) some widely available | |
773 | drawing editor, and that is suitable for input to text formatters or | |
774 | for automatic translation to a variety of formats suitable for input | |
775 | to text formatters. A copy made in an otherwise Transparent file | |
776 | format whose markup has been designed to thwart or discourage | |
777 | subsequent modification by readers is not Transparent. A copy that is | |
778 | not "Transparent" is called "Opaque". | |
779 | ||
780 | Examples of suitable formats for Transparent copies include plain | |
781 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
782 | or XML using a publicly available DTD, and standard-conforming simple | |
783 | HTML designed for human modification. Opaque formats include | |
784 | PostScript, PDF, proprietary formats that can be read and edited only | |
785 | by proprietary word processors, SGML or XML for which the DTD and/or | |
786 | processing tools are not generally available, and the | |
787 | machine-generated HTML produced by some word processors for output | |
788 | purposes only. | |
789 | ||
790 | The "Title Page" means, for a printed book, the title page itself, | |
791 | plus such following pages as are needed to hold, legibly, the material | |
792 | this License requires to appear in the title page. For works in | |
793 | formats which do not have any title page as such, "Title Page" means | |
794 | the text near the most prominent appearance of the work's title, | |
795 | preceding the beginning of the body of the text. | |
796 | ||
797 | ||
798 | 2. VERBATIM COPYING | |
799 | ||
800 | You may copy and distribute the Document in any medium, either | |
801 | commercially or noncommercially, provided that this License, the | |
802 | copyright notices, and the license notice saying this License applies | |
803 | to the Document are reproduced in all copies, and that you add no other | |
804 | conditions whatsoever to those of this License. You may not use | |
805 | technical measures to obstruct or control the reading or further | |
806 | copying of the copies you make or distribute. However, you may accept | |
807 | compensation in exchange for copies. If you distribute a large enough | |
808 | number of copies you must also follow the conditions in section 3. | |
809 | ||
810 | You may also lend copies, under the same conditions stated above, and | |
811 | you may publicly display copies. | |
812 | ||
813 | ||
814 | 3. COPYING IN QUANTITY | |
815 | ||
816 | If you publish printed copies of the Document numbering more than 100, | |
817 | and the Document's license notice requires Cover Texts, you must enclose | |
818 | the copies in covers that carry, clearly and legibly, all these Cover | |
819 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
820 | the back cover. Both covers must also clearly and legibly identify | |
821 | you as the publisher of these copies. The front cover must present | |
822 | the full title with all words of the title equally prominent and | |
823 | visible. You may add other material on the covers in addition. | |
824 | Copying with changes limited to the covers, as long as they preserve | |
825 | the title of the Document and satisfy these conditions, can be treated | |
826 | as verbatim copying in other respects. | |
827 | ||
828 | If the required texts for either cover are too voluminous to fit | |
829 | legibly, you should put the first ones listed (as many as fit | |
830 | reasonably) on the actual cover, and continue the rest onto adjacent | |
831 | pages. | |
832 | ||
833 | If you publish or distribute Opaque copies of the Document numbering | |
834 | more than 100, you must either include a machine-readable Transparent | |
835 | copy along with each Opaque copy, or state in or with each Opaque copy | |
836 | a publicly-accessible computer-network location containing a complete | |
837 | Transparent copy of the Document, free of added material, which the | |
838 | general network-using public has access to download anonymously at no | |
839 | charge using public-standard network protocols. If you use the latter | |
840 | option, you must take reasonably prudent steps, when you begin | |
841 | distribution of Opaque copies in quantity, to ensure that this | |
842 | Transparent copy will remain thus accessible at the stated location | |
843 | until at least one year after the last time you distribute an Opaque | |
844 | copy (directly or through your agents or retailers) of that edition to | |
845 | the public. | |
846 | ||
847 | It is requested, but not required, that you contact the authors of the | |
848 | Document well before redistributing any large number of copies, to give | |
849 | them a chance to provide you with an updated version of the Document. | |
850 | ||
851 | ||
852 | 4. MODIFICATIONS | |
853 | ||
854 | You may copy and distribute a Modified Version of the Document under | |
855 | the conditions of sections 2 and 3 above, provided that you release | |
856 | the Modified Version under precisely this License, with the Modified | |
857 | Version filling the role of the Document, thus licensing distribution | |
858 | and modification of the Modified Version to whoever possesses a copy | |
859 | of it. In addition, you must do these things in the Modified Version: | |
860 | ||
861 | A. Use in the Title Page (and on the covers, if any) a title distinct | |
862 | from that of the Document, and from those of previous versions | |
863 | (which should, if there were any, be listed in the History section | |
864 | of the Document). You may use the same title as a previous version | |
865 | if the original publisher of that version gives permission. | |
866 | B. List on the Title Page, as authors, one or more persons or entities | |
867 | responsible for authorship of the modifications in the Modified | |
868 | Version, together with at least five of the principal authors of the | |
869 | Document (all of its principal authors, if it has less than five). | |
870 | C. State on the Title page the name of the publisher of the | |
871 | Modified Version, as the publisher. | |
872 | D. Preserve all the copyright notices of the Document. | |
873 | E. Add an appropriate copyright notice for your modifications | |
874 | adjacent to the other copyright notices. | |
875 | F. Include, immediately after the copyright notices, a license notice | |
876 | giving the public permission to use the Modified Version under the | |
877 | terms of this License, in the form shown in the Addendum below. | |
878 | G. Preserve in that license notice the full lists of Invariant Sections | |
879 | and required Cover Texts given in the Document's license notice. | |
880 | H. Include an unaltered copy of this License. | |
881 | I. Preserve the section entitled "History", and its title, and add to | |
882 | it an item stating at least the title, year, new authors, and | |
883 | publisher of the Modified Version as given on the Title Page. If | |
884 | there is no section entitled "History" in the Document, create one | |
885 | stating the title, year, authors, and publisher of the Document as | |
886 | given on its Title Page, then add an item describing the Modified | |
887 | Version as stated in the previous sentence. | |
888 | J. Preserve the network location, if any, given in the Document for | |
889 | public access to a Transparent copy of the Document, and likewise | |
890 | the network locations given in the Document for previous versions | |
891 | it was based on. These may be placed in the "History" section. | |
892 | You may omit a network location for a work that was published at | |
893 | least four years before the Document itself, or if the original | |
894 | publisher of the version it refers to gives permission. | |
895 | K. In any section entitled "Acknowledgements" or "Dedications", | |
896 | preserve the section's title, and preserve in the section all the | |
897 | substance and tone of each of the contributor acknowledgements | |
898 | and/or dedications given therein. | |
899 | L. Preserve all the Invariant Sections of the Document, | |
900 | unaltered in their text and in their titles. Section numbers | |
901 | or the equivalent are not considered part of the section titles. | |
902 | M. Delete any section entitled "Endorsements". Such a section | |
903 | may not be included in the Modified Version. | |
904 | N. Do not retitle any existing section as "Endorsements" | |
905 | or to conflict in title with any Invariant Section. | |
906 | ||
907 | If the Modified Version includes new front-matter sections or | |
908 | appendices that qualify as Secondary Sections and contain no material | |
909 | copied from the Document, you may at your option designate some or all | |
910 | of these sections as invariant. To do this, add their titles to the | |
911 | list of Invariant Sections in the Modified Version's license notice. | |
912 | These titles must be distinct from any other section titles. | |
913 | ||
914 | You may add a section entitled "Endorsements", provided it contains | |
915 | nothing but endorsements of your Modified Version by various | |
916 | parties--for example, statements of peer review or that the text has | |
917 | been approved by an organization as the authoritative definition of a | |
918 | standard. | |
919 | ||
920 | You may add a passage of up to five words as a Front-Cover Text, and a | |
921 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
922 | of Cover Texts in the Modified Version. Only one passage of | |
923 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
924 | through arrangements made by) any one entity. If the Document already | |
925 | includes a cover text for the same cover, previously added by you or | |
926 | by arrangement made by the same entity you are acting on behalf of, | |
927 | you may not add another; but you may replace the old one, on explicit | |
928 | permission from the previous publisher that added the old one. | |
929 | ||
930 | The author(s) and publisher(s) of the Document do not by this License | |
931 | give permission to use their names for publicity for or to assert or | |
932 | imply endorsement of any Modified Version. | |
933 | ||
934 | ||
935 | 5. COMBINING DOCUMENTS | |
936 | ||
937 | You may combine the Document with other documents released under this | |
938 | License, under the terms defined in section 4 above for modified | |
939 | versions, provided that you include in the combination all of the | |
940 | Invariant Sections of all of the original documents, unmodified, and | |
941 | list them all as Invariant Sections of your combined work in its | |
942 | license notice. | |
943 | ||
944 | The combined work need only contain one copy of this License, and | |
945 | multiple identical Invariant Sections may be replaced with a single | |
946 | copy. If there are multiple Invariant Sections with the same name but | |
947 | different contents, make the title of each such section unique by | |
948 | adding at the end of it, in parentheses, the name of the original | |
949 | author or publisher of that section if known, or else a unique number. | |
950 | Make the same adjustment to the section titles in the list of | |
951 | Invariant Sections in the license notice of the combined work. | |
952 | ||
953 | In the combination, you must combine any sections entitled "History" | |
954 | in the various original documents, forming one section entitled | |
955 | "History"; likewise combine any sections entitled "Acknowledgements", | |
956 | and any sections entitled "Dedications". You must delete all sections | |
957 | entitled "Endorsements." | |
958 | ||
959 | ||
960 | 6. COLLECTIONS OF DOCUMENTS | |
961 | ||
962 | You may make a collection consisting of the Document and other documents | |
963 | released under this License, and replace the individual copies of this | |
964 | License in the various documents with a single copy that is included in | |
965 | the collection, provided that you follow the rules of this License for | |
966 | verbatim copying of each of the documents in all other respects. | |
967 | ||
968 | You may extract a single document from such a collection, and distribute | |
969 | it individually under this License, provided you insert a copy of this | |
970 | License into the extracted document, and follow this License in all | |
971 | other respects regarding verbatim copying of that document. | |
972 | ||
973 | ||
974 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
975 | ||
976 | A compilation of the Document or its derivatives with other separate | |
977 | and independent documents or works, in or on a volume of a storage or | |
978 | distribution medium, does not as a whole count as a Modified Version | |
979 | of the Document, provided no compilation copyright is claimed for the | |
980 | compilation. Such a compilation is called an "aggregate", and this | |
981 | License does not apply to the other self-contained works thus compiled | |
982 | with the Document, on account of their being thus compiled, if they | |
983 | are not themselves derivative works of the Document. | |
984 | ||
985 | If the Cover Text requirement of section 3 is applicable to these | |
986 | copies of the Document, then if the Document is less than one quarter | |
987 | of the entire aggregate, the Document's Cover Texts may be placed on | |
988 | covers that surround only the Document within the aggregate. | |
989 | Otherwise they must appear on covers around the whole aggregate. | |
990 | ||
991 | ||
992 | 8. TRANSLATION | |
993 | ||
994 | Translation is considered a kind of modification, so you may | |
995 | distribute translations of the Document under the terms of section 4. | |
996 | Replacing Invariant Sections with translations requires special | |
997 | permission from their copyright holders, but you may include | |
998 | translations of some or all Invariant Sections in addition to the | |
999 | original versions of these Invariant Sections. You may include a | |
1000 | translation of this License provided that you also include the | |
1001 | original English version of this License. In case of a disagreement | |
1002 | between the translation and the original English version of this | |
1003 | License, the original English version will prevail. | |
1004 | ||
1005 | ||
1006 | 9. TERMINATION | |
1007 | ||
1008 | You may not copy, modify, sublicense, or distribute the Document except | |
1009 | as expressly provided for under this License. Any other attempt to | |
1010 | copy, modify, sublicense or distribute the Document is void, and will | |
1011 | automatically terminate your rights under this License. However, | |
1012 | parties who have received copies, or rights, from you under this | |
1013 | License will not have their licenses terminated so long as such | |
1014 | parties remain in full compliance. | |
1015 | ||
1016 | ||
1017 | 10. FUTURE REVISIONS OF THIS LICENSE | |
1018 | ||
1019 | The Free Software Foundation may publish new, revised versions | |
1020 | of the GNU Free Documentation License from time to time. Such new | |
1021 | versions will be similar in spirit to the present version, but may | |
1022 | differ in detail to address new problems or concerns. See | |
1023 | http://www.gnu.org/copyleft/. | |
1024 | ||
1025 | Each version of the License is given a distinguishing version number. | |
1026 | If the Document specifies that a particular numbered version of this | |
1027 | License "or any later version" applies to it, you have the option of | |
1028 | following the terms and conditions either of that specified version or | |
1029 | of any later version that has been published (not as a draft) by the | |
1030 | Free Software Foundation. If the Document does not specify a version | |
1031 | number of this License, you may choose any version ever published (not | |
1032 | as a draft) by the Free Software Foundation. | |
1033 | ||
1034 | ||
1035 | ADDENDUM: How to use this License for your documents | |
1036 | ||
1037 | To use this License in a document you have written, include a copy of | |
1038 | the License in the document and put the following copyright and | |
1039 | license notices just after the title page: | |
1040 | ||
1041 | @smallexample | |
1042 | Copyright (c) YEAR YOUR NAME. | |
1043 | Permission is granted to copy, distribute and/or modify this document | |
1044 | under the terms of the GNU Free Documentation License, Version 1.1 | |
1045 | or any later version published by the Free Software Foundation; | |
1046 | with the Invariant Sections being LIST THEIR TITLES, with the | |
1047 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
1048 | A copy of the license is included in the section entitled "GNU | |
1049 | Free Documentation License". | |
1050 | @end smallexample | |
1051 | ||
1052 | If you have no Invariant Sections, write "with no Invariant Sections" | |
1053 | instead of saying which ones are invariant. If you have no | |
1054 | Front-Cover Texts, write "no Front-Cover Texts" instead of | |
1055 | "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
1056 | ||
1057 | If your document contains nontrivial examples of program code, we | |
1058 | recommend releasing these examples in parallel under your choice of | |
1059 | free software license, such as the GNU General Public License, | |
1060 | to permit their use in free software. | |
1061 | ||
252b5132 RH |
1062 | @contents |
1063 | @bye |