Subversion Repositories tendra.SVN

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 7u83 1 
<!-- Crown Copyright (c) 1998 -->
2 
<HTML>
3 
<HEAD>
4 
<TITLE>
5 
TDF Linker
6 
</TITLE>
7 
</HEAD>
8 
 
9 
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#400080" ALINK="#FF0000">
10 
 
11 
<H1>The TDF Linker</H1>
12 
<H3>January 1998</H3>
13 
<IMG SRC="../images/no_next.gif" ALT="next section">
14 
<IMG SRC="../images/no_prev.gif" ALT="previous section">
15 
<IMG SRC="../images/no_top.gif" ALT="current document">
16 
<A HREF="../index.html"><IMG SRC="../images/home.gif" ALT="TenDRA home page">
17 
</A>
18 
<IMG SRC="../images/no_index.gif" ALT="document index"><P>
19 
 
20 
<HR>
21 
<DL>
22 
<DT><A HREF="#S1"><B>1</B> - Introduction</A><DD>
23 
<DT><A HREF="#S2"><B>2</B> - Basic TDF structures</A><DD>
24 
<DT><A HREF="#S3"><B>3</B> - Structure of a TDF Capsule</A><DD>
25 
<DT><A HREF="#S4"><B>4</B> - Linker information unit groups</A><DD>
26 
<DT><A HREF="#S5"><B>5</B> - Structure of a TDF library</A><DD>
27 
<DT><A HREF="#S6"><B>6</B> - Purpose</A><DD>
28 
<DT><A HREF="#S7"><B>7</B> - TDF Linking</A><DD>
29 
<DL>
30 
<DT><A HREF="#S71"><B>7.1</B> - Basic linking</A><DD>
31 
<DT><A HREF="#S72"><B>7.2</B> - Renaming</A><DD>
32 
<DT><A HREF="#S73"><B>7.3</B> - Library capsules</A><DD>
33 
<DT><A HREF="#S74"><B>7.4</B> - Hiding</A><DD>
34 
<DT><A HREF="#S75"><B>7.5</B> - Writing out the capsule</A><DD>
35 
</DL>
36 
<DT><A HREF="#S8"><B>8</B> - Constructing TDF Libraries</A><DD>
37 
</DL>
38 
<HR>
39 
<H2><A NAME=S1>1. Introduction</A></H2>
40 
<P>
41 
This document describes the formats of the files used by the TDF linker
42 
and the linker's required behaviour.  There are two file formats:
43 
the capsule format and the library format.  It also describes the
44 
format of the linker information units within capsules.  The capsule
45 
format is described in more detail in the TDF specification.
46 
<P>
47 
<HR>
48 
<H2><A NAME=S2>2. Basic TDF structures</A></H2>
49 
<P>
50 
The structure of a TDF capsule is defined properly in the TDF specification.
51 
This section describes the basic components of the TDF format that
52 
the linker uses, and the remaining sections describe the format of
53 
a TDF capsule, a TDF library and a linker information unit in terms
54 
of these components.  The basic components are:
55 
<DL>
56 
<DT><CODE>ALIGN</CODE><DD> This is a byte alignment.  It forces the
57 
next object to begin on an eight bit boundary.<P>
58 
<DT><CODE>TDFINT</CODE><DD> This is an unsigned number of unbounded
59 
size.  Its representation is described properly in the TDF specification.
60 
It is a series of nibbles (four bits), with the high bit used as a
61 
terminator and the low three bits used as an octal digit.  The terminator
62 
bit is set on the final octal digit.  As an example, the number ten
63 
would be represented (in binary) as: 0001 1010.<P>
64 
<DT><CODE>BYTE</CODE><DD>This is an eight bit quantity.  <CODE>BYTE</CODE>s
65 
are always aligned on an eight bit boundary.<P>
66 
<DT><CODE>TDFIDENT</CODE><DD>A <CODE>TDFIDENT</CODE> is a sequence
67 
of characters.  It is possible to change the size of the characters,
68 
although the current implementation will produce an error for <CODE>TDFIDENT
69 
</CODE>s with character sizes other than eight bits.  A <CODE>TDFIDENT</CODE>
70 
is represented by two <CODE>TDFINT</CODE>s (the size of the characters
71 
in bits and the number of characters in the <CODE>TDFIDENT</CODE>),
72 
and a sequence of <CODE>BYTE</CODE>s.<P>
73 
<DT><CODE>UNIQUE</CODE><DD>A <CODE>UNIQUE</CODE> is a list of <CODE>TDFIDENT
74 
</CODE>s.  It is represented as a
75 
<CODE>TDFINT</CODE> specifying the number of <CODE>TDFIDENT</CODE>s
76 
in the <CODE>UNIQUE</CODE>, followed by that many <CODE>TDFIDENT</CODE>s.<P>
77 
<DT><CODE>EXTERNAL</CODE><DD>An <CODE>EXTERNAL</CODE> is a mechanism
78 
for identifying external identifiers.  It is represented as a discriminating
79 
tag, followed by a byte alignment, followed by either a <CODE>TDFIDENT</CODE>
80 
or a <CODE>UNIQUE</CODE>.  The tag is a two bit number, where one
81 
represents a <CODE>TDFIDENT</CODE>, two represents a
82 
<CODE>UNIQUE</CODE>, and zero and three are currently illegal.  <CODE>UNIQUE
83 
</CODE>s are only used as part of an <CODE>EXTERNAL</CODE>; <CODE>TDFIDENT
84 
</CODE>s are used as entities in their own right, as well as in <CODE>EXTERNAL
85 
</CODE>s.
86 
</DL>
87 
<P>
88 
In the following descriptions, the syntax <I>name: type</I> is used
89 
to specify an object in the structure.  The <I>name</I> is used to
90 
describe the purpose of the object; the <I>type</I> is used to describe
91 
what the object is.  A <I>type</I> is one of the following:
92 
<DL>
93 
<DT><I>basic_type</I><DD>This represents one of the basic types listed
94 
above.<P>
95 
<DT><I>type</I> * <I>integer</I><DD>This represents a sequence of
96 
objects of the specified   type.  The <I>integer</I> may be either
97 
an integer literal, or a   name that has been previously mentioned
98 
and is a <CODE>TDFINT</CODE>
99 
object.<P>
100 
<DT>{ <I>name1</I>: <I>type1</I> ... <I>nameN</I>: <I>typeN</I> }<DD>This
101 
represents a structure composed of the elements   <I>name1: type1</I>
102 
to <I>nameN: typeN</I>.  It is used for   sequences of objects where
103 
the objects are not of basic   types.<P>
104 
<DT><I>type</I> = ( <I>value1</I> | ... | <I>valueN</I> )<DD>This
105 
represents a type with a constraint imposed upon it.   The object
106 
value must be one of <I>value1</I> to <I>valueN</I>.
107 
</DL>
108 
<P>
109 
<HR>
110 
<H2><A NAME=S3>3. Structure of a TDF Capsule</A></H2>
111 
<P>
112 
A TDF capsule has the following structure:
113 
<PRE>
114 
    magic				BYTE * 4 = &quot;TDFC&quot;
