ctoh Command description

contents

# 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*/

The first and last line won't be copied.

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

The first and last line won't be copied.

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

An option will be specified as follows: -<Name>=<Value>
A flag is toggled that way: -<Name>
The default value will be applied when the option wasn't specified.

Name | Type | Default value | Semantic
CPATH | path | . | [DLL basename~]C source directory ; ... [*.c]
HPATH | path | . | H target directory [*.h]
PRJ | path | . | directory for project image file [ctoh.cth]
force | flag | false | force the creation of the header files
ct | flag | false | prefix type identifier string,bool,byte,word with 'c_'
exp | flag | false | generate ms linker export directives / modul
DPATH | path | "" | document target directory [*.htm]
DROOT | path | index.html | root document file
api | string | "" | DLL basename for ms DLL-based ex/import directives, applied to functions prefixed with '_DLL_EXPORT_'

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