tld(1) – TenDRA

Name

tld — TDF linking and library manipulation utility

Synopsis

tld

tld

tld

-mt [ -d file | --debug-file file ]
[ -i file | --index ] [ -s | --size ]
file…

tld

tld

[ -ml | -mc | -mt | -mx ] { -? | --help | -v | --version }

Description

The tld command is used to create and manipulate TDF libraries, and to link together TDF capsules. It has four modes:

Switch	Mode
`-ml`	Link TDF capsules (default)
`-mc`	Create TDF library
`-mt`	List TDF library contents
`-mx`	Extract capsules from TDF library

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

This 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  shape  from  to

which contains three different switches (-v, which takes no arguments; -o, which takes one argument: output-file; and -r, which takes three arguments: shape, from, and 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  shape  from  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.

The following options are common to all modes:

-?
--help: Write an option summary to the standard error. The exact options written out are specific to the particular mode under which tld is running.
-v
--version: Write the version number of the program to the standard error stream.

External Names

An external name may be either a string or a unique. A unique is written as

[component₁.component₂.… .component_n]

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:

Sequence	Meaning
`\[`	Literal `[`
`\]`	Literal `]`
`\.`	Literal `.`
`\n`	Newline
`\r`	Carriage return
`\t`	Tab
`\`	Space
`\xAB`	ASCII character `AB` (in hex)

Linking

In the default mode, tld tries to link together the TDF capsules specified on the command line. This consists of the following stages:

All of the external names specified for renaming on the command line are added to the name tables as indirections to their new names.
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.
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).
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.
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:

-a
--all-hide-defined: Hide all external names (of any shape) that are defined.
-d file
--debug-file file: Produce a diagnostic trace of the linking process in file.
-h shape name
--hide shape name: Cause the external shape name name to be hidden. An error is reported if the name is not defined.
-H shape
--hide-defined shape: Cause the all external shape names that are defined to be hidden.
-i
--missing-definitions: Warn about undefined external linker names. These warnings are disabled by default.
-k shape name
--keep shape name: Cause the external shape name name to be kept.
-K shape
--keep-all shape: Cause the all external shape names to be kept.
-lfile
--library file: 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.
-o file
--output-file 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.
-Ldir
--path dir: Append the directory dir to the library search path.
-r shape from to
--rename shape from to: Rename the external shape name from to to.
-R file
--rename-file file: Read the contents of the file file as a series of renaming specifications. The format of the file is described above.
-s shape name
--suppress shape name: Do not try to find a definition for the external shape name name.
-S shape
--suppress-all shape: Do not try to find a definition for any external shape name.
-M
--suppress-mult: Do not use non-unique definitions in libraries as definitions for external names.
-u file
--unit-file 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.
-w
--warnings: Enable/disable the printing of warning messages. Warnings are generated for things like obsolete linker information units, and undefined external names when $i2.opt; is enabled.

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.

tld accepts the following switches in library construction mode:

-d file
--debug-file file: Produce a diagnostic trace of the library construction process in file.
-i file
--include-library 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.
-o file
--output-file 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.
-s shape name
--suppress shape name: Do not try to find a definition for the external shape name name.
-S shape
--suppress-all shape: Do not try to find a definition for any external shape name.
-M
--suppress-mult: Do not use non-unique definitions in libraries as definitions for external names.
-u file
--unit-file 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.

Library Contents

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:

-d file
--debug-file file: Produce a diagnostic trace of the library contents process in file.
-i file
--index: 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.
-s
--size: 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.

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.

tld accepts the following switches in library extraction mode:

-a
--all: Enable/disable the extraction of all capsules. If all capsules are to be extracted, no capsule names should be specified on the command line.
-b
--basename: 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.
-d file
--debug-file file: Produce a diagnostic trace of the library extraction process in file.
-i file
--info: Enable/disable informational messages. These say which capsules are being extracted.
-m
--match-basename: 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.