115 
    major_version			TDFINT
116 
    minor_version			TDFINT
117 
					ALIGN
118 
    num_prop_names:			TDFINT
119 
    prop_names:				TDFIDENT * num_prop_names
120 
    num_linkable_entities:		TDFINT
121 
    linkable_entities: {
122 
	name:				TDFIDENT
123 
	num_capsule_scope_identifiers:	TDFINT
124 
    } * num_linkable_entities
125 
    num_external_linkages:		TDFINT = num_linkable_entities
126 
    external_linkages: {
127 
	num_entries:			TDFINT
128 
	entries: {
129 
	    capsule_scope_id:		TDFINT
130 
	    external_name:		EXTERNAL
131 
	} * num_entries
132 
    } * num_external_linkages
133 
    num_unit_groups:			TDFINT = num_prop_names
134 
    unit_groups: {
135 
	num_units:			TDFINT
136 
	units: {
137 
	    num_counts:			TDFINT = (num_linkable_entities | 0)
138 
	    counts:			TDFINT * num_counts
139 
	    num_link_sets:		TDFINT = num_counts
140 
	    link_sets: {
141 
		num_links:		TDFINT
142 
		links: {
143 
		    internal:		TDFINT
144 
		    external:		TDFINT
145 
		} * num_links
146 
	    } * num_link_sets
147 
	    num_bytes_tdf:		TDFINT
148 
	    tdf:			BYTE * num_bytes_tdf
149 
	} * num_units
150 
    } * num_unit_groups
