C++ Producer Guide

March 1998

3.1.1 - C coding standard

3.1.2 - API usage and target dependencies

3.1.3 - Source code modules

3.1. Source code organisation

This section describes the basic organisation of the source code for the C++ producer. This includes the coding conventions applied, the application programming interface (API) observed and the division of the code into separate modules.

3.1.1. C coding standard

The C++ producer is written in a subset of C which is compatible with C++ (it compiles with most C compilers, but also bootstraps itself). It has been written to conform to the local (OSSG) C coding standard; most of the conformance checking being automated by use of a user-defined compilation profile, ossg_std.h. The standard macros described in the coding standard are defined in the standard header ossg.h. This is included from the header config.h which is included by all source files. The default definitions for these macros, set according to the value of __STDC__ and other compiler-defined macros, should be correct, but they can be overridden by defining the FS_* macros, described in the header, as command-line options.

The most important of these macros are those used to handle function prototypes, enabling both ISO and pre-ISO C compilers to be accommodated. Simple function definitions take the form:

	ret function
	    PROTO_N ( ( p1, p2, ...., pn ) )
	    PROTO_T ( par1 p1 X par2 p2 X .... X parn pn )
	{
	    ....
	}

	ret function PROTO_S ( ( par1, par2, ...., parn ) ) ;

	ret function
	    PROTO_Z ()
	{
	    ....
	}

	ret function PROTO_S ( ( void ) ) ;

	#if FS_STDARG
	#include <stdarg.h>
	#else
	#include <varargs.h>
	#endif

	ret function
	    PROTO_V ( ( par1 p1, par2 p2, ...., parn pn, ... ) )
	{
	    va_list args ;
	    ....
	#if FS_STDARG
	    va_start ( args, pn ) ;
	#else
	    par1 p1 ;
	    par2 p2 ;
	    ....
	    parn pn ;
	    va_start ( args ) ;
	    p1 = va_arg ( args, par1 ) ;
	    p2 = va_arg ( args, par2 ) ;
	    ....
	    pn = va_arg ( args, parn ) ;
	#endif
	    ....
	    va_end ( args ) ;
	    ....
	}

	ret function PROTO_W ( ( par1, par2, ...., parn, ... ) ) ;

The following TenDRA keywords are defined (with suitable default values for non-TenDRA compilers):

	#pragma TenDRA keyword SET for set
	#pragma TenDRA keyword UNUSED for discard variable
	#pragma TenDRA keyword IGNORE for discard value
	#pragma TenDRA keyword EXHAUSTIVE for exhaustive
	#pragma TenDRA keyword REACHED for set reachable
	#pragma TenDRA keyword UNREACHED for set unreachable
	#pragma TenDRA keyword FALL_THROUGH for fall into case

Various flags giving properties of the compiler being used are defined in ossg.h. Among the most useful are FS_STDARG, which is true if the compiler supports ellipsis functions (see above), and FS_STDC_HASH, which is true if the preprocessor supports the ISO stringising and concatenation operators. The macros CONST and VOLATILE, to be used in place of const and volatile, are also defined.

A policy of rigorous static program checking is enforced. The TenDRA C producer is applied with the user-defined compilation mode ossg_std.h and intermodule checks enabled. Checking is applied with both the C and #pragma token calculus output files. The C++ producer itself is applied with the same checks. gcc -Wall and various versions of lint are also periodically applied.

3.1.2. API usage and target dependencies

Most of the API features used in the C++ producer are to be found in the ISO C API, with just a couple of extensions from POSIX required. These POSIX features can be disabled with minimal loss of functionality by defining the macro FS_POSIX to be false.

The following features are used from the ISO <stdio.h> header:

	BUFSIZ		EOF		FILE		SEEK_SET
	fclose		fflush		fgetc		fgets
	fopen		fprintf		fputc		fputs
	fread		fseek		fwrite		rewind
	sprintf		stderr		stdin		stdout
	vfprintf

	EXIT_SUCCESS	EXIT_FAILURE	NULL		abort
	exit		free		malloc		realloc
	size_t

	memcmp		memcpy		strchr		strcmp
	strcpy		strlen		strncmp		strrchr

	isalpha		isprint

	UCHAR_MAX	UINT_MAX	ULONG_MAX

	va_arg		va_end		va_list		va_start

	localtime	time		time_t		struct tm
	tm::tm_hour	tm::tm_mday	tm::tm_min	tm::tm_mon
	tm::tm_sec	tm::tm_year

	stat		struct stat	stat::st_dev	stat::st_ino
	stat::st_mtime

There are a couple of target dependencies in the producer which can overridden using command-line options:

1. It assumes that if a count of the number of characters read from an input file is maintained, then that count value can be used as an argument to fseek. This may not be true on machines where the end of line marker consists of both a newline and a carriage return. In this case the -m-f command-line option can be used to switch to a slower, but more portable, algorithm for setting file positions.

2. It assumes that a file is uniquely determined by the st_dev and st_ino fields of its corresponding stat value. This is used when processing #include directives to prevent a file being read more than once if this is not necessary. This assumption may not be true on machines with a small ino_t type which have file systems mounted from machines with a larger ino_t type. In this case the -m-i command-line option can be used to disable this check.

3.1.3. Source code modules

For convenience, the source code is divided between a number of directories:

1. The base directory contains only the module containing the main function, the basic type descriptions and the Makefile.
2. The directories obj_c and obj_tok contain respectively the C and #pragma token headers generated from the type algebra by calculus . The directory obj_templ contains certain calculus template files.
3. The directory utility contains routines for such utility operations as memory allocation and error reporting, including the error catalogue.
4. The directory parse contains routines concerned with parsing and preprocessing the input, including the sid grammar.
5. The directory construct contains routines for building up and analysing the internal representation of the parsed code.
6. The directory output contains routines for outputting the internal representation in various formats including as a TDF capsule, a C++ spec file, or a symbol table dump file.

Each module consists of a C source file, file.c say, containing function definitions, and a corresponding header file file.h containing the declarations of these functions. The header is included within its corresponding source file to check these declarations; it is protected against multiple inclusions by a macro of the form FILE_INCLUDED. The header contains a brief comment describing the purpose of the module; each function in the source file contains a comment describing its purpose, its inputs and its output.

The following table lists all the source modules in the C++ producer with a brief description of the purpose of each:

Part of the TenDRA Web.
Crown Copyright © 1998.