# Project files

- Overview
- Project file contents

## Overview

The most powerful and multi-purpose feature of H2D is the project file, which name may be specified at the command line after `=p`.

The project file may be used:

- To translate a set of header files at once, using the same option settings:

  `-BACKEND=C`
  `-GENROVARS+`
  `!module <stdio.h>`
  `!module <stdlib.h>`

- To map calling/naming convention qualifiers used by a particular C compiler to those supported by H2D (see Non-standard qualifiers), or to make them ignorable:

  `!header <*.h> /* define for all headers */`
  `#define _System syscall`
  `#define far`
  `!end`

- To define macros which are predefined by a particular C compiler or are used in conditional compilation preprocessor directives (see Conditional compilation):

  `!header <*.h>`
  `#define __WATCOM_C__`
  `#define INCL_DOS`
  `!end`

- To declare type synonyms in order to prevent H2D from automatic type declarations (see Function prototypes and Types):

  `!header <*.h>`
  `typedef char *String /* no more PtrChar */`
  `!end`

- To collect non-standard preprocessor directives in order to keep original header files intact (see Project file contents):

  `!header <string.h>`
  `#variant strlen(0) : ARRAY`
  `!end`

- Example

### Example

The header files `a.h` and `m1.h`:

    /* a.h */
      #include "m1.h"
      #define constant1 0x11u
      __PASCAL function3( float * arg0, unsigned long arg1 );
    /* end a.h */

    /* m1.h */
      #define constant2 0x111u
      __PASCAL function1( float * arg0, float * arg1 );
      function2( unsigned long arg0, unsigned long arg1 );
    /* end m1.h */

with project file `p.h2d`:

    !header "*.h"
      #define __PASCAL pascal
    !end
    !header "a.h"
      #merge "m1.h"
    !end
    !header "m1.h"
      #variant function1 (1) : VAR
      #variant constant2 : BITSET
      #variant function2 (1) : BITSET
    !end
    !module "a.h"

are translated to

    (* ************************ *)
    (*           m1.h           *)
    (* ************************ *)
    CONST
      constant2 = {0, 4, 8};
    <*- GENTYPEDEF *>
    TYPE
      PtrFloat = POINTER TO REAL;
    PROCEDURE ["StdCall"] function1 ( arg0: PtrFloat;
                               VAR arg1: REAL ): SYSTEM.int;
    PROCEDURE function2 ( arg0: LONGCARD; arg1: BITSET ): SYSTEM.int;
    (* *********************** *)
    (*           a.h           *)
    (* *********************** *)
    CONST
      constant1 = 111H;
    PROCEDURE ["StdCall"] function3 ( arg0: PtrFloat;
                                arg1: LONGCARD ): SYSTEM.int;

## Project file contents

A project file may contain options settings and directives. Option settings in a project file override settings in the configuration file.

H2D recognizes the following directives in project files: `!header`, `!module`, and `!name`, which are described is the following sections.

- !header
- !module
- !name

### !header

    !header ( '<' Pattern '>' | '"' Pattern '"' )
      Prologue
    [
    !footer
      Epilogue
    ]
    !end

`Pattern` is a regular expression (see Redirection file) representing a set of file names. `Prologue` and `Epilogue` are arbitrary sequences of C language tokens. `Prologue` is inserted at the beginning of any header file which name matches `Pattern`; `Epilogue` is appended to its end. `!footer` and `Epilogue` may be omitted.

If a header file name matches `Pattern` in more than one `!header` directive, their `Prologue` and `Epilogue` sections are merged.

`Prologue` usually contains:

- `#merge` and `#variant` directives
- Predefined macros of a particular C compiler
- Type synonym declarations to prevent automatic type names generation

Note: If there are `#include` directives in either `Prolodue` or `Epilogue` ensure that names of the included files do not match `Pattern`, to avoid recursive inclusion:

    !header <*.h&^mytypes.h>
    #include <mytypes.h>
    !end

### !module

    !module ( <file_name> | "file_name" )

The `!module` directive is used to specify header files which are to be translated when H2D processes the project file.

Translating more than one header at once has one more advantage. A header file name may occur multiple times in `#include` directives. H2D keeps information about each translated header in memory, and if an already transtaled header file is encountered, it is not processed again. Note: In this case H2D requires more memory.

- Example

#### Example

    !module <ctype.h>
    !module <math.h>
    !module <stdio.h>
    !module <stdlib.h>
    !module <string.h>

### !name

    !name ( '<' file_name '>' | '"' file_name '"' ) identifier

H2D replaces `file_name` with `identifier` when generating module names. This may be useful when `file_name` contains special characters (e.g. `my-header.h`), or when there are headers with equal names in different directories. See also the description of the GENLONGNAMES option.

- Example

#### Example

`!name <errno.h> errno`
`!name <sys\errno.h> syserrno`