# Options Reference

This chapter contains brief descriptions of all options that may be specified in either configuration file. or project file.

The general option syntax is:

`Option = "-" name ("+" | "-" | "=" (string | integer))`

Option names are case insensitive. Case is preserved when string option values are stored or emitted, but is ignored when they are compared.

Examples

        -mergeall+
        -GENWIDTH=78
        -BackEnd=Common

- File extensions and prefixes
- Translation options
- Base types definition

## File extensions and prefixes

This group of options sets file name extensions and prefixes for H2D input and output files.

Option | Sets extension for... | Default
DEFEXT | definition modules | `def`
DIREXT | directive files | `dir`
HEADEXT | header files | `h`
MODEXT | implementation modules | `mod`
PRJEXT | project files | `h2d`
TREEEXT | include tree files (see the GENTREE option) | `tre`
Option | Sets prefix for... | Default
DEFPFX | definition modules | none
MACPFX | macro prototype modules | _

## Translation options

For each option, a set of possible values is given in parenthesis:

string | an arbitrary sequence of characters
numeric | an unsigned integer number
boolean | ON or OFF

- BACKEND - target compiler back-end
- CHANGEDEF - enable retranslation
- COMMENTPOS - preserved comments position
- CPPCOMMENTS - recognize C++ comments
- CSTDLIB - set CSTDLIB value
- GENDIRS - extract non-standard directives
- GENENUM - enum translation mode
- GENLONGNAMES - keep directory names
- GENMACRO - produce macro prototype modules
- GENROVARS - translate constants to read-only variables
- GENSEP - insert merged headers separators
- GENTREE - generate inclusion tree
- GENWIDTH - limit output line length
- MERGEALL - merge all headers
- PROGRESS - enable progress indicator

### BACKEND - target compiler back-end

(Native/C/Common)

Enables generation of definition modules suitable for either native-code compiler, translator to C, or both. It also affects generation of additional modules (See Fitting a Modula-2 compiler).

Default: `Common` - both native and translator.

### CHANGEDEF - enable retranslation

(boolean)

If this option is set OFF, H2D does not translate a header file if a definition module corresponding to it already exists. Otherwise, H2D produces a new definition module which may overwrite the old one.

See also Redirection file.

Default: OFF - do not process already translated headers

### COMMENTPOS - preserved comments position

(numeric)

Sets starting position of comments preserved by H2D in output files. Has effect only on comments which are placed next to declarations.

Default: delimit comments with a single blank.

### CPPCOMMENTS - recognize C++ comments

(boolean)

If this option is set ON, H2D recognizes C++-style comments (started with `'//'`) in header files.

Default: ON - recognize C++ comments.

### CSTDLIB - set CSTDLIB value

(boolean)

Sets value of the CSTDLIB XDS option in output definition modules corresponding to top-level header files (listed on the command line or in a project file). See Convertor to C for more information.

Default: OFF - set CSTDLIB off in definition modules.

### GENDIRS - extract non-standard directives

(boolean)

If this option is set ON, a file containing non-standard preprocessor directives is produced for each header file.

Deafult: OFF - do not extract non-standard directives

### GENENUM - enum translation mode

(Const/Enum/Mixed)

Defines whether C enumerations should be unconditionally translated to integer constants (`Const`) or Modula-2 enumeration types (`Enum`). If set to `Mixed`, only enumerations with default (or explicitly specified, but matching default) constant values are translated to enumeration types; all other are translated to constants. See also Enumeration.

Default: `Const` - always translate to constants

### GENLONGNAMES - keep directory names

(boolean)

This option controls translation of the `#include` directive in cases when a specified file name contains directories. If this option is set OFF, H2D strips directory names. Otherwise directory names are kept and separators are replaced with underscore characters:

`#include <sys\errno.h> IMPORT sys_errno;`

See also !name.

Default: OFF - strip directory names

### GENMACRO - produce macro prototype modules

(boolean)

Setting this option ON forces H2D to produce prototype modules for function-like C macros encountered in header files (prototype means that implementation modules contain procedures with empty bodies; the actual code has to be written by hand). These modules have not to be imported, but to be added to the link list. See also Native code.

This option is ignored if the target is XDS-C (the BACKEND option is set to `C`).

Default: OFF - do not generate macro modules.

### GENROVARS - translate constants to read-only variables

(boolean)

Being set ON, enables translation of `#define`d constants to read-only variables. Have no effect in native back-end sections. See Preserving constant names for more information.

Default: OFF - do not translate constants to variables.

### GENSEP - insert merged headers separators

(boolean)

Setting this option ON forces H2D to insert a comment containing name of a merged header before declarations from that header.

Default: OFF - do not insert separators

### GENTREE - generate inclusion tree

(boolean)

If this option is set ON, H2D produces a text file containing a tree of `#include` directives for each header file specified on the command line or in a project file using the `!module directive`. A name of a tree file is a name of a corresponding header file with extension defined by the TREEEXT option.

Default: OFF - do not produce tree files

### GENWIDTH - limit output line length

(numeric)

Sets maximum length of a string in the output file.

Default: do not limit string length.

### MERGEALL - merge all headers

(boolean)

If this option is set ON, H2D merges all header files included into the translated header by means of the `#include` directive. If this option is set OFF, H2D generates separate definition module for each header which is not specified in the `#merge` directive.

See also File inclusion and Headers merging.

Default: OFF - do not merge headers which are not specified in the `#merge` directive.

### PROGRESS - enable progress indicator

(boolean)

Setting this option ON enables progress indicator.

Default: OFF - show no progress indicator

## Base types definition

The base types definition and mapping options, CTYPE and M2TYPE, have a special syntax. Either of them may be specified more than once in a project or configuration file, provided that each time a new type is defined. See Base types mapping for more information on usage of these directives.

By default, H2D is configured to support XDS compilers.

- CTYPE - define a C base type
- M2TYPE - define a Modula-2 type

### CTYPE - define a C base type

(special)

This option defines size and default mapping of a C base type.

    CTypeOption = '-' 'CTYPE' '=' Type '=' size ',' qualident
    Type = 'signed char'     | 'unsigned char'      |
           'short int'       | 'unsigned short int' |
           'signed int'      | 'unsigned int'       |
           'signed long int' | 'unsigned long int'  |
           'float'           | 'double'             |
           'long float'      | 'long double'

`size` is the size of `Type` in bytes, and `qualident` is a Modula-2 type to which `Type` should be translated by default:

`-CTYPE = signed char = 1, CHAR`

See Base types mapping for more information.

### M2TYPE - define a Modula-2 type

(special)

This option defines a Modula-2 type.

    M2TypeOption = '-' 'M2TYPE' '=' qualident '=' size ',' Attr
    Attr = 'BOOL'   | 'CHAR' |
           'REAL'   | 'SET'  |
           'SIGNED' | 'UNSIGNED'

`qualident` is a Modula-2 type being defined, `size` is its size in bytes, and `Attr` is a family to which it belongs:

`-M2TYPE = SYSTEM.INT16 = 2, SIGNED`

See Base types mapping for more information.