Compiler Options#

Compiler options are things you can change to change how the compiler interprets your code. Many of the available options exist for compatibility for older scripts, when things about ZScript worked differently- said options are usually best left at their defaults unless you specifically know what you are doing. Other options are designed specifically to be changable as needed for a variety of purposes, and can be changed at your leisure.

Option Scope#

Different parts of your scripts can use different options. This is accomplished by using the #option compiler directive. The #option directive may be used at function scope or higher, and may only be used at the top of the scope, before any other statements.

If, for example, you’re compiling an older script that relied on the broken integer division behavior that was present in version 2.50, you could put:

#option TRUNCATE_DIVISION_BY_LITERAL_BUG on

at the top of the script that requires the old broken behavior. Then, while compiling that script, the compiler will use the old behavior.

Option Inheritance#

In every scope except the ‘script buffer’ in the editor defaults every single option to the special value inherit.

This means that they will inherit the value for that option from the scope above them. Since the ‘script buffer’ has nothing above it, the options it uses are set in a menu in the editor, ZScript->Compiler Settings. In the table below on this page, the listed ‘Default’ values are what you will see in this menu upon a fresh installation of the program.

You can technically manually set options to inherit, though as it will already be this for every scope, this has no effect. You can also manually set options to the special value default, which will inherit the settings directly from the menu in the editor, ignoring all the scopes above.

What are all the options?#

Standard Options#

Name	Default	Possible Values[1]	Effect
NO_LOGGING	`off`	`on` `off`	All functions that would log to the console are compiled away, producing no code or output.
HEADER_GUARD	`on`	`on` `off` `error` `warn`	Determines what happens when importing a file that was already imported. If `on`, prevents the duplicate import with no error. Can be set to instead prevent it and issue an `error` or `warn`ing.
NO_ERROR_HALT	`off`	`on` `off`	If on, the compiler will keep trying as long as it can, even after it encounters an error. If off, it stops after one error.
APPROX_EQUAL_MARGIN	`0.0100`	numbers in `float` range	The `~~` (approximately equal) operator will return `true` if the difference between its operands is `<=` this value.
STRING_SWITCH_CASE_INSENSITIVE	`off`	`on` `off`	If enabled, switch statements using strings will match the strings case-insensitively.
WARN_DEPRECATED	`off`	`on` `off` `error` `warn`	If `on` or `warn`, issues a warning when using any internal symbol that is marked as `deprecated`. Setting to `error` gives a compile error instead.

Not Yet Implemented

STRING_SWITCH_CASE_INSENSITIVE may become deprecated in favor of an annotation on switch statements instead.

Compatibility Options#

You almost certainly want to leave these in their default state, unless you know what you are doing.

Name	Default	Possible Values[1]	Effect
TRUNCATE_DIVISION_BY_LITERAL_BUG	`off`	`on` `off`	Enables old bug where division specifically by a literal was wrongly truncating, resulting in integer division.
SHORT_CIRCUIT	`on`	`on` `off`	Allows boolean expressions to short-circuit, exiting early if the final answer is already known.
BOOL_TRUE_RETURN_DECIMAL	`off`	`on` `off`	Most boolean `true` values will use the internal representation `0.0001` instead of `1` if this is enabled.
TRUE_INT_SIZE	`on`	`on` `off`	Changes the size range of number literals. If off, their range is `-214747.0000` to `214747.0000`.
BINARY_32BIT	`off`	`on` `off`	Makes bitwise operators treat `int`s the same way they do `long`s. Do not enable this. Just use `long`s instead.