Man Linux: Main Page and Category List

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)