ctoh C header file generation

Overview

'ctoh' creates the corresponding header files for all given c source files which represent modules, i.e. don't contain the function 'main'. The lines below show the general structure of the generated header files:

               | Header ...
               | #ifndef _INCL
               | #define _INCL
               | Includes ...
               | #ifdef __cplusplus
               | extern "C" {
               | #endif
               | Signature ...
               | #ifdef __cplusplus
               | }
               | #endif
               | #endif
    

The header file will only be produced if there are differences to the previous one.

Rules

Within each c modul there may be certain groups of lines, called blocks, which belong to the interface. If nothing else is mentioned each interface block starts with a word and is followed either by an empty line or the curly bracket '{' at line position 0 which both marks the end of the block. In the interface copy the curly bracket '{' is replaced by a semicolon ';'. The body within the curly brackets and the curly bracket '}' will be skipped.

Function definition block

The basic idea is that a function definition block starts with a word that is not marked as non-function or non-interface related, i.e. the result type name.

The header definition ends with the first empty line or the curly bracket '{' at line position 0. The latter will be replaced with a semicolon ';' in the copy for the interface. The function body will be skipped.

Non-interface related block

Blocks whose first Line start with on of the following words don't belong to the interface and will be skipped:

'static', 'ConcreteType', 'ConcreteImp', 'struct', 'union' und 'typedef', 'inline', 'class', 'template'

Beside that a member function definition block, recognized by the pattern 'name::name' will be skipped.

C source file header block

The first block will allways be copied. Within this block the suffix of the file name will be patched from '.c' to '.h'.

Include block

The first block whose lines starts with an #include-directive will be copied. In order to copy the necessary #include-directives they must be places first in the c source file, separated by an empty line from the rest.

Comment block

Comment lines starting with '/*I-' or '/*I=' are interface-related and thus copied. The Character 'I' will be replaced with a space character. Further comment blocks starting with '/*!' will be copied.

Explicit interface block ( 1 )
In order to force the copy of certain c source lines to the interface the first line of such a block must only contain the comment '/*INTERFACE*/'. This line will be skipped and not copied.

'/*DOC_INTERFACE*/' is a second variant which in addition copies the block to the [.htm] documentation file if the option 'DPATH' is given.

Explicit interface block ( 2 )
In addition to the previous method the following uses an explicit start and end tag to provide more flexibility.

                | /*INTERFACE_COPY_ON*/
                | ...
                | /*INTERFACE_COPY_OFF*/
    

Alternative '/*DOC_INTERFACE_COPY_ON*/' and '/*DOC_INTERFACE_COPY_OFF*/' can be used for additional documentation purposes.

Explicit interface-only block
The following mechanismn applies to text which should be placed in the interface but is not visible in the c source file for the c/c++ compiler. This is done via the below mentioned conditional preprocessor directive. As a consequence the macro name 'INTERFACE' can't be defined.

                | #ifdef INTERFACE
                | ...
                | #endif
    

Documentation block

A documentation block is non-interface related and will be skipped. Therefore the macro name can't be defined in another context.

                | #ifdef DOCUMENT
                | ...
                | #endif
    

Interface layout

Blocks where the first line starts with a letter and ends with ')' and the second line starts with '/*' or '{' will be recognized as function definitions and layouted in one line.

The comment line '/*INTERFACE_GROUP*/' produces an empty line.

Starting point of the Signature

Generall the signature starts after the first include-block or before the first function definition. The comment line '/*INTERFACE_LINKAGE_ON*/ forces the creation of the opening linkage block.

Options

The options '-exp' and '-api' are not used in a linux environment.