151 
</PRE>
152 
The rest of this section describes the format of a capsule.
153 
<P>
154 
The capsule begins with a header that contains a four byte magic number
155 
(<I>magic</I>: &quot;TDFC&quot;), followed by the major (<I>major_version</I>)
156 
and minor (<I>minor_version</I>) version numbers of the TDF in the
157 
capsule.  This is then followed by a byte alignment and then the the
158 
capsule body.
159 
<P>
160 
The first part of a capsule tells the linker how many types of unit
161 
groups there are in the capsule (<I>num_prop_names</I>), and what
162 
the names of these unit group types are (<I>prop_names</I>).  There
163 
can be many unit group types, but the linker must know what they are
164 
called, and the order in which they should occur.  At present the
165 
linker knows about <I>tld</I>, <I>tld2</I>, <I>versions</I>,
166 
<I>tokdec</I>, <I>tokdef</I>, <I>aldef</I>, <I>diagtype</I>, <I>tagdec</I>,
167 
<I>diagdef</I>, <I>tagdef</I> and
168 
<I>linkinfo</I> (this can be changed from the command line).  There
169 
is nothing special about any unit group type except for the <I>tld</I>
170 
unit group type, which contains information that the linker uses (and
171 
the <I>tld2</I> unit group type, which is obsolete, but is treated
172 
as a special case of the <I>tld</I> unit group type).  The format
173 
of the <I>tld</I> unit group type is described in a later section.
174 
<P>
175 
The second part of the capsule tells the linker how many linkable
176 
entities it should be linking on (<I>num_linkable_entities</I>), the
177 
name of each linkable entity (<I>name</I>), and the number of identifiers
178 
of each linkable entity at capsule scope (<I>num_capsule_scope_identifiers</I>).
179 
Identifiers at capsule scope should be numbers from zero to one less
180 
than
181 
<I>num_capsule_scope_identifiers</I>.  The identifier allocation may
182 
be sparse, but the linker is optimized for continuous identifier allocation.
183 
<P>
184 
The third part of the capsule tells the linker which external names
185 
the capsule contains for each linkable entity.  For each linkable
186 
entity listed in the second part, the number of external names of
187 
that linkable entity are listed in this part (<I>num_entries</I>),
188 
along with each of the external names (<I>external_name</I>) and the
189 
corresponding capsule scope identifiers (<I>capsule_scope_id</I>).
190 
The ordering of the linkable entities in part three must be identical
191 
to the ordering of linkable entities in part two.
192 
<P>
193 
The fourth and final part of the capsule contains the unit groups
194 
themselves.  The unit groups occur in the same order as the unit group
195 
types were listed in part one.  For each unit group, there is a <CODE>TDFINT
196 
</CODE> specifying the number of units in that unit group (<I>num_units</I>),
197 
followed by that many units.
198 
<P>
199 
Each unit contains a list of counts (<I>counts</I>) and the number
200 
of counts in that list (<I>num_counts</I>), which must be either zero
201 
or the same as the number of linkable entities in the capsule (<I>num_linkable_entities
202 
</I>). Each count contains the number of unit scope identifiers of
203 
the given linkable entity in the unit.  If the number of counts is
204 
non-zero, then the counts must be in the same order as the linkable
205 
entity names.
206 
<P>
207 
After the counts come the unit scope identifier to capsule scope identifier
208 
mapping tables.  The number of these tables is specified by
209 
<I>num_link_sets</I> and must be the same as the number of counts
210 
(<I>num_counts</I>), which is either zero or the same as the number
211 
of linkable entities in the capsule.  There is one table for each
212 
linkable entity (if
213 
<I>num_link_sets</I> is non-zero), and each table contains <I>num_links</I>
214 
pairs of <CODE>TDFINT</CODE>s.  The <I>internal</I> <CODE>TDFINT</CODE>
215 
is the unit scope identifier; the
216 
<I>external</I> <CODE>TDFINT</CODE> is the capsule scope identifier.
217 
<P>
218 
After the mapping tables there is a length (<I>num_bytes_tdf</I>),
219 
and that many bytes of TDF data (<I>tdf</I>).
220 
<P>
221 
<HR>
222 
<H2><A NAME=S4>4. Linker information unit groups</A></H2>
223 
<P>
224 
The <I>tld</I> unit group (if it exists in the capsule) should contain
225 
one unit only.  This unit should begin with two zeroes (i.e. no counts,
226 
and no identifier mapping tables), a length (which must be correct),
227 
and a sequence of bytes.
228 
<P>
229 
The bytes encode information useful to the linker.  The first thing
230 
in the byte sequence of a <I>tld</I> unit is a <CODE>TDFINT</CODE>
231 
that is the type of the unit. What follows depends upon the type.
232 
There are currently two types that are supported: zero and one.  Type
233 
zero units contain the same information as the old <I>tld2</I> units
234 
(if a <I>tld2</I> unit is read, it is treated as if it were a <I>tld</I>
235 
unit that began with a type of zero; it is illegal for a capsule to
236 
contain both a <I>tld</I> unit group and a <I>tld2</I> unit group).
237 
Type one units contain more information (described below), and are
238 
what the linker writes out in the generated capsule.
239 
<P>
240 
A version one unit contains a sequence of <CODE>TDFINT</CODE>s.  There
241 
is one <CODE>TDFINT</CODE> for each external name in part two of the
242 
capsule.  These <CODE>TDFINT</CODE>s should be in the same order as
243 
the external names were.  The <CODE>TDFINT</CODE>s are treated as
244 
a sequence of bits, with the following meanings:
245 
<BLOCKQUOTE>
246 
<P>0 =  The name is used within this capsule.
247 
<P>1 =  The name is declared within this capsule.
248 
<P>2 =  The name is uniquely defined within this capsule.   If this
249 
bit is set for a tag, then the declared bit   must also be set (i.e.
250 
a declaration must exist).
251 
<P>3 =  The name is defined in this capsule, but may have   other
252 
definitions provided by other capsules.  This   bit may not be set
253 
for tokens.  If a tag has this   bit set, then the declared bit must
254 
also be set   (i.e. a declaration must exist).
255 
</BLOCKQUOTE>
256 
<P>
257 
All of the other bits in the <CODE>TDFINT</CODE> are reserved.  The
258 
linker uses the information provided by this unit to check that names
259 
do not have multiple unique definitions, and to decide whether libraries
260 
should be consulted to provide a definition for an external name.
261 
If a capsule contains no linker information unit group, then the external
262 
names in that capsule will have no information, and hence these checks
263 
will not be made.  A similar situation arises when the information
264 
for a name has no bits set.
265 
<P>
266 
A version zero unit contains a sequence of <CODE>TDFINT</CODE>s.
267 
There is one <CODE>TDFINT</CODE>
268 
for each external token name, and one <CODE>TDFINT</CODE> for each
269 
external tag name. These <CODE>TDFINT</CODE>s should be in the same
270 
order as the external names were (but the tokens always come before
271 
the tags).  The <CODE>TDFINT</CODE>s are treated as a sequence of
272 
bits, with the same meanings as above.
273 
<P>
274 
<HR>
275 
<H2><A NAME=S5>5. Structure of a TDF library</A></H2>
276 
<P>
277 
A TDF library begins with a header, followed by a <CODE>TDFINT</CODE>,
278 
that is the type of the library.  At present only type zero libraries
279 
are supported.  The format of a type zero library is as follows:
280 
<PRE>
281 
    magic:				BYTE * 4 = &quot;TDFL&quot;
