16.4 Implementation

This section describes some of the conventions we used in the organization of the source code. See section `Top' in GNU Coding Standards, for the general GNU conventions.

In our sources, `.c' files include `config.h' first, which in turn includes `global.h', which includes `types.h' and other header files which define ubiquitous identifiers.

`.h' files, on the other hand, do not include `config.h'. They only include whatever headers are needed to define what they themselves use--typically including but not limited to `types.h'.

All `.h' files are protected with #ifndef unique-symbol.

The upshot of these conventions is that headers can be included in any order, as many times as necessary. In a `.c' file, only those headers which define symbols needed in the C source need be included, without worrying that some headers depend on others. (ANSI C defines its headers to follow these same rules.)

Virtually all `.c' files--the only exceptions are (sometimes) `main.c' and some library files--have a corresponding `.h' file, which defines all the public symbols (e.g., non-static routines and types). in the `.h' file are intended to explain the external interface; comments in the `.c' file assume you already know what's in the `.h' file, to avoid having the same information in two places, and try to explain only implementation details.

Therefore, a `.c' file should always include its corresponding `.h' file, to ensure consistency between the definitions and the declarations. GCC 2's `-Wmissing-prototypes' option can be used to check this.

The main program is always in a file named `main.c'. Typically it loops through all the characters in the input font, doing something with them. Parsing arguments is also done in `main.c', in a function named read_command_line, using getopt. See section 3.3 Command-line options, for more information on option parsing.

The `configure' script used to determine system dependencies is generated by GNU Autoconf from `configure.in'. When `configure' runs, it creates `include/c-auto.h' from `include/c-auto.h.in' to record what it discovers. `config.h' includes this file.

We access members of most structure types via macros instead of with . or -> directly. We pass and return whole structures without hesitation; this has not resulted in any noticeable performance loss. When we use pointers to structures, it's almost always because we need a distinguishable value (i.e., NULL).

When a function has no side effects (e.g., assignments to global variables), and does not examine any values except its arguments (e.g. if a pointer is passed, it does not examine the data pointed to), we declare it const. (This is a GNU C extension.)