1.1. Specification Levels

Let us begin by examining the various levels of specification with which tspec is concerned. At the lowest level it is concerned with objects - the types, expressions, constants etc. which comprise the API - and indeed most of this document is concerned with how tspec describes these objects. At the highest level, tspec is concerned with APIs. We could just describe an API as being a set of objects, however this is to ignore the internal structure of APIs.

At the most obvious level the objects in an API are spread over a number of different system headers. For example, in ANSI, the objects concerned with file input and output are grouped in stdio.h, whereas those concerned with string manipulation are in string.h. But a further level of refinement is also required. For example, ANSI specifies that the type size_t is defined in both stdio.h and string.h. Therefore tspec needs to be able to represent subsets of headers in order to express this intersection relation.

To conclude, tspec distinguishes four levels of specification - APIs (which are sets of headers), headers (which are sets of objects), subsets of headers, and objects. It identifies APIs by an identifying name chosen by the person performing the API description. The (purely arbitrary) convention is for short, lower case names, for example:

In this document, headers are identified by the API they belong to and the header name. Thus c/c89:stdio.h refers to the stdio.h header of the ANSI API. Finally subsets of headers are identified by the header and the subset name. If, for example, the stdio.h header of ANSI has a subset named file, then this is referred to as c/c89:stdio.h:file.

1.2. Input Layout

The tspec representation of an API is arranged as a directory with the same name as the API, containing a number of files, one for each API header. For example, the ANSI C89 API is represented by a directory c/c89 containing files c/c89/stdio.h, c/c89/string.h.ts etc. In addition each API directory contains a master file (for ANSI C89 it would be called c/c89/master.ts) which lists all the headers comprising that API.

When tspec needs to find an API directory it does so by searching along its input directory path. This is a colon separated list of directories to be searched. This may be specified in a number of ways. A default search list is built into tspec, however this may be overridden by the system variable TSPEC_INPUT. Directories may be added to the start of the path using the -Idir command-line option. The current working directory is always added to the start of the path.

1.3. Output Layout

tspec actually outputs two sets of output files, the include output files, containing the #pragma token directives corresponding to the input API, and the source output files, which provide a rig for TDF library building (see section 6.4). These output files and directories are built up under two standard output directories - the include output directory, incl_dir say, and the source output directory, src_dir say. tspec has default values for these directories built in, but these may be overridden in a number of ways. Firstly, if the system variable TSPEC_OUTPUT is defined to be dir, say, then incl_dir is dir/include and src_dir is dir/src. Secondly, incl_dir and src_dir can be set independently using the system variables TSPEC_INCL_OUTPUT and TSPEC_SRC_OUTPUT respectively. Finally, they may also be set using the -Odir and -Sdir command-line options respectively.

As an example of the mapping from input files to output files, the header c/c89:stdio.h is mapped to the include output file incl_dir/c/c89.api/stdio.h and the source output file src_dir/c/c89.api/stdio.c. The header subset c/c89:stdio.h:file is mapped to its own pair of output files, subset_dir/c/c89.api/file.h and src_dir/c/c89.api/file.c.

The default output file names can be overridden by means of the INCLNAME and SOURCENAME file properties described in section 5.4.

By default, tspec only creates an output file if the date stamps on all the input files it depends on indicate that it needs updating. In effect, tspec creates an internal makefile from the dependencies it deduces. This behaviour can be overridden by means of the -f command-line option, which forces all output files to be created.

In addition, tspec only creates the source output file if it is needed for TDF library building. If the corresponding include output file does not contain any token specifications then the source output file is suppressed (see section 5.5).

tspec can also generate environment files suitable for tcc (see section 5.4).