282 
    major_version:			TDFINT
283 
    minor_version:			TDFINT
284 
					ALIGN
285 
    type:				TDFINT = 0
286 
    num_capsules:			TDFINT
287 
    capsules: {
288 
	capsule_name:			TDFIDENT
289 
	capsule_length:			TDFINT
290 
	capsule_body:			BYTE * capsule_length
291 
    } * num_capsules
292 
    num_linkable_entities:		TDFINT
293 
    linkable_entities: {
294 
	linkable_entity_name:		TDFIDENT
295 
	num_this_linkable_entity:	TDFINT
296 
	this_linkable_entity_names: {
297 
	    name:			EXTERNAL
298 
	    info:			TDFINT
299 
	    capsule:			TDFINT
300 
        } * num_this_linkable_entity
301 
    } * num_linkable_entities
302 
</PRE>
303 
The library begins with a four byte magic number (<I>magic</I>: &quot;TDFL&quot;),
304 
followed by the major (<I>major_version</I>) and minor (<I>minor_version</I>)
305 
versions of the TDF in the library (the major version must be the
306 
same for each capsule in the library; the minor version is the highest
307 
of the minor version numbers of all of the the capsules contained
308 
in the library).  This is followed by a byte alignment, the type of
309 
the library (<I>type</I>: 0), and the number of capsules in the library
310 
(<I>num_capsules</I>), followed by that many capsules.
311 
<P>
312 
Each of the <I>capsules</I> has a name (<I>capsule_name</I>), and
313 
the capsule content, which consists of the length of the capsule (<I>capsule_length
314 
</I>) and that many bytes (<I>capsule_body</I>).  The capsule name
315 
is the name of the file from which the capsule was obtained when the
316 
library was built.  The names of capsules within a library must all
317 
be different.
318 
<P>
319 
The library is terminated by the index.  This contains information
320 
about where to find definitions for external names.  The index begins
321 
with the number of linkable entities whose external names the library
322 
will provide definitions for (<I>num_linkable_entities</I>).
323 
<P>
324 
For each of these linkable entities, the linkable entity index begins
325 
with the name of the linkable entity (<I>linkable_entity_name</I>),
326 
followed by the number of external names of the linkable entity that
327 
have entries in the index (<I>num_this_linkable_entity</I>).  This
328 
is followed by the index information for each of the names.
329 
<P>
330 
For each name, the index contains the name (<I>name</I>); a <CODE>TDFINT</CODE>
331 
that provides information about the name (<I>info</I>) with the same
332 
meaning as the
333 
<CODE>TDFINT</CODE>s in the linker information units; and the index
334 
of the capsule that contains the definition for the name (<I>capsule</I>).
335 
The index of the first capsule is zero.
336 
<P>
337 
<HR>
338 
<H2><A NAME=S6>6. Purpose</A></H2>
339 
<P>
340 
The TDF linker has four uses:
341 
<UL>
342 
<LI>To bind together a number of TDF capsules (including those in
343 
libraries) to produce a single capsule.<P>
344 
<LI>To produce a TDF library from a set of capsules.<P>
345 
<LI>To list the contents of a TDF library.<P>
346 
<LI>To extract capsules from a TDF library.
347 
</UL>
348 
The most complex part of the linker is the normal linking process,
349 
which is described in the next section.  Constructing libraries is
350 
described in the section after the one on linking.  Listing the contents
351 
of a library, and extracting capsules from a library are not very
352 
complicated so they aren't described in this document.
353 
<P>
354 
<HR>
355 
<H2><A NAME=S7>7. TDF Linking</A></H2>
356 
<P>
357 
This section describes the requirements of linking capsules together.
358 
The first sub-section describes the basic linking requirements.  Subsequent
359 
sub-sections detail the requirements of some more advanced features.
360 
<P>
361 
Before the linking process is described in detail, here is an outline
362 
of the stages of the link process:
363 
<BLOCKQUOTE>
364 
<P>
365 
The linker is invoked with the following inputs: a set of input
366 
capsules, a set of libraries, a set of hiding rules, a set of keeping
367 
rules, a set of renaming rules, and a set of link suppression rules.
368 
<P>
369 
The first thing that the linker does is to enter the renaming rules
370 
into the name hash table.  The name entry lookup routines will automatically
371 
pick up the new name when a renamed name is looked up in a name table.
372 
<P>
373 
The next stage is to load the input capsules, and to bind them together.
374 
As part of this binding process, the capsule scope identifiers for
375 
all     input capsules are mapped into a single capsule scope (to
376 
be output to     the final capsule).  The rules for this mapping are
377 
described below.
378 
<P>
379 
After binding the input capsules together, the linker tries to provide
380 
definitions for undefined names using the specified libraries.  When
381 
a     definition is found in a library (and it hasn't been suppressed
382 
by the     link suppression rules), the capsule that contains it is
383 
loaded and     bound to the input capsules as if it had been one itself.
384 
<P>
385 
After the library capsules have been bound in, external names are
386 
hidden     according to the hiding rules, and kept according to the
387 
keeping rules.     Hiding means removing an entry from the external
388 
name list of the output     capsule.  Keeping means forcing an entry
389 
into the list, if it would     otherwise be hidden.  It is illegal
390 
to hide names that have no     definition.
391 
<P>
392 
Finally the output capsule is written to a file.
393 
</BLOCKQUOTE>
394 
<P>
395 
<H3><A NAME=S71>7.1. Basic linking</A></H3>
396 
<P>
397 
This sub-section describes the process of binding capsules together
398 
in greater detail.
399 
<P>
400 
The first thing that the linker does when reading a capsule is to
401 
read in the magic number, and the major and minor version numbers.
402 
Capsules with an incorrect magic number are rejected.  The major version
403 
number of each capsule read in must be at least four.  In addition,
404 
the major version numbers of all capsules that are read in must be
405 
the same.
406 
<P>
407 
 
