Rev 2 | Blame | Compare with Previous | Last modification | View Log | RSS feed
.\" Crown Copyright (c) 1997
.\"
.\" This TenDRA(r) Manual Page is subject to Copyright
.\" owned by the United Kingdom Secretary of State for Defence
.\" acting through the Defence Evaluation and Research Agency
.\" (DERA). It is made available to Recipients with a
.\" royalty-free licence for its use, reproduction, transfer
.\" to other parties and amendment for any purpose not excluding
.\" product development provided that any such use et cetera
.\" shall be deemed to be acceptance of the following conditions:-
.\"
.\" (1) Its Recipients shall ensure that this Notice is
.\" reproduced upon any copies or amended versions of it;
.\"
.\" (2) Any amended version of it shall be clearly marked to
.\" show both the nature of and the organisation responsible
.\" for the relevant amendment or amendments;
.\"
.\" (3) Its onward transfer from a recipient to another
.\" party shall be deemed to be that party's acceptance of
.\" these conditions;
.\"
.\" (4) DERA gives no warranty or assurance as to its
.\" quality or suitability for any purpose and DERA accepts
.\" no liability whatsoever in relation to any use to which
.\" it may be put.
.\"
.TH tld 1
.SH NAME
tld \- TDF linking and library manipulation utility
.SH SYNTAX
.B tld
[\fImode\fR] [\fIoption\fR]... \fIfile\fR...
.SH DESCRIPTION
.LP
The
.B tld
command is used to create and manipulate TDF libraries, and to link together
TDF capsules. It has four modes, selected by one of the \fB\-ml\fR (link TDF
capsules), \fB\-mc\fR (create TDF library), \fB\-mt\fR (list TDF library
contents) or \fB\-mx\fR (extract capsules from TDF library) switches. If
provided, the switch must be the first on the command line. If one is not
provided, the \fB\-ml\fR switch is assumed.
.LP
The different modes are described below. In the description, external name
definitions are referred to as unique and multiple. A unique definition is
a definition where the defined attribute is set; a multiple definition is
one where the multiple attribute is set (i.e. more than one definition is
allowed). A definition may be both multiple and unique (if both bits are
set - this means that there is more than definition, but one of them is
unique). It is an error for there to be more than one unique definition of
any given name. It is an error for token external names to have the
multiple attribute set.
.SH SWITCHES
.LP
The new version of
.B tld
accepts both short form and long form command line switches.
.LP
Short form switches are single characters, and begin with a \&'-' or \&'+'
character. They can be concatenated into a single command line word, e.g.:
.IP
\fB\-vor\fR \fIoutput-file\fR \fIrename-shape\fR \fIrename-from\fR
\fIrename-to\fR
.LP
which contains three different switches (\fB\-v\fR, which takes no
arguments; \fB\-o\fR, which takes one argument: \fIoutput-file\fR; and
\fB\-r\fR, which takes three arguments: \fIrename-shape\fR,
\fIrename-from\fR, and \fIrename-to\fR).
.LP
Long form switches are strings, and begin with \&'--' or \&'++'. With long
form switches, only the shortest unique prefix need be entered. The long
form of the above example would be:
.IP
\fB\-\-version\fR \fB\-\-output\-file\fR \fIoutput-file\fR
\fB\-\-rename\fR \fIrename-shape\fR \fIrename-from\fR \fIrename-to\fR
.LP
In most cases the arguments to the switch should follow the switch as a
separate word. In the case of short form switches, the arguments to the
short form switches in a single word should follow the word in the order of
the switches (as in the first example). For some options, the argument may
be part of the same word as the switch (such options are shown without a
space between the switch and the argument in the switch summaries below).
In the case of short form switches, such a switch would terminate any
concatenation of switches (either a character would follow it, which would
be treated as its argument, or it would be the end of the word, and its
argument would follow as normal).
.LP
For binary switches, the \&'-' or \&'--' switch prefixes set (enable) the
switch, and the \&'+' or \&'++' switch prefixes reset (disable) the switch.
This is probably back to front, but is in keeping with other programs. The
switches \&'--' or \&'++' by themselves terminate option parsing.
.SH EXTERNAL NAMES
.LP
An external name may be either a string or a unique. A unique is written as
.IP
\fB[\fIcomponent1\fB.\fIcomponent2\fB.\fR...\fB.\fIcomponentN\fB]\fR
.LP
Each component of a unique is a string. A string consists of any sequence
of characters, although some special characters must be preceded by a
backslash character to stop them being treated specially. These characters
are \&'\fB\\\fR', \&'\fB[\fR', \&'\fB]\fR' and \&'\fB.\fR'. In addition,
the following character sequences are treated the same as they would be in
C: \&'\fB\\n\fR', \&'\fB\\r\fR', \&'\fB\\t\fR', \&'\fB\\0\fR'. Finally, the
sequence \&'\fB\\x\fINN\fR' represents the character with code \fINN\fR in
hex.
.SH RENAME FILE SYNTAX
.LP
Renaming may be specified either on the command line, or in a file. The files
that specify the renamings to be performed have the following syntax. The
file consists of a number of sections. Each section begins with a shape
name, followed by zero or more pairs of external names (each pair is
terminated by a semi-colon). Shape names are written as a sequence of
characters surrounded by single quotes. Unique names have the same syntax
as described above. String names are a sequence of characters surrounded by
double quotes. The normal backslash escape sequences are supported. The
hash character acts as a comment to end of line character (if this is
necessary).
.SH UNIT SET FILE SYNTAX
.LP
The file should consist of a sequence of strings enclosed in double quotes.
The backslash character can be used to escape characters. The following C
style escape sequences are recognized: \&'\fB\\n\fR', \&'\fB\\r\fR',
\&'\fB\\t\fR', \&'\fB\\0\fR'. Also, the sequence \&'\fB\\x\fINN\fR'
represents the character with code \fINN\fR in hex. The order of the
strings is important, as it specifies the order that the unit sets should be
in when read from capsules. It is necessary to specify the \fItld\fR unit
set name.
.SH ERROR FILE SYNTAX
.LP
It is possible to change the error messages that the linker uses. In order
to do this, make the environment variable \fITLD_ERROR_FILE\fR contain the
name of a file with the new error messages in.
.LP
The error file consists of zero or more sections. Each section begins with
a section marker (one of \fB%prefix%\fR, \fB%errors%\fR or \fB%strings%\fR).
The prefix section takes a single string (this is to be the prefix for all
error messages). The other sections take zero or more pairs of names and
strings. A name is a sequence of characters surrounded by single quotes. A
string is a sequence of characters surrounded by double quotes. In the case
of the prefix and error sections, the strings may contain variables of the
form \fB${\fIvariable name\fB}\fR. These variables will be replaced by
suitable information when the error occurs. The normal backslash escape
sequences are supported. The hash character acts as a comment to end of
line character.
.LP
The \fB\-\-show\-errors\fR option may be used to get a copy of the current
error messages.
.SH LINKING
.LP
In the default mode,
.B tld
tries to link together the TDF capsules specified on the command line. This
consists of the following stages:
.IP 1.
All of the external names specified for renaming on the command line are
added to the name tables as indirections to their new names.
.IP 2.
All of the capsules specified on the command line are loaded, and their
identifiers are mapped into a per shape namespace. In these namespaces, all
external names of the same shape and with the same name will be mapped to
the same identifier.
.B tld
will report errors about any attempt to link together more than one capsule
providing a unique definition for any external name.
.IP 3.
If any libraries were specified on the command line, then the libraries are
loaded to see what definitions they provide. After loading the libraries,
the external names specified for link suppression on the command line are
removed from the library index (so that the linker will not attempt to
define those names). Link suppression does not prevent a name from being
defined, it just stops the linker trying to define it; a definition for it
may still be found from a capsule that is loaded to define another name.
.IP
Any capsules that provide necessary definitions are loaded. There must only
be one definition for each external name in all of the libraries (in the
case of all non-token shapes, this may be either one non-unique definition,
or one unique definition with zero or more non-unique definitions; if a
unique definition exists, then the non-unique definitions are ignored).
.IP 4.
If any external names require hiding or keeping (specified by command line
switches), then they are hidden at this point. Hiding means removing the
external name from the external name list. It is illegal to hide undefined
external names. Keeping means keeping an external name in the external name
tables. Keeping a name overrides any attempt to hide that name.
.IP 5.
A new TDF capsule is created, consisting of all of the input capsules and
the necessary library capsules. Unless specified with the
\fB\-\-output\-file\fR switch, the output file will be called
\fIcapsule.j\fR.
.SH Switches
.LP
.B tld
accepts the following switches in link mode:
.LP
\fB\-\-all\-hide\-defined\fR
.br
\fB\-a\fR
.IP
Hide all external names (of any shape) that are defined.
.LP
\fB\-\-debug\-file\fR \fIFILE\fR
.br
\fB\-d\fR \fIFILE\fR
.IP
Produce a diagnostic trace of the linking process in \fIFILE\fR.
.LP
\fB\-\-help\fR
.br
\fB\-?\fR
.IP
Write an option summary to the standard error.
.LP
\fB\-\-hide\fR \fISHAPE\fR \fINAME\fR
.br
\fB\-h\fR \fISHAPE\fR \fINAME\fR
.IP
Cause the external \fISHAPE\fR name \fINAME\fR to be hidden. An error is
reported if the name is not defined.
.LP
\fB\-\-hide\-defined\fR \fISHAPE\fR
.br
\fB\-H\fR \fISHAPE\fR
.IP
Cause the all external \fISHAPE\fR names that are defined to be hidden.
.LP
\fB\-\-keep\fR \fISHAPE\fR \fINAME\fR
.br
\fB\-k\fR \fISHAPE\fR \fINAME\fR
.IP
Cause the external \fISHAPE\fR name \fINAME\fR to be kept.
.LP
\fB\-\-keep\-all\fR \fISHAPE\fR
.br
\fB\-K\fR \fISHAPE\fR
.IP
Cause the all external \fISHAPE\fR names to be kept.
.LP
\fB\-\-library\fR \fIFILE\fR
.br
\fB\-l\fR\fIFILE\fR
.IP
Use the file \fIFILE\fR as a TDF library. If the file name contains a \&'/',
then it is used as specified; if not, the library search path is searched
for a file named \&'\fIFILE\fR.tl'. Duplicate entries for the same library
are ignored.
.LP
\fB\-\-output\-file\fR \fIFILE\fR
.br
\fB\-o\fR \fIFILE\fR
.IP
Write the output capsule to the file \fIFILE\fR. If this switch is not
specified, then the output is written to the file \&'capsule.j' instead.
.LP
\fB\-\-path\fR \fIDIRECTORY\fR
.br
\fB\-L\fR\fIDIRECTORY\fR
.IP
Append the directory \fIDIRECTORY\fR to the library search path.
.LP
\fB\-\-rename\fR \fISHAPE\fR \fIFROM\fR \fITO\fR
.br
\fB\-r\fR \fISHAPE\fR \fIFROM\fR \fITO\fR
.IP
Rename the external \fISHAPE\fR name \fIFROM\fR to \fITO\fR.
.LP
\fB\-\-rename\-file\fR \fIFILE\fR
.br
\fB\-R\fR \fIFILE\fR
.IP
Read the contents of the file \fIFILE\fR as a series of renaming
specifications. The format of the file is described above.
.LP
\fB\-\-show\-errors\fR
.br
\fB\-e\fR
.IP
Write the current error message list to the standard output.
.LP
\fB\-\-suppress\fR \fISHAPE\fR \fINAME\fR
.br
\fB\-s\fR \fISHAPE\fR \fINAME\fR
.IP
Do not try to find a definition for the external \fISHAPE\fR name \fINAME\fR.
.LP
\fB\-\-suppress\-all\fR \fISHAPE\fR
.br
\fB\-S\fR \fISHAPE\fR
.IP
Do not try to find a definition for any external \fISHAPE\fR name.
.LP
\fB\-\-suppress\-mult\fR
.br
\fB\-M\fR
.IP
Do not use non-unique definitions in libraries as definitions for external
names.
.LP
\fB\-\-unit\-file\fR \fIFILE\fR
.br
\fB\-u\fR \fIFILE\fR
.IP
Parse \fIFILE\fR to get a new unit set name list. By default, all of the
standard (as specified in the version 4.0 TDF specification) unit set names
are known.
.LP
\fB\-\-version\fR
.br
\fB\-v\fR
.IP
Write the version number of the program to the standard error stream.
.LP
\fB\-\-warnings\fR
.br
\fB\-w\fR
.IP
Enable/disable the printing of warning messages. Warnings are generated for
things like obsolete linker information units, and undefined external names.
.SH LIBRARY CONSTRUCTION
.LP
A TDF library is a sequence of named capsules, with an index. The index
indicates which external names are defined by the capsules in the library,
and which capsules provide the definitions. When invoked with the
\fB\-mc\fR switch,
.B tld
produces a library consisting of the TDF capsules specified on the command
line. The library is written to the file \fIlibrary.tl\fR, unless the
\fB\-\-output\-file\fR switch is used.
.SH Switches
.LP
.B tld
accepts the following switches in library construction mode:
.LP
\fB\-\-debug\-file\fR \fIFILE\fR
.br
\fB\-d\fR \fIFILE\fR
.IP
Produce a diagnostic trace of the library construction process in \fIFILE\fR.
.LP
\fB\-\-help\fR
.br
\fB\-?\fR
.IP
Write an option summary to the standard error.
.LP
\fB\-\-include\-library\fR \fIFILE\fR
.br
\fB\-i\fR \fIFILE\fR
.IP
Include all of the capsules in the TDF library \fIFILE\fR in the library
being constructed. The library name should be a proper file name, not a
library abbreviation like the \fB\-\-library\fR switch used by the linking
mode.
.LP
\fB\-\-output\-file\fR \fIFILE\fR
.br
\fB\-o\fR \fIFILE\fR
.IP
Write the output library to the file \fIFILE\fR. If this switch is not
specified, then the output is written to the file \&'library.tl' instead.
.LP
\fB\-\-show\-errors\fR
.br
\fB\-e\fR
.IP
Write the current error message list to the standard output.
.LP
\fB\-\-suppress\fR \fISHAPE\fR \fINAME\fR
.br
\fB\-s\fR \fISHAPE\fR \fINAME\fR
.IP
Do not try to find a definition for the external \fISHAPE\fR name \fINAME\fR.
.LP
\fB\-\-suppress\-all\fR \fISHAPE\fR
.br
\fB\-S\fR \fISHAPE\fR
.IP
Do not try to find a definition for any external \fISHAPE\fR name.
.LP
\fB\-\-suppress\-mult\fR
.br
\fB\-M\fR
.IP
Do not use non-unique definitions in libraries as definitions for external
names.
.LP
\fB\-\-unit\-file\fR \fIFILE\fR
.br
\fB\-u\fR \fIFILE\fR
.IP
Parse \fIFILE\fR to get a new unit set name list. By default, all of the
standard (as specified in the version 4.0 TDF specification) unit set names
are known.
.LP
\fB\-\-version\fR
.br
\fB\-v\fR
.IP
Write the version number of the program to the standard error stream.
.SH LIBRARY CONTENTS
.LP
When invoked with the \fB\-mt\fR switch,
.B tld
produces a listing of the contents of the TDF library specified on the
command line.
.SH Switches
.LP
.B tld
accepts the following switches in library contents mode:
.LP
\fB\-\-debug\-file\fR \fIFILE\fR
.br
\fB\-d\fR \fIFILE\fR
.IP
Produce a diagnostic trace of the library contents process in \fIFILE\fR.
.LP
\fB\-\-help\fR
.br
\fB\-?\fR
.IP
Write an option summary to the standard error.
.LP
\fB\-\-index\fR
.br
\fB\-i\fR
.IP
Enable/disable the printing of the index of the library. If printing of the
index is enabled, the index of the library will be printed. The order of
the shapes and external names in the printed index is not necessarily the
same as the order of the index in the library itself. If the order is
important, use the \fR\-\-debug\-file\fR option and look at the output that is
produced.
.LP
\fB\-\-show\-errors\fR
.br
\fB\-e\fR
.IP
Write the current error message list to the standard output.
.LP
\fB\-\-size\fR
.br
\fB\-s\fR
.IP
Enable/disable the printing of the size of each capsule in the library. If
enabled, the size of each capsule in bytes is printed after its name.
.LP
\fB\-\-version\fR
.br
\fB\-v\fR
.IP
Write the version number of the program to the standard error stream.
.SH LIBRARY EXTRACTION
.LP
When invoked with the \fB\-mx\fR switch,
.B tld
extracts capsules from the TDF library specified as the first file on the
command line. The names of the capsules to extract should follow the
library name. If capsule names are specified, they must match exactly the
names of the capsules in the library (use the \fB\-mt\fR mode switch to find
out what the exact names are). The capsules are normally extracted relative
to the current directory, using the name of the capsule as the output file
name. The linker will try to create any directories on the extracted
capsule's path name (in some implementations of the linker this may not be
supported, in which case the directories will need to be created manually
before extraction). The extracted capsules will overwrite existing files of
the same name.
.SH Switches
.LP
.B tld
accepts the following switches in library extraction mode:
.LP
\fB\-\-all\fR
.br
\fB\-a\fR
.IP
Enable/disable the extraction of all capsules. If all capsules are to be
extracted, no capsule names should be specified on the command line.
.LP
\fB\-\-basename\fR
.br
\fB\-b\fR
.IP
Enable/disable the use of the basename of each capsule when extracting. If
this is enabled, then extracted capsules are extracted into the current
directory, using just their basename. This may cause some of the capsules
to be written on top of each other.
.LP
\fB\-\-debug\-file\fR \fIFILE\fR
.br
\fB\-d\fR \fIFILE\fR
.IP
Produce a diagnostic trace of the library extraction process in \fIFILE\fR.
.LP
\fB\-\-help\fR
.br
\fB\-?\fR
.IP
Write an option summary to the standard error.
.LP
\fB\-\-info\fR
.br
\fB\-i\fR
.IP
Enable/disable informational messages. These say which capsules are being
extracted.
.LP
\fB\-\-match\-basename\fR
.br
\fB\-m\fR
.IP
Enable/disable matching of capsule names by basename. If enabled, then the
basename of each library capsule is also matched against the file names
specified. This may result in more than one capsule being extracted for one
file name.
.LP
\fB\-\-show\-errors\fR
.br
\fB\-e\fR
.IP
Write the current error message list to the standard output.
.LP
\fB\-\-version\fR
.br
\fB\-v\fR
.IP
Write the version number of the program to the standard error stream.
.SH SEE ALSO
.LP
tcc(1).