NAME
tld - TDF linking and library manipulation utility
SYNTAX
tld [mode] [option]... file...
DESCRIPTION
The 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
-ml (link TDF capsules), -mc (create TDF library), -mt (list TDF
library contents) or -mx (extract capsules from TDF library) switches.
If provided, the switch must be the first on the command line. If one
is not provided, the -ml switch is assumed.
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.
SWITCHES
The new version of tld accepts both short form and long form command
line switches.
Short form switches are single characters, and begin with a ’-’ or ’+’
character. They can be concatenated into a single command line word,
e.g.:
-vor output-file rename-shape rename-from rename-to
which contains three different switches (-v, which takes no arguments;
-o, which takes one argument: output-file; and -r, which takes three
arguments: rename-shape, rename-from, and rename-to).
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:
--version --output-file output-file --rename rename-shape
rename-from rename-to
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).
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.
EXTERNAL NAMES
An external name may be either a string or a unique. A unique is
written as
[component1.component2.....componentN]
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 ’\’, ’[’, ’]’ and ’.’. In addition, the following
character sequences are treated the same as they would be in C: ’\n’,
’\r’, ’\t’, ’\0’. Finally, the sequence ’\xNN’ represents the
character with code NN in hex.
RENAME FILE SYNTAX
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).
UNIT SET FILE SYNTAX
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: ’\n’, ’\r’, ’\t’,
’\0’. Also, the sequence ’\xNN’ represents the character with code NN
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 tld unit set name.
ERROR FILE SYNTAX
It is possible to change the error messages that the linker uses. In
order to do this, make the environment variable TLD_ERROR_FILE contain
the name of a file with the new error messages in.
The error file consists of zero or more sections. Each section begins
with a section marker (one of %prefix%, %errors% or %strings%). 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 ${variable name}. 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.
The --show-errors option may be used to get a copy of the current error
messages.
LINKING
In the default mode, tld tries to link together the TDF capsules
specified on the command line. This consists of the following stages:
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.
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. tld will
report errors about any attempt to link together more than one
capsule providing a unique definition for any external name.
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.
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).
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.
5. A new TDF capsule is created, consisting of all of the input
capsules and the necessary library capsules. Unless specified
with the --output-file switch, the output file will be called
capsule.j.
Switches
tld accepts the following switches in link mode:
--all-hide-defined
-a
Hide all external names (of any shape) that are defined.
--debug-file FILE
-d FILE
Produce a diagnostic trace of the linking process in FILE.
--help
-?
Write an option summary to the standard error.
--hide SHAPE NAME
-h SHAPE NAME
Cause the external SHAPE name NAME to be hidden. An error is
reported if the name is not defined.
--hide-defined SHAPE
-H SHAPE
Cause the all external SHAPE names that are defined to be
hidden.
--keep SHAPE NAME
-k SHAPE NAME
Cause the external SHAPE name NAME to be kept.
--keep-all SHAPE
-K SHAPE
Cause the all external SHAPE names to be kept.
--library FILE
-lFILE
Use the file FILE 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 ’FILE.tl’. Duplicate entries
for the same library are ignored.
--output-file FILE
-o FILE
Write the output capsule to the file FILE. If this switch is
not specified, then the output is written to the file
’capsule.j’ instead.
--path DIRECTORY
-LDIRECTORY
Append the directory DIRECTORY to the library search path.
--rename SHAPE FROM TO
-r SHAPE FROM TO
Rename the external SHAPE name FROM to TO.
--rename-file FILE
-R FILE
Read the contents of the file FILE as a series of renaming
specifications. The format of the file is described above.
--show-errors
-e
Write the current error message list to the standard output.
--suppress SHAPE NAME
-s SHAPE NAME
Do not try to find a definition for the external SHAPE name
NAME.
--suppress-all SHAPE
-S SHAPE
Do not try to find a definition for any external SHAPE name.
--suppress-mult
-M
Do not use non-unique definitions in libraries as definitions
for external names.
--unit-file FILE
-u FILE
Parse FILE 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.
--version
-v
Write the version number of the program to the standard error
stream.
--warnings
-w
Enable/disable the printing of warning messages. Warnings are
generated for things like obsolete linker information units, and
undefined external names.
LIBRARY CONSTRUCTION
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 -mc switch, tld produces a library consisting of the TDF capsules
specified on the command line. The library is written to the file
library.tl, unless the --output-file switch is used.
Switches
tld accepts the following switches in library construction mode:
--debug-file FILE
-d FILE
Produce a diagnostic trace of the library construction process
in FILE.
--help
-?
Write an option summary to the standard error.
--include-library FILE
-i FILE
Include all of the capsules in the TDF library FILE in the
library being constructed. The library name should be a proper
file name, not a library abbreviation like the --library switch
used by the linking mode.
--output-file FILE
-o FILE
Write the output library to the file FILE. If this switch is
not specified, then the output is written to the file
’library.tl’ instead.
--show-errors
-e
Write the current error message list to the standard output.
--suppress SHAPE NAME
-s SHAPE NAME
Do not try to find a definition for the external SHAPE name
NAME.
--suppress-all SHAPE
-S SHAPE
Do not try to find a definition for any external SHAPE name.
--suppress-mult
-M
Do not use non-unique definitions in libraries as definitions
for external names.
--unit-file FILE
-u FILE
Parse FILE 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.
--version
-v
Write the version number of the program to the standard error
stream.
LIBRARY CONTENTS
When invoked with the -mt switch, tld produces a listing of the
contents of the TDF library specified on the command line.
Switches
tld accepts the following switches in library contents mode:
--debug-file FILE
-d FILE
Produce a diagnostic trace of the library contents process in
FILE.
--help
-?
Write an option summary to the standard error.
--index
-i
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
--debug-file option and look at the output that is produced.
--show-errors
-e
Write the current error message list to the standard output.
--size
-s
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.
--version
-v
Write the version number of the program to the standard error
stream.
LIBRARY EXTRACTION
When invoked with the -mx switch, 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 -mt 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.
Switches
tld accepts the following switches in library extraction mode:
--all
-a
Enable/disable the extraction of all capsules. If all capsules
are to be extracted, no capsule names should be specified on the
command line.
--basename
-b
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.
--debug-file FILE
-d FILE
Produce a diagnostic trace of the library extraction process in
FILE.
--help
-?
Write an option summary to the standard error.
--info
-i
Enable/disable informational messages. These say which capsules
are being extracted.
--match-basename
-m
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.
--show-errors
-e
Write the current error message list to the standard output.
--version
-v
Write the version number of the program to the standard error
stream.
SEE ALSO
tcc(1).
tld(1)