408 
After this, the linker reads the unit group type names (also called
409 
`prop names'), and checks that the they are known and that they are
410 
in the correct order.  There is a default list of names built into
411 
the linker (the list specified in the TDF specification) and that
412 
should be sufficient for most uses of the linker, but it is possible
413 
to provide a new list by specifying a file containing the new list
414 
on the command line.
415 
<P>
416 
The next thing the linker does is to read in the linkable entity names
417 
and the capsule scope identifier limit for each linkable entity.
418 
It checks that there are no duplicate names, and creates a mapping
419 
vector for each linkable entity, to contain the mapping from the capsule
420 
scope identifiers in the capsule being read in to the capsule scope
421 
identifiers in the capsule that will be written out.
422 
<P>
423 
After reading the linkable entity names, the linker reads the external
424 
names for each linkable entity.  For each name, it checks that its
425 
capsule scope identifier is in range, and maps that to the next available
426 
capsule scope identifier (for the same linkable entity) in the output
427 
capsule, unless a name with the same linkable entity and the same
428 
name (subject to the renaming rules) has already been read (in which
429 
case it is mapped to the same capsule scope identifier as the identical
430 
name).  The linker also checks to ensure that each capsule scope identifier
431 
has no more than one external name bound to it.
432 
<P>
433 
The final phase of reading a capsule is to read the unit groups.
434 
For normal (i.e. not <I>tld</I> or <I>tld2</I>) unit groups, the following
435 
occurs for each unit in the unit group:
436 
<BLOCKQUOTE>
437 
<P>
438 
The unit scope identifier limits for each linkable entity are read
439 
and     saved in the unit data structure (which is appended to the
440 
list of units     in that unit group for all input capsules).  When
441 
the unit is written     out in the output capsule, it may be necessary
442 
to add extra unit scope     identifier limits (and extra mapping tables)
443 
as other capsules may have     different linkable entities, which
444 
will also need entries (they will     just be zero length).
445 
<P>
446 
The capsule scope to unit scope identifier mapping tables are read,
447 
and     the old capsule scope identifier (which is first checked to
448 
see if it is     in range) is replaced by a new capsule scope identifier.
449 
This     information is also saved in the unit data structure.  The
450 
new capsule     scope identifiers are either the ones that were allocated
451 
when reading     in the external names (if the old identifier is bound
452 
to an external     name), or the next free capsule scope identifier
453 
of the required     linkable entity.
454 
<P>
455 
Finally, the unit body is read, and saved with the unit.
456 
</BLOCKQUOTE>
457 
<P>
458 
For <I>tld</I> and <I>tld2</I> unit groups, the unit group count is
459 
checked to ensure that it is one, and the number of unit scope identifier
460 
limits and identifier mapping tables are checked to ensure that they
461 
are both zero. The size of the body is read (and it must be correct
462 
as this is checked after reading the unit), and then the body is read.
463 
If the unit is a <I>tld</I>
464 
unit, then the type is read, and the body is read depending upon the
465 
type; if the unit is a <I>tld2</I> unit, then the body is read as
466 
if it where a type zero <I>tld</I> unit.
467 
<P>
468 
A type zero <I>tld</I> unit consists of a number of integers: one
469 
for each external token name, followed by one for each external tag
470 
name (in the same order as the external name tables, but tokens always
471 
precede tags).  A type one <I>tld</I> unit consists of a number of
472 
integers: one for each external name (of all linkable entities), in
473 
the same order as the external name tables.
474 
<P>
475 
Each of the integers is interpreted as a series of bits, with the
476 
bits having the following meanings:
477 
<BLOCKQUOTE>
478 
 
479 
<P>
480 
1 =  The name is declared within this capsule.
481 
<P>
482 
2 =  The name is uniquely defined within this capsule.  If    this
483 
bit is set for a tag, then the declared bit    must also be set.
484 
It is illegal to have a name    uniquely defined in more than one
485 
capsule.  If this    occurs, the linker will report an error.
486 
<P>
487 
3 =  The name is defined in this capsule, but may have    other definitions
488 
provided by other capsules.  This    bit may not be set for tokens.
489 
If a tag has this    bit set, the declared bit must also be set.
490 
It is    possible for a name to provide a unique definition,    but
491 
still allow other non-unique definitions to be    linked in from other
492 
capsules.
493 
</BLOCKQUOTE>
494 
All of the other bits in the integer are reserved.  The linker uses
495 
the information provided by this unit to check that names do not have
496 
multiple unique definitions, and to decide whether libraries should
497 
be consulted to provide a definition for a name.  If a capsule contains
498 
no linker information unit group, then the names in that capsule will
499 
have no information, and hence will not receive the extra checking
500 
or library definition.
501 
<P>
502 
<H3><A NAME=S72>7.2. Renaming</A></H3>
503 
<P>
504 
Renaming just requires that any occurrence of the name being renamed
505 
is treated as though it were an occurrence of the name it is being
506 
renamed to. This includes names read from library indices.
507 
<P>
508 
<H3><A NAME=S73>7.3. Library capsules</A></H3>
509 
<P>
510 
After reading in all of the specified capsules, the linker loads the
511 
libraries.  The library indices are read, and checked to ensure that
512 
there is no more than one definition for any external name.  If there
513 
is no unique definition, but there is a single multiple definition,
514 
then this is considered to be a definition (although this can be turned
515 
off with a command line option).
516 
<P>
517 
Once the libraries have been loaded, each of the external names in
518 
the bound capsules that are used, but not defined are looked up in
519 
the library index. If a definition is found (and it hasn't been suppressed)
520 
then the defining capsule is loaded from the library.  This process
521 
is repeated until definitions have been found for all external names
522 
that need them (and that definitions exist for), including those that
523 
are undefined in the capsules read in from the libraries.
524 
<P>
525 
<H3><A NAME=S74>7.4. Hiding</A></H3>
526 
<P>
527 
Hiding and keeping just require that all names which should be hidden,
528 
and are not required to be kept, are not written to the external name
529 
table of the output capsule.
530 
<P>
531 
<H3><A NAME=S75>7.5. Writing out the capsule</A></H3>
532 
<P>
533 
The magic number is written out, followed by the major and minor version
534 
numbers.  The major version number is the same as that in each of
535 
the loaded capsules.  The minor version number is the largest of the
536 
minor version numbers in the loaded capsules.
537 
<P>
538 
The unit group type names are written out first.  Only those unit
539 
groups that are non-empty are actually written out.  They are written
540 
out in the order specified by the current unit group name list.
541 
<P>
542 
The linkable entity names are written out next, followed by their
543 
capsule scope identifier limit.  Again, only those linkable entity
544 
names that are non empty (i.e.  have some unit scope or capsule scope
545 
identifiers) are written out.
546 
<P>
547 
After the linkable entity names have been written out, the external
548 
names are written out.  These are written out in an arbitrary order
549 
within their linkable entities, with the linkable entities being written
550 
out in the same order as in the linkable entity name section (which
551 
is itself arbitrary, but must be repeatable).  The names are written
552 
out with their new capsule scope identifiers.  External names that
553 
have been hidden must not be written out.
554 
<P>
555 
Finally the unit groups are written out in the same order as the unit
556 
group type names in the first section.  For normal units, the old
557 
counts (plus some zero counts that may be necessary if there are new
558 
linkable entities that weren't in the unit's original capsule) are
559 
written out in the same order as the linkable entity names in section
560 
two.  The counts are followed by the new capsule scope to unit scope
561 
identifier mapping tables, in the same order as the counts.  Finally
562 
the old unit content is written out.
563 
<P>
564 
For <I>tld</I> unit groups, a single version one <I>tld</I> unit is
565 
written out containing the use information for each of the external
566 
names, in the same order that the external names were written out
567 
in.
568 
<P>
569 
<HR>
570 
<H2><A NAME=S8>8. Constructing TDF Libraries</A></H2>
571 
<P>
572 
This section describes the requirements of building TDF libraries.
573 
Here is an outline of the stages of the construction process:
574 
<BLOCKQUOTE>
575 
<P>
576 
The linker is invoked with the following inputs: a set of input
577 
capsules, a set of libraries, and a set of link suppression rules.
578 
<P>
579 
The first thing that the linker does is to load the input capsules
580 
(including all capsules that are included in any of the specified
581 
libraries), and to extract their external name information into a
582 
central index.  The index is checked to ensure that there is only
583 
one     definition for any given name.  The capsules are read in in
584 
the same way     as for linking them (this checks them for validity).
585 
<P>
586 
The suppression rules are applied, to ensure that no suppressed external
587 
name will end up in the index in the output library.
588 
<P>
589 
The library is written out.  The library consists of a magic number,
590 
and     the major and minor version numbers of the TDF in the library
591 
(calculated in the same way as for capsules), the type zero, followed
592 
by     the number of capsules.  This is followed by that many capsule
593 
name and     capsule content pairs.  Finally, the index is appended
594 
to the library.
595 
<P>
596 
The index only contains entries for linkable entities that have external
597 
names defined by the library.  Only external names for which there
598 
is a     definition are written into the index, although this is not
599 
a     requirement (when linking, the linker will ignore index entries
600 
that     don't provide a definition).  Either a unique definition
601 
or a single     multiple definition are considered to be definitions
602 
(although the     latter can be disabled using a command line option).
603 
</BLOCKQUOTE>
604 
<P>
605 
<HR>
606 
<P><I>Part of the <A HREF="../index.html">TenDRA Web</A>.<BR>Crown
607 
Copyright &copy; 1998.</I></P>
608 
</BODY>
609 
</HTML>