tld - TDF linking and library manipulation utility

tld [mode] [option]... file...

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

When invoked with the -mt switch, tld produces a listing of the contents of the TDF library specified on the command line.

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.

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.

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.

tcc(1).